Mercurial > genshi > mirror

annotate doc/text-templates.txt @ 693:35e143388705 trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Enable use of expressions in include directives of text templates. Closes #194. Thanks to Oliver Cope for reporting the issue.
author cmlenz
date Mon, 17 Mar 2008 11:09:56 +0000
parents 1da8de3e5e51
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.
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
442
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
12 reference to those developing Genshi text templates. Templates are text files of
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
13 some kind that include processing directives_ that affect how the template is
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
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
442
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
17 See `Genshi Templating Basics <templates.html>`_ for general information on
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
18 embedding Python code in templates.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
19
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
20 .. note:: Actually, Genshi currently has two different syntaxes for text
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
21 templates languages: One implemented by the class ``OldTextTemplate``
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
22 and another implemented by ``NewTextTemplate``. This documentation
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
23 concentrates on the latter, which is planned to completely replace the
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
24 older syntax. The older syntax is briefly described under legacy_.
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
25
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
39 Directives are template commands enclosed by ``{% ... %}`` characters. They can
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
40 affect how the template is rendered in a number of ways: Genshi provides
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
43 Each directive must be terminated using an ``{% end %}`` marker. You can add
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
44 a string inside the ``{% end %}`` marker, for example to document which
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
45 directive is being closed, or even the expression associated with that
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
46 directive. Any text after ``end`` inside the delimiters is ignored, and
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
47 effectively treated as a comment.
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
48
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
49 If you want to include a literal delimiter in the output, you need to escape it
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
56 .. _`if`:
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
57
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
58 ``{% if %}``
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
59 ------------
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
60
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
61 The content is only rendered if the expression evaluates to a truth value:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
62
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
63 .. code-block:: genshitext
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
64
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
65 {% if foo %}
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
66 ${bar}
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
75 .. _`choose`:
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
76 .. _`when`:
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
77 .. _`otherwise`:
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
78
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
79 ``{% choose %}``
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
80 ----------------
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
81
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
82 The ``choose`` directive, in combination with the directives ``when`` and
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
83 ``otherwise``, provides advanced contional processing for rendering one of
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
84 several alternatives. The first matching ``when`` branch is rendered, or, if
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
85 no ``when`` branch matches, the ``otherwise`` branch is be rendered.
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
86
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
87 If the ``choose`` directive has no argument the nested ``when`` directives will
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
88 be tested for truth:
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
89
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
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:
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
93 {% choose %}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
94 {% when 0 == 1 %}0{% end %}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
95 {% when 1 == 1 %}1{% end %}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
96 {% otherwise %}2{% end %}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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:
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
102 1
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
103
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
104 If the ``choose`` does have an argument, the nested ``when`` directives will
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
105 be tested for equality to the parent ``choose`` value:
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
106
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
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:
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
110 {% choose 1 %}\
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
111 {% when 0 %}0{% end %}\
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
112 {% when 1 %}1{% end %}\
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
113 {% otherwise %}2{% end %}\
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
125 .. _`for`:
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
126
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
127 ``{% for %}``
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
128 -------------
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
129
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
130 The content is repeated for every item in an iterable:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
131
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
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:
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
135 {% for item in items %}\
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
136 * ${item}
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
153 ``{% def %}``
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
154 -------------
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
155
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
158 in other places:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
159
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
160 .. code-block:: genshitext
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
161
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
162 {% def greeting(name) %}
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
163 Hello, ${name}!
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
173 If a macro doesn't require parameters, it can be defined without the
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
174 parenthesis. For example:
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
175
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
176 .. code-block:: genshitext
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
177
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
178 {% def greeting %}
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
179 Hello, world!
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
180 {% end %}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
477
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
188 .. _includes:
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
189 .. _`include`:
477
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
190
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
191 ``{% include %}``
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
192 -----------------
477
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
193
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
194 To reuse common parts of template text across template files, you can include
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
195 other files using the ``include`` directive:
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
196
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
197 .. code-block:: genshitext
477
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
198
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
199 {% include base.txt %}
477
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
200
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
201 Any content included this way is inserted into the generated output. The
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
202 included template sees the context data as it exists at the point of the
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
203 include. `Macros`_ in the included template are also available to the including
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
204 template after the point it was included.
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
205
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
206 Include paths are relative to the filename of the template currently being
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
207 processed. So if the example above was in the file "``myapp/mail.txt``"
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
208 (relative to the template search path), the include directive would look for
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
209 the included file at "``myapp/base.txt``". You can also use Unix-style
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
210 relative paths, for example "``../base.txt``" to look in the parent directory.
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
211
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
212 Just like other directives, the argument to the ``include`` directive accepts
477
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
213 any Python expression, so the path to the included template can be determined
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
214 dynamically:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
215
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
216 .. code-block:: genshitext
477
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
217
693
35e143388705 Enable use of expressions in include directives of text templates. Closes #194. Thanks to Oliver Cope for reporting the issue.
cmlenz
parents: 592
diff changeset
218 {% include ${'%s.txt' % filename} %}
477
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
219
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
220 Note that a ``TemplateNotFound`` exception is raised if an included file can't
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
221 be found.
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
222
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
223 .. note:: The include directive for text templates was added in Genshi 0.5.
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
224
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
229 .. _`with`:
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
230
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
231 ``{% with %}``
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
232 --------------
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
233
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
240 For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
241
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
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!
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
255 of the ``with`` directive, it will **not** be overwritten. Instead, it will
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
260 .. _whitespace:
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
261
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
262 ---------------------------
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
263 White-space and Line Breaks
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
264 ---------------------------
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
265
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
266 Note that space or line breaks around directives is never automatically removed.
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
267 Consider the following example:
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
268
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
269 .. code-block:: genshitext
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
270
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
271 {% for item in items %}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
272 {% if item.visible %}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
273 ${item}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
274 {% end %}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
275 {% end %}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
276
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
277 This will result in two empty lines above and beneath every item, plus the
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
278 spaces used for indentation. If you want to supress a line break, simply end
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
279 the line with a backslash:
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
280
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
281 .. code-block:: genshitext
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
282
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
283 {% for item in items %}\
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
284 {% if item.visible %}\
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
285 ${item}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
286 {% end %}\
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
287 {% end %}\
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
288
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
289 Now there would be no empty lines between the items in the output. But you still
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
290 get the spaces used for indentation, and because the line breaks are removed,
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
291 they actually continue and add up between lines. There are numerous ways to
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
292 control white-space in the output while keeping the template readable, such as
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
293 moving the indentation into the delimiters, or moving the end delimiter on the
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
294 next line, and so on.
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
295
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
303 Parts in templates can be commented out using the delimiters ``{# ... #}``.
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
304 Any content in comments are removed from the output.
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
305
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
306 .. code-block:: genshitext
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
307
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
308 {# This won't end up in the output #}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
309 This will.
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
310
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
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.
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
313
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
314 .. code-block:: genshitext
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
315
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
316 \{# This *will* end up in the output, including delimiters #}
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
317 This too.
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
318
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
319
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
320 .. _legacy:
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
321
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
322 ---------------------------
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
323 Legacy Text Template Syntax
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
324 ---------------------------
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
325
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
326 The syntax for text templates was redesigned in version 0.5 of Genshi to make
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
327 the language more flexible and powerful. The older syntax is based on line
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
328 starting with dollar signs, similar to e.g. Cheetah_ or Velocity_.
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
329
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
330 .. _cheetah: http://cheetahtemplate.org/
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
331 .. _velocity: http://jakarta.apache.org/velocity/
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
332
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
333 A simple template using the old syntax looked like this:
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
334
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
335 .. code-block:: genshitext
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
336
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
337 Dear $name,
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
338
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
339 We have the following items for you:
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
340 #for item in items
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
341 * $item
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
342 #end
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
343
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
344 All the best,
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
345 Foobar
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
346
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
347 Beyond the requirement of putting directives on separate lines prefixed with
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
348 dollar signs, the language itself is very similar to the new one. Except that
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
349 comments are lines that start with two ``#`` characters, and a line-break at the
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
350 end of a directive is removed automatically.
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
351
693
35e143388705 Enable use of expressions in include directives of text templates. Closes #194. Thanks to Oliver Cope for reporting the issue.
cmlenz
parents: 592
diff changeset
352 .. note:: If you're using this old syntax, it is strongly recommended to
35e143388705 Enable use of expressions in include directives of text templates. Closes #194. Thanks to Oliver Cope for reporting the issue.
cmlenz
parents: 592
diff changeset
353 migrate to the new syntax. Simply replace any references to
35e143388705 Enable use of expressions in include directives of text templates. Closes #194. Thanks to Oliver Cope for reporting the issue.
cmlenz
parents: 592
diff changeset
354 ``TextTemplate`` by ``NewTextTemplate`` (and also change the
35e143388705 Enable use of expressions in include directives of text templates. Closes #194. Thanks to Oliver Cope for reporting the issue.
cmlenz
parents: 592
diff changeset
355 text templates, of course). On the other hand, if you want to stick
35e143388705 Enable use of expressions in include directives of text templates. Closes #194. Thanks to Oliver Cope for reporting the issue.
cmlenz
parents: 592
diff changeset
356 with the old syntax for a while longer, replace references to
592
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
357 ``TextTemplate`` by ``OldTextTemplate``; while ``TextTemplate`` is
1da8de3e5e51 Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 510
diff changeset
358 still an alias for the old language at this point, that will change
693
35e143388705 Enable use of expressions in include directives of text templates. Closes #194. Thanks to Oliver Cope for reporting the issue.
cmlenz
parents: 592
diff changeset
359 in a future release. But also note that the old syntax may be
35e143388705 Enable use of expressions in include directives of text templates. Closes #194. Thanks to Oliver Cope for reporting the issue.
cmlenz
parents: 592
diff changeset
360 dropped entirely in a future release.
Copyright (C) 2012-2017 Edgewall Software