3.7 Quickstart tutorial

This tutorial briefly introduces how to use Cheetah from the Python prompt. The following chapters will discuss other ways to use templates and more of Cheetah's features.

The core of Cheetah is the Template class in the Cheetah.Template module. The following example shows how to use the Template class in an interactive Python session. t is the Template instance. Lines prefixed with »> and ... are user input. The remaining lines are Python output.

>>> from Cheetah.Template import Template
>>> templateDef = """
... <HTML>
... <HEAD><TITLE>$title</TITLE></HEAD>
... <BODY>
... $contents
... ## this is a single-line Cheetah comment and won't appear in the output
... #* This is a multi-line comment and won't appear in the output
...    blah, blah, blah 
... *#
... </BODY>
... </HTML>"""
>>> nameSpace = {'title': 'Hello World Example', 'contents': 'Hello World!'}
>>> t = Template(templateDef, searchList=[nameSpace])
>>> print t
 
<HTML>
<HEAD><TITLE>Hello World Example</TITLE></HEAD>
<BODY>
Hello World!
</BODY>
</HTML>
>>> print t    # print it as many times as you want
      [ ... same output as above ... ]
>>> nameSpace['title'] = 'Example #2'
>>> nameSpace['contents'] = 'Hiya Planet Earth!'
>>> print t   # Now with different plug-in values.
<HTML>
<HEAD><TITLE>Example #2</TITLE></HEAD>
<BODY>
Hiya Planet Earth!
</BODY>
</HTML>

>>> t2 = Template(templateDef)
>>> t2.title = 'Hello World Example!'
>>> t2.contents = 'Hello World'
>>> print t2
      [ ... same output as the first example above ... ]
>>> t2.title = 'Example #2'
>>> t2.contents = 'Hello World!'
>>> print t2
     [ ... same as Example #2 above ... ]

>>> class Template3(Template):
>>>     title = 'Hello World Example!'
>>>     contents = 'Hello World!'
>>> t3 = Template3(templateDef)
>>> print t3
     [ ... you get the picture ... ]

The template definition can also come from a file instead of a string, as we will see in section 4.1.

The above is all fine for short templates, but for long templates or for an application that depends on many templates in a hierarchy, it's easier to store the templates in separate *.tmpl files and use the cheetah compile program to convert them into Python classes in their own modules. This will be covered in section 4.2.

As an appetizer, we'll just briefly mention that you can store constant values inside the template definition, and they will be converted to attributes in the generated class. You can also create methods the same way. You can even use inheritance to arrange your templates in a hierarchy, with more specific templates overriding certain parts of more general templates (e.g., a "page" template overriding a sidebar in a "section" template).

For the minimalists out there, here's a template definition, instantiation and filling all in one Python statement:

>>> print Template("Templates are pretty useless without placeholders.")
Templates are pretty useless without placeholders.

You use a precompiled template the same way, except you don't provide a template definition since it was already established:

from MyPrecompiledTemplate import MyPrecompiledTemplate
t = MyPrecompiledTemplate()
t.name = "Fred Flintstone"
t.city = "Bedrock City"
print t