Mercurial > genshi > mirror
view doc/text-templates.txt @ 443:84c6a7522abb trunk
Set MIME type of new doc page.
author | cmlenz |
---|---|
date | Thu, 12 Apr 2007 23:32:19 +0000 |
parents | 97544725bb7f |
children | 477fac8052e3 26cf27d4f2b3 |
line wrap: on
line source
.. -*- mode: rst; encoding: utf-8 -*- ============================= Genshi Text Template Language ============================= In addition to the XML-based template language, Genshi provides a simple text-based template language, intended for basic plain text generation needs. The language is similar to Cheetah_ or Velocity_. .. _cheetah: http://cheetahtemplate.org/ .. _velocity: http://jakarta.apache.org/velocity/ This document describes the template language and will be most useful as reference to those developing Genshi text templates. Templates are text files of some kind that include processing directives_ that affect how the template is rendered, and template expressions that are dynamically substituted by variable data. See `Genshi Templating Basics <templates.html>`_ for general information on embedding Python code in templates. .. contents:: Contents :depth: 3 .. sectnum:: .. _`directives`: ------------------- Template Directives ------------------- Directives are lines starting with a ``#`` character followed immediately by the directive name. They can affect how the template is rendered in a number of ways: Genshi provides directives for conditionals and looping, among others. Directives must be on separate lines, and the ``#`` character must be be the first non-whitespace character on that line. Each directive must be “closed” using a ``#end`` marker. You can add after the ``#end`` marker, for example to document which directive is being closed, or even the expression associated with that directive. Any text after ``#end`` (but on the same line) is ignored, and effectively treated as a comment. If you want to include a literal ``#`` in the output, you need to escape it by prepending a backslash character (``\``). Note that this is **not** required if the ``#`` isn't immediately followed by a letter, or it isn't the first non-whitespace character on the line. Conditional Sections ==================== .. _`#if`: ``#if`` --------- The content is only rendered if the expression evaluates to a truth value:: #if foo ${bar} #end Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this would produce:: Hello .. _`#choose`: .. _`#when`: .. _`#otherwise`: ``#choose`` ------------- The ``#choose`` directive, in combination with the directives ``#when`` and ``#otherwise`` provides advanced contional processing for rendering one of several alternatives. The first matching ``#when`` branch is rendered, or, if no ``#when`` branch matches, the ``#otherwise`` branch is be rendered. If the ``#choose`` directive has no argument the nested ``#when`` directives will be tested for truth:: The answer is: #choose #when 0 == 1 0 #end #when 1 == 1 1 #end #otherwise 2 #end #end This would produce the following output:: The answer is: 1 If the ``#choose`` does have an argument, the nested ``#when`` directives will be tested for equality to the parent ``#choose`` value:: The answer is: #choose 1 #when 0 0 #end #when 1 1 #end #otherwise 2 #end #end This would produce the following output:: The answer is: 1 Looping ======= .. _`#for`: ``#for`` ---------- The content is repeated for every item in an iterable:: Your items: #for item in items * ${item} #end Given ``items=[1, 2, 3]`` in the context data, this would produce:: Your items * 1 * 2 * 3 Snippet Reuse ============= .. _`#def`: .. _`macros`: ``#def`` ---------- The ``#def`` directive can be used to create macros, i.e. snippets of template text that have a name and optionally some parameters, and that can be inserted in other places:: #def greeting(name) Hello, ${name}! #end ${greeting('world')} ${greeting('everyone else')} The above would be rendered to:: Hello, world! Hello, everyone else! If a macro doesn't require parameters, it can be defined as well as called without the parenthesis. For example:: #def greeting Hello, world! #end ${greeting} The above would be rendered to:: Hello, world! Variable Binding ================ .. _`#with`: ``#with`` ----------- The ``#with`` directive lets you assign expressions to variables, which can be used to make expressions inside the directive less verbose and more efficient. For example, if you need use the expression ``author.posts`` more than once, and that actually results in a database query, assigning the results to a variable using this directive would probably help. For example:: Magic numbers! #with y=7; z=x+10 $x $y $z #end Given ``x=42`` in the context data, this would produce:: Magic numbers! 42 7 52 Note that if a variable of the same name already existed outside of the scope of the ``#with`` directive, it will **not** be overwritten. Instead, it will have the same value it had prior to the ``#with`` assignment. Effectively, this means that variables are immutable in Genshi. .. _comments: -------- Comments -------- Lines where the first non-whitespace characters are ``##`` are removed from the output, and can thus be used for comments. This can be escaped using a backslash.