genshi/mirror: doc/text-templates.txt annotate

annotate doc/text-templates.txt @ 820:9755836bb396 experimental-inline

Sync (old) experimental inline branch with trunk@1027.

author	cmlenz
date	Wed, 11 Mar 2009 17:51:06 +0000
parents	3eb30e4ece8c
children

rev	line source
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	1 .. -- mode: rst; encoding: utf-8 --
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	2
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	3 =============================
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	4 Genshi Text Template Language
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	5 =============================
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	6
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	7 In addition to the XML-based template language, Genshi provides a simple
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	8 text-based template language, intended for basic plain text generation needs.
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	9 The language is similar to the Django_ template language.
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	10
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	11 This document describes the template language and will be most useful as
500 3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	12 reference to those developing Genshi text templates. Templates are text files of
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	13 some kind that include processing directives_ that affect how the template is
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	14 rendered, and template expressions that are dynamically substituted by
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	15 variable data.
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	16
500 3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	17 See `Genshi Templating Basics <templates.html>`_ for general information on
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	18 embedding Python code in templates.
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	19
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	20 .. note:: Actually, Genshi currently has two different syntaxes for text
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	21 templates languages: One implemented by the class ``OldTextTemplate``
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	22 and another implemented by ``NewTextTemplate``. This documentation
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	23 concentrates on the latter, which is planned to completely replace the
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	24 older syntax. The older syntax is briefly described under legacy_.
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	25
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	26 .. _django: http://www.djangoproject.com/
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	27
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	28 .. contents:: Contents
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	29 :depth: 3
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	30 .. sectnum::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	31
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	32
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	33 .. _`directives`:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	34
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	35 -------------------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	36 Template Directives
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	37 -------------------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	38
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	39 Directives are template commands enclosed by ``{% ... %}`` characters. They can
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	40 affect how the template is rendered in a number of ways: Genshi provides
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	41 directives for conditionals and looping, among others.
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	42
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	43 Each directive must be terminated using an ``{% end %}`` marker. You can add
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	44 a string inside the ``{% end %}`` marker, for example to document which
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	45 directive is being closed, or even the expression associated with that
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	46 directive. Any text after ``end`` inside the delimiters is ignored, and
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	47 effectively treated as a comment.
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	48
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	49 If you want to include a literal delimiter in the output, you need to escape it
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	50 by prepending a backslash character (``\``).
244 fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	51
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	52
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	53 Conditional Sections
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	54 ====================
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	55
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	56 .. _`if`:
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	57
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	58 ``{% if %}``
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	59 ------------
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	60
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	61 The content is only rendered if the expression evaluates to a truth value:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	62
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	63 .. code-block:: genshitext
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	64
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	65 {% if foo %}
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	66 ${bar}
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	67 {% end %}
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	68
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	69 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	70 would produce::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	71
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	72 Hello
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	73
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	74
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	75 .. _`choose`:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	76 .. _`when`:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	77 .. _`otherwise`:
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	78
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	79 ``{% choose %}``
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	80 ----------------
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	81
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	82 The ``choose`` directive, in combination with the directives ``when`` and
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	83 ``otherwise``, provides advanced contional processing for rendering one of
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	84 several alternatives. The first matching ``when`` branch is rendered, or, if
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	85 no ``when`` branch matches, the ``otherwise`` branch is be rendered.
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	86
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	87 If the ``choose`` directive has no argument the nested ``when`` directives will
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	88 be tested for truth:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	89
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	90 .. code-block:: genshitext
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	91
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	92 The answer is:
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	93 {% choose %}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	94 {% when 0 == 1 %}0{% end %}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	95 {% when 1 == 1 %}1{% end %}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	96 {% otherwise %}2{% end %}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	97 {% end %}
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	98
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	99 This would produce the following output::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	100
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	101 The answer is:
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	102 1
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	103
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	104 If the ``choose`` does have an argument, the nested ``when`` directives will
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	105 be tested for equality to the parent ``choose`` value:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	106
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	107 .. code-block:: genshitext
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	108
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	109 The answer is:
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	110 {% choose 1 %}\
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	111 {% when 0 %}0{% end %}\
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	112 {% when 1 %}1{% end %}\
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	113 {% otherwise %}2{% end %}\
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	114 {% end %}
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	115
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	116 This would produce the following output::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	117
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	118 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	119 1
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	120
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	121
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	122 Looping
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	123 =======
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	124
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	125 .. _`for`:
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	126
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	127 ``{% for %}``
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	128 -------------
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	129
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	130 The content is repeated for every item in an iterable:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	131
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	132 .. code-block:: genshitext
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	133
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	134 Your items:
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	135 {% for item in items %}\
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	136 * ${item}
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	137 {% end %}
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	138
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	139 Given ``items=[1, 2, 3]`` in the context data, this would produce::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	140
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	141 Your items
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	142 * 1
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	143 * 2
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	144 * 3
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	145
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	146
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	147 Snippet Reuse
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	148 =============
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	149
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	150 .. _`def`:
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	151 .. _`macros`:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	152
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	153 ``{% def %}``
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	154 -------------
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	155
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	156 The ``def`` directive can be used to create macros, i.e. snippets of template
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	157 text that have a name and optionally some parameters, and that can be inserted
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	158 in other places:
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	159
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	160 .. code-block:: genshitext
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	161
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	162 {% def greeting(name) %}
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	163 Hello, ${name}!
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	164 {% end %}
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	165 ${greeting('world')}
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	166 ${greeting('everyone else')}
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	167
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	168 The above would be rendered to::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	169
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	170 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	171 Hello, everyone else!
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	172
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	173 If a macro doesn't require parameters, it can be defined without the
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	174 parenthesis. For example:
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	175
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	176 .. code-block:: genshitext
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	177
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	178 {% def greeting %}
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	179 Hello, world!
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	180 {% end %}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	181 ${greeting()}
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	182
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	183 The above would be rendered to::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	184
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	185 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	186
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	187
500 3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	188 .. _includes:
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	189 .. _`include`:
500 3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	190
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	191 ``{% include %}``
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	192 -----------------
500 3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	193
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	194 To reuse common parts of template text across template files, you can include
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	195 other files using the ``include`` directive:
500 3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	196
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	197 .. code-block:: genshitext
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	198
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	199 {% include base.txt %}
500 3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	200
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	201 Any content included this way is inserted into the generated output. The
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	202 included template sees the context data as it exists at the point of the
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	203 include. `Macros`_ in the included template are also available to the including
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	204 template after the point it was included.
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	205
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	206 Include paths are relative to the filename of the template currently being
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	207 processed. So if the example above was in the file "``myapp/mail.txt``"
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	208 (relative to the template search path), the include directive would look for
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	209 the included file at "``myapp/base.txt``". You can also use Unix-style
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	210 relative paths, for example "``../base.txt``" to look in the parent directory.
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	211
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	212 Just like other directives, the argument to the ``include`` directive accepts
500 3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	213 any Python expression, so the path to the included template can be determined
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	214 dynamically:
500 3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	215
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	216 .. code-block:: genshitext
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	217
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	218 {% include ${'%s.txt' % filename} %}
500 3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	219
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	220 Note that a ``TemplateNotFound`` exception is raised if an included file can't
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	221 be found.
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	222
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	223 .. note:: The include directive for text templates was added in Genshi 0.5.
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	224
3eb30e4ece8c Merged revisions 487-603 via svnmerge from cmlenz parents: 395 diff changeset	225
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	226 Variable Binding
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	227 ================
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	228
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	229 .. _`with`:
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	230
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	231 ``{% with %}``
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	232 --------------
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	233
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	234 The ``{% with %}`` directive lets you assign expressions to variables, which can
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	235 be used to make expressions inside the directive less verbose and more
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	236 efficient. For example, if you need use the expression ``author.posts`` more
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	237 than once, and that actually results in a database query, assigning the results
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	238 to a variable using this directive would probably help.
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	239
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	240 For example:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	241
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	242 .. code-block:: genshitext
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	243
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	244 Magic numbers!
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	245 {% with y=7; z=x+10 %}
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	246 $x $y $z
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	247 {% end %}
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	248
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	249 Given ``x=42`` in the context data, this would produce::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	250
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	251 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	252 42 7 52
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	253
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	254 Note that if a variable of the same name already existed outside of the scope
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	255 of the ``with`` directive, it will not be overwritten. Instead, it will
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	256 have the same value it had prior to the ``with`` assignment. Effectively,
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	257 this means that variables are immutable in Genshi.
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	258
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	259
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	260 .. _whitespace:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	261
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	262 ---------------------------
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	263 White-space and Line Breaks
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	264 ---------------------------
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	265
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	266 Note that space or line breaks around directives is never automatically removed.
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	267 Consider the following example:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	268
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	269 .. code-block:: genshitext
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	270
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	271 {% for item in items %}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	272 {% if item.visible %}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	273 ${item}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	274 {% end %}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	275 {% end %}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	276
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	277 This will result in two empty lines above and beneath every item, plus the
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	278 spaces used for indentation. If you want to supress a line break, simply end
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	279 the line with a backslash:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	280
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	281 .. code-block:: genshitext
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	282
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	283 {% for item in items %}\
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	284 {% if item.visible %}\
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	285 ${item}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	286 {% end %}\
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	287 {% end %}\
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	288
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	289 Now there would be no empty lines between the items in the output. But you still
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	290 get the spaces used for indentation, and because the line breaks are removed,
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	291 they actually continue and add up between lines. There are numerous ways to
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	292 control white-space in the output while keeping the template readable, such as
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	293 moving the indentation into the delimiters, or moving the end delimiter on the
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	294 next line, and so on.
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	295
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	296
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	297 .. _comments:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	298
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	299 --------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	300 Comments
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	301 --------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	302
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	303 Parts in templates can be commented out using the delimiters ``{# ... #}``.
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	304 Any content in comments are removed from the output.
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	305
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	306 .. code-block:: genshitext
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	307
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	308 {# This won't end up in the output #}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	309 This will.
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	310
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	311 Just like directive delimiters, these can be escaped by prefixing with a
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	312 backslash.
820 9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	313
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	314 .. code-block:: genshitext
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	315
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	316 \{# This will end up in the output, including delimiters #}
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	317 This too.
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	318
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	319
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	320 .. _legacy:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	321
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	322 ---------------------------
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	323 Legacy Text Template Syntax
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	324 ---------------------------
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	325
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	326 The syntax for text templates was redesigned in version 0.5 of Genshi to make
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	327 the language more flexible and powerful. The older syntax is based on line
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	328 starting with dollar signs, similar to e.g. Cheetah_ or Velocity_.
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	329
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	330 .. _cheetah: http://cheetahtemplate.org/
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	331 .. _velocity: http://jakarta.apache.org/velocity/
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	332
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	333 A simple template using the old syntax looked like this:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	334
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	335 .. code-block:: genshitext
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	336
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	337 Dear $name,
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	338
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	339 We have the following items for you:
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	340 #for item in items
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	341 * $item
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	342 #end
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	343
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	344 All the best,
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	345 Foobar
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	346
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	347 Beyond the requirement of putting directives on separate lines prefixed with
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	348 dollar signs, the language itself is very similar to the new one. Except that
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	349 comments are lines that start with two ``#`` characters, and a line-break at the
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	350 end of a directive is removed automatically.
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	351
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	352 .. note:: If you're using this old syntax, it is strongly recommended to
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	353 migrate to the new syntax. Simply replace any references to
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	354 ``TextTemplate`` by ``NewTextTemplate`` (and also change the
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	355 text templates, of course). On the other hand, if you want to stick
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	356 with the old syntax for a while longer, replace references to
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	357 ``TextTemplate`` by ``OldTextTemplate``; while ``TextTemplate`` is
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	358 still an alias for the old language at this point, that will change
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	359 in a future release. But also note that the old syntax may be
9755836bb396 Sync (old) experimental inline branch with trunk@1027. cmlenz parents: 500 diff changeset	360 dropped entirely in a future release.

Mercurial > genshi > mirror

annotate doc/text-templates.txt @ 820:9755836bb396 experimental-inline