Mercurial > genshi > genshi-test
annotate doc/text-templates.txt @ 771:b4c973fbe6f5
Unbuffered match templates could result in parts of the matched content being included in the output if the match template didn't actually consume it via one or more calls to the `select()` function. Closes #243. Thanks to Felix Schwarz for the report and test case.
author | cmlenz |
---|---|
date | Mon, 07 Jul 2008 16:35:06 +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 | 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. |