4.1 Constructing Template Objects

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 The template definition as a string. You may omit the 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.
: file A filename or file object containing the template definition. A filename must be a string, and a file object must be open for reading. By convention, template definition files have the extension .tmpl.
: searchList A list of objects to add to the searchList. The attributes/keys of these objects will be consulted for $placeholder lookup.
: filter A class that will format every $placeholder value. 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 #filter directive (section 7.9) to switch filters at runtime.)
: filtersLib A module containing the filters Cheetah should look up by name. The default is Cheetah.Filters. All classes in this module that are subclasses of Cheetah.Filters.Filter are considered filters.
: errorCatcher A class to handle $placeholder errors. 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 #errorCatcher directive (section 10.2).
: compilerSettings A dictionary (or dictionary hierarchy) of settings that change Cheetah's behavior. Not yet documented.

To use Template directly, you must specify either source or 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.")
Pass the template definition as a string.
: t = Template(file="fink.tmpl")
Read the template definition from a file named "fink.tmpl".
: t = Template(file=f)
Read the template definition from file-like object 'f'.
: t = Template("The king is a $placeholder1.", searchList=[dict, obj])
Pass the template definition as a string. Also pass two namespaces for the searchList: a dictionary 'dict' and an instance 'obj'.
: t = Template(file="fink.txt", searchList=[dict, obj])
Same, but pass a filename instead of a string.
: t = Template(file=f, searchList=[dict, obj])
Same with a file object.

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 Template. It 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 .writeBody() or a user-defined name. (Section 8.3 explains why the method name is not always the same.) However, .__str__() is 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 #def or #block method and it will fill just that portion of the template, although this feature is not often used.