excess.org

Ian Ward

Consulting
Boxkite Inc.
Software
CKAN contributor/tech lead
PyRF primary contributor
Urwid author
Speedometer author

Presentations
Contributing to Open Source
IASA E-Summit, 2014-05-16
Urwid Applications
2012-11-14
Urwid Intro
2012-01-22
Unfortunate Python
2011-12-19
Django 1.1
2009-05-16

Writing
Moving to Python 3
2011-02-17
Article Tags

Home

Ian Ward's email:
first name at this domain

wardi on OFTC, freenode and github

Locations of visitors to this page

Templayer 1.5.1

Purpose

Templayer is a layered template library for Python and Django. It currently supports only HTML generation, but its simple design is easily extended to support other file formats.

Templayer was created to offer an alternative to the more common ways of generating dynamic HTML: embedding code within the HTML (PHP etc.), or embedding HTML within code (traditional CGI). Neither of these methods allow for a clean separation of the form, or layout, of a page and the function of page generation. Instead of mixing HTML and Python, two rich and extremely expressive languages, we can add a small amount of syntax to each and keep the two separate and coherent.

Example


   <html>
   <head><title>%title%</title></head>
   <body>
   <h1>%title%</h1>
   {contents}
{report} <h3>%day%</h3> %contents% {/report}
{happening}<p>%contents%</p> {/happening}
{/contents} <hr> <p>Generated on %date%.</p> </body> </html>


This is a simple Templayer HTML template from the tutorial.

The %slots% may be filled with any value. All strings have always been escaped by default. Simple markup may also be used.

The {layers}...{/layers} may be nested or combined one after the next then inserted into the %slots%.

The {contents}...{/contents} also acts like a slot with everything at the top and bottom of the template becoming part of the output.

See the Tutorial for more details and example Python CGI and Django code.

Documentation

The Tutorial demonstrates Templayer basics.

The Reference Manual documents the Templayer API.

Source Code

The latest development version of Templayer is available from the Mercurial repository.

Download / Changelog

Current version is 1.5.1

Version 1.5.1 tarball (2009-03-08)

  * django_view functions now return a unicode string 
    (fix for RSS feeds)

  * Fix for get_django_template with auto_reload!='debug'

  * UTF-8 data in templates is now accepted

Version 1.5 tarball (2009-02-12)

  * Improved Django integration with django_view, 
    django_template and get_django_template, 
    django_template_loader functions.

  * Updated django_form to work with Django newforms.

  * Expanded tutorial to include Django examples.

  * Template text is now stored as unicode.  File encoding defaults 
    to UTF-8.

  * template(layer, slot1=value1, ...) is now a shortcut for
    template.format(layer, slot1=value1, ...).

  * Non-lazy versions of HTML Markup were added: urljoin, href, 
    target, entity, BR, P, I, B and U functions immediately convert
    to RawHTML.

  * Renamed FileLayer class to FileWriter.  Old name kept for
    backwards compatibility

Version 1.4 tarball (2006-09-25)

  * Added a django_form convenience function for using Templayer
    with the Django web framework's FormWrapper objects.

  * Added an allow_degenerate parameter to Template.__init__.  If
    set to True then a template file that is missing a contents
    block will be accepted and not cause an exception to be raised.

  * Added a special layer name '*' that treats the entire contents 
    of a template file as a layer.

  * Added two new HTML Markup elements:
    - ('pluralize',count,singular_markup,plural_markup) inserts
      singular_markup if count equals one, and plural_markup 
      otherwise.
    - ('&',entity) inserts the given HTML entity where valid
      entity values include "gt", "#161" and "#xA9".

  * FileLayer.close now returns the file object to which it wrote.
    This simplifies the code required to use Templayer in Django
    view functions.

  * Fixed a really obvious bug in the html_href function.

Version 1.3 tarball (2006-08-30)

  * Added reference documentation and a new tutorial.

  * Added an auto_reload parameter to Template.__init__ to make the
    Template.start_file function check and reload a template if it has
    been modified.  This is useful for mod_python and web frameworks
    with long-lived processes.

  * Changed the internal representation of the templates to improve
    performance for large templates and to solve an issue with
    slots being filled with text that appears to contain another
    slot that is being filled at the same time.

    The new implementation no longer allows "%" and "{" characers in
    slot and layer names.

  * The Template.missing_slot function is now passed a list of 
    missing slots for a layer.  This should improve performance when 
    ignoring a large number of missing slots.

  * The HTML markup has been adjusted to make its use of <br> and <p> 
    tags more standards-compliant.

  * HtmlTemplate has been renamed to HTMLTemplate and MarkupException
    has been renamed to MarkupError.  The old names are still 
    provided for backwards compatibility.

Installation

Debian or Ubuntu, system wide

Install the package python-templayer from the standard repositories.

Others, system wide

Download and extract the Templayer tarball, then run the following commands in the templayer directory as root:

python setup.py install

Local install

If you don't have root access or you don't want to do a system wide install, you can download and extract the Templayer tarball, then copy the file templayer.py into the directory of each program that needs to use it.