2 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 5 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 8.3.

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 5.3 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 5.5.

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 5.8 (Directive Syntax Rules).