"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

---