Mercurial > genshi > genshi-test

annotate doc/text-templates.txt @ 938:a5a1c9a11135 tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
update tags
author convert-repo
date Tue, 31 May 2011 20:05:15 +0000
parents fa8a55fe2d57
children
rev   line source
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
2
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
3 =============================
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
4 Genshi Text Template Language
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
5 =============================
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
6
bbed6d426678 * 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
bbed6d426678 * 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
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
10
bbed6d426678 * 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
ff7c72b52fb2 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
ff7c72b52fb2 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
ff7c72b52fb2 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
15 variable data.
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
16
442
ff7c72b52fb2 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
ff7c72b52fb2 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.
ff7c72b52fb2 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
7145e4eba2ec 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
7145e4eba2ec 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``
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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_.
7145e4eba2ec 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
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
27
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
28 .. contents:: Contents
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
29 :depth: 3
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
30 .. sectnum::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
31
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
32
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
33 .. _`directives`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
34
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
35 -------------------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
36 Template Directives
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
37 -------------------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
38
592
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
42
592
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
48
592
7145e4eba2ec 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
7145e4eba2ec 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
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
51
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
52
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
53 Conditional Sections
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
54 ====================
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
55
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
57
592
7145e4eba2ec 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 %}``
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
60
510
ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
62
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
63 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
64
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
66 ${bar}
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
68
bbed6d426678 * 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
70 would produce::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
71
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
72 Hello
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
73
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
74
592
7145e4eba2ec 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`:
7145e4eba2ec 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`:
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
78
592
7145e4eba2ec 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 %}``
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
81
592
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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.
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
89
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
90 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
91
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
92 The answer is:
592
7145e4eba2ec 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 %}
7145e4eba2ec 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 %}
7145e4eba2ec 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 %}
7145e4eba2ec 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 %}
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
98
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
99 This would produce the following output::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
100
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
101 The answer is:
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
103
592
7145e4eba2ec 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
7145e4eba2ec 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
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
106
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
107 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
108
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
109 The answer is:
592
7145e4eba2ec 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 %}\
7145e4eba2ec 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 %}\
7145e4eba2ec 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 %}\
7145e4eba2ec 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 %}\
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
115
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
116 This would produce the following output::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
117
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
118 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
119 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
120
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
121
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
122 Looping
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
123 =======
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
124
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
126
592
7145e4eba2ec 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 %}``
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
129
510
ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
131
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
132 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
133
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
134 Your items:
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
136 * ${item}
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
138
bbed6d426678 * 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::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
140
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
141 Your items
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
142 * 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
143 * 2
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
144 * 3
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
145
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
146
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
147 Snippet Reuse
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
148 =============
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
149
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
151 .. _`macros`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
152
592
7145e4eba2ec 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 %}``
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
155
592
7145e4eba2ec 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
bbed6d426678 * 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
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
158 in other places:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
159
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
160 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
161
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
163 Hello, ${name}!
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
165 ${greeting('world')}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
166 ${greeting('everyone else')}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
167
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
168 The above would be rendered to::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
169
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
170 Hello, world!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
171 Hello, everyone else!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
172
592
7145e4eba2ec 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
7145e4eba2ec 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
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
175
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
176 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
177
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
179 Hello, world!
592
7145e4eba2ec 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 %}
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
182
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
183 The above would be rendered to::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
184
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
185 Hello, world!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
186
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
187
477
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
188 .. _includes:
592
7145e4eba2ec 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
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
190
592
7145e4eba2ec 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 %}``
7145e4eba2ec 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
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
193
2abf0a19058b 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
7145e4eba2ec 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
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
196
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
197 .. code-block:: genshitext
477
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
198
592
7145e4eba2ec 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
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
200
2abf0a19058b 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
2abf0a19058b 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
2abf0a19058b 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
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
204 template after the point it was included.
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
205
2abf0a19058b 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
2abf0a19058b 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``"
2abf0a19058b 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
2abf0a19058b 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
2abf0a19058b 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.
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
211
592
7145e4eba2ec 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
2abf0a19058b 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
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
214 dynamically:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
215
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
216 .. code-block:: genshitext
477
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
217
693
fa8a55fe2d57 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
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
219
2abf0a19058b 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
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
221 be found.
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
222
2abf0a19058b 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.
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
224
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
225
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
226 Variable Binding
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
227 ================
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
228
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
230
592
7145e4eba2ec 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 %}``
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
233
592
7145e4eba2ec 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
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
238 to a variable using this directive would probably help.
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
239
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
240 For example:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
241
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
242 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
243
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
244 Magic numbers!
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
246 $x $y $z
592
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
248
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
249 Given ``x=42`` in the context data, this would produce::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
250
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
251 Magic numbers!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
252 42 7 52
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
253
bbed6d426678 * 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
7145e4eba2ec 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
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
257 this means that variables are immutable in Genshi.
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
258
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
259
592
7145e4eba2ec 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:
7145e4eba2ec 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
7145e4eba2ec 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 ---------------------------
7145e4eba2ec 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
7145e4eba2ec 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 ---------------------------
7145e4eba2ec 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
7145e4eba2ec 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.
7145e4eba2ec 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:
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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 %}
7145e4eba2ec 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 %}
7145e4eba2ec 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}
7145e4eba2ec 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 %}
7145e4eba2ec 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 %}
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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:
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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 %}\
7145e4eba2ec 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 %}\
7145e4eba2ec 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}
7145e4eba2ec 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 %}\
7145e4eba2ec 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 %}\
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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,
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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.
7145e4eba2ec 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
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
297 .. _comments:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
298
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
299 --------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
300 Comments
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
301 --------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
302
592
7145e4eba2ec 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 ``{# ... #}``.
7145e4eba2ec 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.
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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 #}
7145e4eba2ec 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.
7145e4eba2ec 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
7145e4eba2ec 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
312 backslash.
592
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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 #}
7145e4eba2ec 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.
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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:
7145e4eba2ec 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
7145e4eba2ec 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 ---------------------------
7145e4eba2ec 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
7145e4eba2ec 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 ---------------------------
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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_.
7145e4eba2ec 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
7145e4eba2ec 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/
7145e4eba2ec 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/
7145e4eba2ec 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
7145e4eba2ec 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:
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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,
7145e4eba2ec 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
7145e4eba2ec 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:
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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,
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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
7145e4eba2ec 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.
7145e4eba2ec 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
fa8a55fe2d57 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
fa8a55fe2d57 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
fa8a55fe2d57 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
fa8a55fe2d57 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
fa8a55fe2d57 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
7145e4eba2ec 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
7145e4eba2ec 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
fa8a55fe2d57 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
fa8a55fe2d57 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