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

annotate doc/text-templates.txt @ 427:55c574767df2 trunk

More API documentation.

author	cmlenz
date	Thu, 22 Mar 2007 15:05:29 +0000
parents	cab6b0256019
children	691dd56c0dd0 3eb30e4ece8c

rev	line source
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	1 .. -- mode: rst; encoding: utf-8 --
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	2
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	3 =============================
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	4 Genshi Text Template Language
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	5 =============================
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	6
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	7 In addition to the XML-based template language, Genshi provides a simple
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	8 text-based template language, intended for basic plain text generation needs.
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	9 The language is similar to Cheetah_ or Velocity_.
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	10
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	11 .. _cheetah: http://cheetahtemplate.org/
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	12 .. _velocity: http://jakarta.apache.org/velocity/
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	13
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	14 This document describes the template language and will be most useful as
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	15 reference to those developing Genshi text templates. Templates are XML files of some
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	16 kind (such as XHTML) that include processing directives_ (elements or
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	17 attributes identified by a separate namespace) that affect how the template is
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	18 rendered, and template expressions_ that are dynamically substituted by
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	19 variable data.
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	20
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	21
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	22 .. contents:: Contents
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	23 :depth: 3
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	24 .. sectnum::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	25
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	26 ----------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	27 Python API
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	28 ----------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	29
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	30 The Python code required for templating with Genshi is generally based on the
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	31 following pattern:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	32
244 fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	33 * Attain a ``TextTemplate`` object from a string or file object containing the
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	34 template source. This can either be done directly, or through a
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	35 ``TemplateLoader`` instance.
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	36 * Call the ``generate()`` method of the template, passing any data that should
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	37 be made available to the template as keyword arguments.
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	38 * Serialize the resulting stream using its ``render()`` method.
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	39
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	40 For example::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	41
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	42 from genshi.template import TextTemplate
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	43
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	44 tmpl = TextTemplate('$title')
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	45 stream = tmpl.generate(title='Hello, world!')
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	46 print stream.render('text')
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	47
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	48 That code would produce the following output::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	49
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	50 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	51
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	52 Using a template loader provides the advantage that “compiled” templates are
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	53 automatically cached, and only parsed again when the template file changes::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	54
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	55 from genshi.template import TemplateLoader
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	56
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	57 loader = TemplateLoader([templates_dir])
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	58 tmpl = loader.load('test.txt' cls=TextTemplate)
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	59 stream = tmpl.generate(title='Hello, world!')
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	60 print stream.render('text')
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	61
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	62
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	63 .. _`expressions`:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	64
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	65 --------------------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	66 Template Expressions
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	67 --------------------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	68
244 fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	69 Python_ expressions can be used in text and as arguments to directives_. An expression is substituted with the result of its evaluation against the
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	70 template data. Expressions need to prefixed with a dollar sign (``$``) and
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	71 usually enclosed in curly braces (``{…}``).
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	72
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	73 .. _python: http://www.python.org/
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	74
394 cab6b0256019 Minor doc fixes. cmlenz parents: 354 diff changeset	75 If the expression starts with a letter and contains only letters, digits, dots,
cab6b0256019 Minor doc fixes. cmlenz parents: 354 diff changeset	76 and underscores, the curly braces may be omitted. In all other cases, the
cab6b0256019 Minor doc fixes. cmlenz parents: 354 diff changeset	77 braces are required so that the template processor knows where the expression
cab6b0256019 Minor doc fixes. cmlenz parents: 354 diff changeset	78 ends::
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	79
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	80 >>> from genshi.template import TextTemplate
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	81 >>> tmpl = TextTemplate('${items[0].capitalize()} item')
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	82 >>> print tmpl.generate(items=['first', 'second'])
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	83 First item
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	84
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	85 Expressions support the full power of Python. In addition, it is possible to
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	86 access items in a dictionary using “dotted notation” (i.e. as if they were
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	87 attributes), and vice-versa (i.e. access attributes as if they were items in
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	88 a dictionary)::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	89
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	90 >>> from genshi.template import TextTemplate
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	91 >>> tmpl = TextTemplate('${dict.foo}')
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	92 >>> print tmpl.generate(dict={'foo': 'bar'})
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	93 bar
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	94
244 fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	95 Another difference is that you can access variables that are not defined, and
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	96 won't get a ``NameError`` exception::
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	97
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	98 >>> from genshi.template import TextTemplate
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	99 >>> tmpl = TextTemplate('${doh}')
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	100 >>> print tmpl.generate()
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	101 <BLANKLINE>
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	102
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	103 You will however get a ``NameError`` if you try to call an undefined
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	104 variable, or do anything else with it, such as accessing its attributes. If you
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	105 need to know whether a variable is defined, you can check its type against the
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	106 ``Undefined`` class, for example in an `#if`_ directive::
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	107
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	108 >>> from genshi.template import TextTemplate
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	109 >>> tmpl = TextTemplate('${type(doh) is Undefined}')
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	110 >>> print tmpl.generate()
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	111 True
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	112
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	113
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	114 .. _`directives`:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	115
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	116 -------------------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	117 Template Directives
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	118 -------------------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	119
354 6951db75824e Remove unused code from text template plugin. cmlenz parents: 246 diff changeset	120 Directives are lines starting with a ``#`` character followed immediately by
6951db75824e Remove unused code from text template plugin. cmlenz parents: 246 diff changeset	121 the directive name. They can affect how the template is rendered in a number of
244 fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	122 ways: Genshi provides directives for conditionals and looping, among others.
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	123
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	124 Directives must be on separate lines, and the ``#`` character must be be the
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	125 first non-whitespace character on that line. Each directive must be “closed”
246 c7dd64bcde9c Document that `#end` markers in text templates can be used as comments. cmlenz parents: 244 diff changeset	126 using a ``#end`` marker. You can add after the ``#end`` marker, for example to
c7dd64bcde9c Document that `#end` markers in text templates can be used as comments. cmlenz parents: 244 diff changeset	127 document which directive is being closed, or even the expression associated with
c7dd64bcde9c Document that `#end` markers in text templates can be used as comments. cmlenz parents: 244 diff changeset	128 that directive. Any text after ``#end`` (but on the same line) is ignored,
c7dd64bcde9c Document that `#end` markers in text templates can be used as comments. cmlenz parents: 244 diff changeset	129 and effectively treated as a comment.
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	130
244 fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	131 If you want to include a literal ``#`` in the output, you need to escape it
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	132 by prepending a backslash character (``\``). Note that this is not required
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	133 if the ``#`` isn't immediately followed by a letter, or it isn't the first
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	134 non-whitespace character on the line.
fa07ab5a7e53 Fixes for the text template docs. cmlenz parents: 241 diff changeset	135
241 4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	136
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	137 Conditional Sections
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	138 ====================
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	139
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	140 .. _`#if`:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	141
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	142 ``#if``
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	143 ---------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	144
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	145 The content is only rendered if the expression evaluates to a truth value::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	146
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	147 #if foo
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	148 ${bar}
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	149 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	150
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	151 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	152 would produce::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	153
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	154 Hello
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	155
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	156
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	157 .. _`#choose`:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	158 .. _`#when`:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	159 .. _`#otherwise`:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	160
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	161 ``#choose``
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	162 -------------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	163
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	164 The ``#choose`` directive, in combination with the directives ``#when`` and
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	165 ``#otherwise`` provides advanced contional processing for rendering one of
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	166 several alternatives. The first matching ``#when`` branch is rendered, or, if
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	167 no ``#when`` branch matches, the ``#otherwise`` branch is be rendered.
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	168
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	169 If the ``#choose`` directive has no argument the nested ``#when`` directives
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	170 will be tested for truth::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	171
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	172 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	173 #choose
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	174 #when 0 == 1
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	175 0
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	176 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	177 #when 1 == 1
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	178 1
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	179 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	180 #otherwise
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	181 2
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	182 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	183 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	184
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	185 This would produce the following output::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	186
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	187 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	188 1
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	189
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	190 If the ``#choose`` does have an argument, the nested ``#when`` directives will
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	191 be tested for equality to the parent ``#choose`` value::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	192
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	193 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	194 #choose 1
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	195 #when 0
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	196 0
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	197 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	198 #when 1
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	199 1
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	200 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	201 #otherwise
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	202 2
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	203 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	204 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	205
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	206 This would produce the following output::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	207
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	208 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	209 1
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	210
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	211
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	212 Looping
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	213 =======
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	214
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	215 .. _`#for`:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	216
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	217 ``#for``
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	218 ----------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	219
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	220 The content is repeated for every item in an iterable::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	221
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	222 Your items:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	223 #for item in items
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	224 * ${item}
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	225 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	226
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	227 Given ``items=[1, 2, 3]`` in the context data, this would produce::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	228
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	229 Your items
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	230 * 1
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	231 * 2
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	232 * 3
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	233
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	234
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	235 Snippet Reuse
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	236 =============
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	237
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	238 .. _`#def`:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	239 .. _`macros`:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	240
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	241 ``#def``
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	242 ----------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	243
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	244 The ``#def`` directive can be used to create macros, i.e. snippets of template
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	245 text that have a name and optionally some parameters, and that can be inserted
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	246 in other places::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	247
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	248 #def greeting(name)
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	249 Hello, ${name}!
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	250 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	251 ${greeting('world')}
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	252 ${greeting('everyone else')}
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	253
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	254 The above would be rendered to::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	255
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	256 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	257 Hello, everyone else!
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	258
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	259 If a macro doesn't require parameters, it can be defined as well as called
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	260 without the parenthesis. For example::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	261
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	262 #def greeting
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	263 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	264 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	265 ${greeting}
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	266
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	267 The above would be rendered to::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	268
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	269 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	270
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	271
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	272 Variable Binding
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	273 ================
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	274
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	275 .. _`#with`:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	276
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	277 ``#with``
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	278 -----------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	279
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	280 The ``#with`` directive lets you assign expressions to variables, which can
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	281 be used to make expressions inside the directive less verbose and more
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	282 efficient. For example, if you need use the expression ``author.posts`` more
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	283 than once, and that actually results in a database query, assigning the results
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	284 to a variable using this directive would probably help.
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	285
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	286 For example::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	287
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	288 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	289 #with y=7; z=x+10
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	290 $x $y $z
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	291 #end
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	292
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	293 Given ``x=42`` in the context data, this would produce::
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	294
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	295 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	296 42 7 52
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	297
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	298 Note that if a variable of the same name already existed outside of the scope
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	299 of the ``#with`` directive, it will not be overwritten. Instead, it will
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	300 have the same value it had prior to the ``#with`` assignment. Effectively,
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	301 this means that variables are immutable in Genshi.
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	302
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	303
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	304 .. _comments:
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	305
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	306 --------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	307 Comments
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	308 --------
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	309
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	310 Lines where the first non-whitespace characters are ``##`` are removed from
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	311 the output, and can thus be used for comments. This can be escaped using a
4d81439bc097 * Added basic documentation for the text-based template language. cmlenz parents: diff changeset	312 backslash.

Mercurial > genshi > mirror

annotate doc/text-templates.txt @ 427:55c574767df2 trunk