The heart of Cheetah is the
Template class in the
Cheetah.Template module. You can use it directly if you have a
template definition in hand, or indirectly through a precompiled template,
which is a subclass. The constructor accepts the following keyword
arguments. (If you're a beginner, learn the first three arguments now;
the others are much less frequent.)
source=prefix if it's the first argument, as in all the examples below. The source can be a string literal in your module, or perhaps a string you read from a database or other data structure.
$placeholdervalue. You may specify a class object or string. If a class object, it must be a subclass of
Cheetah.Filters.Filter. If a string, it must be the name of one of the filters in filtersLib module (see next item). (You may also use the
#filterdirective (section 7.9) to switch filters at runtime.)
Cheetah.Filters. All classes in this module that are subclasses of
Cheetah.Filters.Filterare considered filters.
$placeholdererrors. You may specify a class object or string. If a class object, it must be a subclass of
Cheetah.ErrorCatchers.ErrorCatcher. If a string, it must be the name of one of the error catchers in
Cheetah.ErrorCatchers. This is similar to the
#errorCatcherdirective (section 10.2).
Template directly, you must specify either
file, but not both. To use a precompiled template, you
must not specify either one, because the template definition is already
built into the class. The other arguments, however, may be used in either case.
Here are typical ways to create a template instance:
t = Template("The king is a $placeholder1.")
t = Template(file="fink.tmpl")
t = Template(file=f)
t = Template("The king is a $placeholder1.", searchList=[dict, obj])
t = Template(file="fink.txt", searchList=[dict, obj])
t = Template(file=f, searchList=[dict, obj])
If you use
Template directly, the template definition will be compiled
the first time it's filled. Compilation creates a template-specific class
called the generated class, which is a subclass of
then dynamically switches the instance so it's now an instance of this class.
Don't worry if you don't understand this; it works.
When you precompile a template using the ``cheetah compile'' command, it
writes the generated class to a file. Actually, what it writes is the source
code for a Python module that contains the generated class. Again, the
generated class is a subclass of
Template. We call the generated
module a .py template module. Thus, if you always use
precompiled templates (as many people do), you can view Cheetah as a
convenient front-end for writing certain kinds of Python modules, the way
you might use a graphical dialog builder to make a dialog module.
Precompiled templates provide a slight performance boost because the compilation happens only once rather than every time it's instantiated. Also, once you import the .py template module and allow Python to create a .pyc or .pyo file, you skip the Python compiler too. The speed advantage of all this is negligable, but it may make a difference in programs that use templates many times a second.
Template subclasses Webware's
Servlet class when available,
so the generated class can be used as a Webware servlet. This is practical
only with precompiled templates.
To fill a template, you call its main method. This is normally
.respond(), but under certain circumstances it's
a user-defined name. (Section 8.3 explains why
the method name is not always the same.) However,
always an alias for the main method, so you can always use
print myTemplateInstance or
str(myTempateInstance) to fill it.
You can also call any
#block method and it will fill
just that portion of the template, although this feature is not often used.