"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "docs/users_guide/output.rst" between
cheetah3-3.1.0.tar.gz and cheetah3-3.2.0.tar.gz

About: Cheetah3 is a template engine and code generation tool for e.g. for Web development or Java, SQL, LaTeX, form email ... (written in Python).

output.rst  (cheetah3-3.1.0):output.rst  (cheetah3-3.2.0)
.. role:: math(raw) .. role:: math(raw)
:format: html latex :format: html latex
Generating, Caching and Filtering Output Generating, Caching and Filtering Output
======================================== ========================================
(output)
Output from complex expressions: #echo Output from complex expressions: #echo
-------------------------------------- --------------------------------------
(output.echo)
Syntax: Syntax:
:: ::
#echo EXPR #echo EXPR
The {#echo} directive is used to echo the output from expressions The {#echo} directive is used to echo the output from expressions
that can't be written as simple $placeholders. that can't be written as simple $placeholders.
:: ::
skipping to change at line 36 skipping to change at line 32
This produces: This produces:
:: ::
Here is my silly, silly, silly, silly, silly example. Here is my silly, silly, silly, silly, silly example.
Executing expressions without output: #silent Executing expressions without output: #silent
--------------------------------------------- ---------------------------------------------
(output.silent)
Syntax: Syntax:
:: ::
#silent EXPR #silent EXPR
{#silent} is the opposite of {#echo}. It executes an expression but {#silent} is the opposite of {#echo}. It executes an expression but
discards the output. discards the output.
:: ::
skipping to change at line 62 skipping to change at line 56
If your template requires some Python code to be executed at the If your template requires some Python code to be executed at the
beginning; (e.g., to calculate placeholder values, access a beginning; (e.g., to calculate placeholder values, access a
database, etc), you can put it in a "doEverything" method you database, etc), you can put it in a "doEverything" method you
inherit, and call this method using {#silent} at the top of the inherit, and call this method using {#silent} at the top of the
template. template.
One-line #if One-line #if
------------ ------------
(output.oneLineIf)
Syntax: Syntax:
:: ::
#if EXPR1 then EXPR2 else EXPR3# #if EXPR1 then EXPR2 else EXPR3#
The {#if} flow-control directive (section flowControl.if) has a The {#if} flow-control directive (section flowControl.if) has a
one-line counterpart akin to Perl's and C's {?:} operator. If one-line counterpart akin to Perl's and C's {?:} operator. If
{EXPR1} is true, it evaluates {EXPR2} and outputs the result (just {EXPR1} is true, it evaluates {EXPR2} and outputs the result (just
like {#echo EXPR2#}). Otherwise it evaluates {EXPR3} and outputs like {#echo EXPR2#}). Otherwise it evaluates {EXPR3} and outputs
skipping to change at line 88 skipping to change at line 80
you or you don't like the style use multi-line {#if} directives you or you don't like the style use multi-line {#if} directives
(section flowControl.if). (section flowControl.if).
The trailing {#} is the normal end-of-directive character. As usual The trailing {#} is the normal end-of-directive character. As usual
it may be omitted if there's nothing after the directive on the it may be omitted if there's nothing after the directive on the
same line. same line.
Caching Output Caching Output
-------------- --------------
(output.caching)
Caching individual placeholders Caching individual placeholders
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
(output.caching.placeholders)
By default, the values of each $placeholder is retrieved and By default, the values of each $placeholder is retrieved and
interpolated for every request. However, it's possible to cache the interpolated for every request. However, it's possible to cache the
values of individual placeholders if they don't change very often, values of individual placeholders if they don't change very often,
in order to speed up the template filling. in order to speed up the template filling.
To cache the value of a single {$placeholder}, add an asterisk To cache the value of a single {$placeholder}, add an asterisk
after the $; e.g., {$\*var}. The first time the template is filled, after the $; e.g., {$\*var}. The first time the template is filled,
{$var} is looked up. Then whenever the template is filled again, {$var} is looked up. Then whenever the template is filled again,
the cached value is used instead of doing another lookup. the cached value is used instead of doing another lookup.
skipping to change at line 142 skipping to change at line 130
only around the placeholder name: ``$*.5h*{var.func('arg')}``. only around the placeholder name: ``$*.5h*{var.func('arg')}``.
Sometimes it's preferable to explicitly invalidate a cached item Sometimes it's preferable to explicitly invalidate a cached item
whenever you say so rather than at certain time intervals. You whenever you say so rather than at certain time intervals. You
can't do this with individual placeholders, but you can do it with can't do this with individual placeholders, but you can do it with
cached regions, which will be described next. cached regions, which will be described next.
Caching entire regions Caching entire regions
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
(output.caching.regions)
Syntax: Syntax:
:: ::
#cache [id=EXPR] [timer=EXPR] [test=EXPR] #cache [id=EXPR] [timer=EXPR] [test=EXPR]
#end cache #end cache
The {#cache} directive is used to cache a region of content in a The {#cache} directive is used to cache a region of content in a
template. The region is cached as a single unit, after placeholders template. The region is cached as a single unit, after placeholders
and directives inside the region have been evaluated. If there are and directives inside the region have been evaluated. If there are
skipping to change at line 221 skipping to change at line 207
We are planning to add a {'varyBy'} keyword argument in the future We are planning to add a {'varyBy'} keyword argument in the future
that will allow a separate cache instances to be created for a that will allow a separate cache instances to be created for a
variety of conditions, such as different query string parameters or variety of conditions, such as different query string parameters or
browser types. This is inspired by ASP.net's varyByParam and browser types. This is inspired by ASP.net's varyByParam and
varyByBrowser output caching keywords. varyByBrowser output caching keywords.
#raw #raw
---- ----
(output.raw)
Syntax: Syntax:
:: ::
#raw #raw
#end raw #end raw
Any section of a template definition that is inside a {#raw ... Any section of a template definition that is inside a {#raw ...
#end raw} tag pair will be printed verbatim without any parsing of #end raw} tag pair will be printed verbatim without any parsing of
$placeholders or other directives. This can be very useful for $placeholders or other directives. This can be very useful for
debugging, or for Cheetah examples and tutorials. debugging, or for Cheetah examples and tutorials.
{#raw} is conceptually similar to HTML's {<PRE>} tag and LaTeX's { {#raw} is conceptually similar to HTML's {<PRE>} tag and LaTeX's {
verbatim{}} tag, but unlike those tags, {#raw} does not cause the verbatim{}} tag, but unlike those tags, {#raw} does not cause the
body to appear in a special font or typeface. It can't, because body to appear in a special font or typeface. It can't, because
Cheetah doesn't know what a font is. Cheetah doesn't know what a font is.
#include #include
-------- --------
(output.include)
Syntax: Syntax:
:: ::
#include [raw] FILENAME_EXPR #include [raw] FILENAME_EXPR
#include [raw] source=STRING_EXPR #include [raw] source=STRING_EXPR
The {#include} directive is used to include text from outside the The {#include} directive is used to include text from outside the
template definition. The text can come from an external file or template definition. The text can come from an external file or
from a {$placeholder} variable. When working with external files, from a {$placeholder} variable. When working with external files,
skipping to change at line 299 skipping to change at line 281
includes only if the defined using the {#set global} keyword. includes only if the defined using the {#set global} keyword.
All directives must be balanced in the include file. That is, if All directives must be balanced in the include file. That is, if
you start a {#for} or {#if} block inside the include, you must end you start a {#for} or {#if} block inside the include, you must end
it in the same include. (This is unlike PHP, which allows it in the same include. (This is unlike PHP, which allows
unbalanced constructs in include files.) unbalanced constructs in include files.)
#slurp #slurp
------ ------
(output.slurp)
Syntax: Syntax:
:: ::
#slurp #slurp
The {#slurp} directive eats up the trailing newline on the line it The {#slurp} directive eats up the trailing newline on the line it
appears in, joining the following line onto the current line. appears in, joining the following line onto the current line.
It is particularly useful in {#for} loops: It is particularly useful in {#for} loops:
skipping to change at line 327 skipping to change at line 307
outputs: outputs:
:: ::
0 1 2 3 4 0 1 2 3 4
#indent #indent
------- -------
(output.indent)
This directive is not implemented yet. When/if it's completed, it This directive is not implemented yet. When/if it's completed, it
will allow you to will allow you to
#. indent your template definition in a natural way (e.g., the #. indent your template definition in a natural way (e.g., the
bodies of {#if} blocks) without affecting the output bodies of {#if} blocks) without affecting the output
#. add indentation to output lines without encoding it literally in #. add indentation to output lines without encoding it literally in
the template definition. This will make it easier to use Cheetah to the template definition. This will make it easier to use Cheetah to
produce indented source code programmatically (e.g., Java or Python produce indented source code programmatically (e.g., Java or Python
source code). source code).
skipping to change at line 352 skipping to change at line 330
at this time. So pretend it doesn't exist. If you have a use for at this time. So pretend it doesn't exist. If you have a use for
this feature and would like to see it implemented sooner rather this feature and would like to see it implemented sooner rather
than later, let us know on the mailing list. than later, let us know on the mailing list.
The latest specification for the future {#indent} directive is in The latest specification for the future {#indent} directive is in
the TODO file in the Cheetah source distribution. the TODO file in the Cheetah source distribution.
Ouput Filtering and #filter Ouput Filtering and #filter
--------------------------- ---------------------------
(output.filter)
Syntax: Syntax:
:: ::
#filter FILTER_CLASS_NAME #filter FILTER_CLASS_NAME
#filter $PLACEHOLDER_TO_A_FILTER_INSTANCE #filter $PLACEHOLDER_TO_A_FILTER_INSTANCE
#filter None #filter None
Output from $placeholders is passed through an ouput filter. The Output from $placeholders is passed through an ouput filter. The
default filter merely returns a string representation of the default filter merely returns a string representation of the
 End of changes. 12 change blocks. 
24 lines changed or deleted 0 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)