CherryTemplate

CherryTemplate is an easy and powerful templating module for Python. It used to be part of CherryPy but is now released as a separate/standalone module.

Download

You can download the latest CherryTemplate module from the SourceForge page.

Install

  • Prerequisite: Python-2.3 or higher
  • Unzip/untar the file that you downloaded
  • Go to the directory that got created and type "python setup.py install"
  • That's it !

How to use it

Note: This documentation applies to the latest code in the Subversion repository, not to the 1.0.0a1 release (the API has been simplified since then).

Basic example: 

$ python
Python 2.3.3 (#51, Dec 18 2003, 20:22:39) [MSC v.1200 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from cherrytemplate import renderTemplate
>>> name = "world"
>>> renderTemplate('Hello, <py-eval="name">')
'Hello, world'

The basic example isn't very useful, because all it does it write out a string to the console. What we really want to know is how to use CherryTemplate to help us put application data into the user's browser.

More detailed example:

See J. Clement's blog, which includes a brief write-up on CherryPy and a good example of how to use CherryTemplate with template files. With CherryPy, you create .py files that contain your CherryPy application, and write methods that return html code to the browser. When you add in CherryTemplate, all that you do is replace the 'return' command with a renderTemplate() method.

Tags

  • py-eval: evaluate a Python expression and inserts the result (the results has to be a string). Example: 
      Hello, the value is <py-eval="'%02d' % (3 + 4)">
  • py-exec: execute one line of Python code. Example: 
      <py-exec="import time">
  Hello, the time is: <py-eval="str(time.ctime(time.time()))">
  • py-code: execute a block of Python code. Example: 
       <py-code="
       a = 1
       if a > 1:
           b = 2
       else:
           b = 3
    ">
    The sum is <py-eval="str(a+b)">
  • py-if/py-else: exactly like if/else in Python. Example: 
       <py-if="2 > 3">
       Not normal
   </py-if><py-else>
       Normal
   </py-else>
  • py-for: like a for loop in Python. Example: 
        <py-for="i, j in [(1,1), (2,1), (1,3)]">
      i + j: <py-eval="str(i+j)"><br>
    </py-for>
  • py-include: include an external file in the template. Example: 
        <py-include="header.html">
    Hello, this is the body of the page
    <py-include="footer.html">

External template

Instead of putting your template in a Python string, you can just put it in a file and call "renderTemplate" like this: 

renderTemplate(file = 'template.html')

Unicode support

CherryTemplate can work on unicode templates or encoded templates, and it can return a unicode string or an encoded string.

  • The default behavior is to not do any transformation, so if you pass in a unicode string, you'll get a unicode result, and if you pass in an encoded string, you'll get an encoded result in the same encoding.
  • If you pass in an encoded template and you want CherryTemplate to turn it into unicode for processing it, you have to pass a non-None "inputEncoding" parameter (or set the global "defaultInputEncoding" variable in the module)
  • If you want CherryTemplate to return an encoded result, you have to pass a non-None "outputEncoding" parameter (or set the global "defaultOutputEncoding" variable in the module). Note that if you want to do that, you have to either pass in a unicode template or use "inputEncoding" to tell CherryTemplate what the encoding of the template is.
  • Example: Let's say your template is in a file "template.html" using latin-1 encoding, and you want to render it as a utf-8 encoded string, here is the command to run: 
    renderTemplate(file = "template.html", inputEncoding = 'latin-1', outputEncoding = 'utf-8')
  • For more examples, look at the file unittest/unittest.py that comes with the module

Subversion repository

If you're interested, you can access the CherryTemplate Subversion repository at:

http://svn.cherrytemplate.python-hosting.com/

The *nix command to check out the source into a local dir called 'work' is:

svn checkout http://svn.cherrytemplate.python-hosting.com/trunk work

What about py-attr? Missing or deprecated?

Attachments