1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
|
Vocabulary
==========
(glossary) (vocabulary)
{ Template} is an informal term meaning a template definition, a
template instance or a template class. A { template definition} is
what the human { template maintainer} writes: a string consisting
of text, placeholders and directives. { Placeholders} are variables
that will be looked up when the template is filled. { Directives}
are commands to be executed when the template is filled, or
instructions to the Cheetah compiler. The conventional suffix for a
file containing a template definition is { .tmpl}.
There are two things you can do with a template: compile it or fill
it. { Filling} is the reason you have a template in the first
place: to get a finished string out of it. Compiling is a necessary
prerequisite: the { Cheetah compiler} takes a template definition
and produces Python code to create the finished string. Cheetah
provides several ways to compile and fill templates, either as one
step or two.
Cheetah's compiler produces a subclass of {Cheetah.Template}
specific to that template definition; this is called the {
generated class}. A { template instance} is an instance of a
generated class.
If the user calls the {Template} constructor directly (rather than
a subclass constructor), s/he will get what appears to be an
instance of {Template} but is actually a subclass created
on-the-fly.
The user can make the subclass explicit by using the
"cheetah compile" command to write the template class to a Python
module. Such a module is called a { .py template module}.
The { Template Definition Language} - or the "Cheetah language" for
short - is the syntax rules governing placeholders and directives.
These are discussed in sections language and following in this
Guide.
To fill a template, you call its { main method}. This is normally
{.respond()}, but it may be something else, and you can use the
{#implements} directive to choose the method name. (Section
inheritanceEtc.implements.
A { template-servlet} is a .py template module in a Webware servlet
directory. Such templates can be filled directly through the web by
requesting the URL. "Template-servlet" can also refer to the
instance being filled by a particular web request. If a Webware
servlet that is not a template-servlet invokes a template, that
template is not a template-servlet either.
A { placeholder tag} is the substring in the template definition
that is the placeholder, including the start and end delimeters (if
there is an end delimeter). The { placeholder name} is the same but
without the delimeters.
Placeholders consist of one or more { identifiers} separated by
periods (e.g., {a.b}). Each identifier must follow the same rules
as Python identifiers; that is, a letter or underscore followed by
one or more letters, digits or underscores. (This is the regular
expression ``[A-Za-z_][A-Za-z0-9_]*``.)
The first (or only) identifier of a placeholder name represents a {
variable} to be looked up. Cheetah looks up variables in various {
namespaces}: the searchList, local variables, and certain other
places. The searchList is a list of objects ({ containers}) with
attributes and/or keys: each container is a namespace. Every
template instance has exactly one searchList. Identifiers after the
first are looked up only in the parent object. The final value
after all lookups have been performed is the { placeholder value}.
Placeholders may occur in three positions: top-level, expression
and LVALUE. { Top-level} placeholders are those in ordinary text
("top-level text"). { Expression} placeholders are those in Python
expressions. { LVALUE} placeholders are those naming a variable to
receive a value. (LVALUE is computerese for
"the left side of the equal sign".) Section
language.placeholders.positions explains the differences between
these three positions.
The routine that does the placeholder lookups is called the {
NameMapper}. Cheetah's NameMapper supports universal dotted
notation and autocalling. { Universal dotted notation} means that
keys may be written as if they were attributes: {a.b} instead of
{a['b']}. { Autocalling} means that if any identifier's value is
found to be a function or method, Cheetah will call it without
arguments if there is no ``()`` following. More about the
NameMapper is in section language.namemapper.
Some directives are multi-line, meaning they have a matching {
#end} tag. The lines of text between the start and end tags is the
{ body} of the directive. Arguments on the same line as the start
tag, in contrast, are considered part of the directive tag. More
details are in section language.directives.syntax (Directive Syntax
Rules).
|
