TemplateParser¶

The µWeb TemplateParser is a in-house developed templating engine that provides tag replacement, tag-functions and template control functions. This document will describe the following:

• The Template class, used to parse the templating language
• The Parser class, which provides template loading and caching
• Using TemplateParser inside a µWeb PageMaker
• Template syntax, an overview of the language's constructs and behaviors

First though, to help with understanding the TemplateParser, a minimal size template document:

Hello [title] [name]

The above document contains two simple template tags. These tags are delimited by square brackets, and they will be replaced by the named argument provided during parsing. If this name is not present, then the literal presentation of the tag will remain in the output.

Template class¶

The Template class provides the interface for pre-parsing templates, loading them from files and parsing single templates to completion. During pre-parsing, constructs such as loops and conditional statements are converted to TemplateLoop and TemplateConditional objects, and their scopes nested appropriately in the Template. Tags are replaced by TemplateTag instances, and text is captured in TemplateText. All of these provide Parse methods, which together result in the combined parsed template output.

Creating a template¶

A template is created simple by providing a string input to the Template's constructor. This will return a valid Template instance (or raise an error if there is a problem with the syntax:

import templateparser
>>> template = templateparser.Template('Hello [title] [name]')
>>> template
Template([TemplateText('Hello '), TemplateTag('[title]'), TemplateText(' '), TemplateTag('[name]')])

Above can be seen the various parts of the template, which will be combined to output once parsed.

Loading a template from file¶

The Template class provides a classmethod called FromFile, which loads the template at the path.

Loading a template named example.utp from the current working directory:

import templateparser
>>> template = templateparser.Template.FromFile('example.utp')
>>> template
Template([TemplateText('Hello '), TemplateTag('[title]'), TemplateText(' '), TemplateTag('[name]')])

Parsing a template¶

Parsing a template can be done by calling the Template's Parse method. The keyword arguments provided to this call will from the replacement mapping for the template. In the following example, we will provide one such keyword, and leave the other undefined to show the (basic) behavior of the Template.Parse method.

import templateparser
>>> template = templateparser.Template('Hello [title] [name]')
>>> template.Parse(title='sir')
'Hello sir [name]'

Parser class¶

The Parser class provides simple management of multiple Template objects. It is mainly used to load templates from disk. When initiating a Parser, the first argument provides the search path from where templates should be loaded (the default is the current working directory). An optional second argument can be provided to preload the template cache: a mapping of names and Template objects.

Loading templates¶

Creating a parser object, and loading the 'example.utp' template from the 'templates' directory works like this:

import templateparser
>>> # This sets the 'templates' directory as the search path for AddTemplate
>>> parser = templateparser.Parser('templates')
>>> # Loads the 'templates/example.utp' and stores it as 'example.utp':
>>> template = parser.AddTemplate('example.utp')
>>> template.Parse(title='mister', name='Bob Dobalina')
'Hello mister Bob Dobalina'

The AddTemplate method takes a second optional argument, which allows us to give the template a different name in the cache, which we will now explain.

Template cache and auto-loading¶

The Parser object behaves like a slightly modified dictionary to achieve this. Retrieving keys yields the associated template. Keys that are not present in the cache are automatically retrieved from the filesystem:

import templateparser
>>> parser = templateparser.Parser('templates')
>>> parser
Parser({})  # The parser is empty (has no cached templates)
>>> # Automatically loads the named template from the 'templates' directory:
>>> parser['example.utp'].Parse(title='mister', name='Bob Dobalina')
'Hello mister Bob Dobalina'
>>> parser
Parser({'example.utp': Template([TemplateText('Hello '), TemplateTag('[title]'),
                                 TemplateText(' '), TemplateTag('[name]')])})

If these cannot be found, TemplateReadError is raised:

import templateparser
>>> parser = templateparser.Parser('templates')
>>> parser['bad_template.utp'].Parse(failure='imminent')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/var/lib/underdark/libs/uweb/templateparser.py", line 147, in __getitem__
    self.AddTemplate(template)
  File "/var/lib/underdark/libs/uweb/templateparser.py", line 171, in AddTemplate
    raise TemplateReadError('Could not load template %r' % template_path)
underdark.libs.uweb.templateparser.TemplateReadError: Could not load template 'templates/bad_template.utp'

Parse and ParseString¶

For convencience and consistency, the Parser comes with two handy methods to provide parsing of Template objects, one from its cache, one from raw template strings. It is recommended to use these over the previously shown direct key-based access:

import templateparser
>>> parser = templateparser.Parser('templates')
>>> parser.Parse('example.utp', title='mister', name='Bob Dobalina')
'Hello mister Bob Dobalina'
>>> parser.ParseString('Hello [title] [name]', title='mister', name='Bob Dobalina')
'Hello mister Bob Dobalina'

Using TemplateParser inside µWeb¶

Templating language syntax¶