htmltmpl

A templating engine for separation of code and HTML.

VERSION: 1.20

AUTHOR: Tomas Styblo (tripie@cpan.org)

WEBSITE: http://htmltmpl.sourceforge.net/

LICENSE: GNU GPL

The documentation of this templating engine is separated to two parts:

1. Description of the templating language.

2. Documentation of classes and API of this module that provides a Python implementation of the templating language.

All the documentation can be found in 'doc' directory of the distribution tarball or at the homepage of the engine. Latest versions of this module are also available at that website.

You can use and redistribute this module under conditions of the GNU General Public License that can be found either at http://www.gnu.org/ or in file "LICENSE" contained in the distribution tarball of this module.

Copyright (c) 2001 Tomas Styblo, tripie@cpan.org


CLASSES:



CLASS: TemplateProcessor

Fill the template with data and process it.

This class provides actual processing of a compiled template. Use it to set template variables and loops and then obtain result of the processing.

METHODS:

        __init__     Constructor.
        process     Process a compiled template. Return the result as string.
        set     Associate a value with top-level template variable or loop.
        reset     Reset the template data.

METHOD: __init__()

Constructor. (class TemplateProcessor)

PARAMETERS:

__init__(html_escape=1, magic_vars=1, global_vars=0, debug=0)

METHOD: process()

Process a compiled template. Return the result as string. (class TemplateProcessor)

This method actually processes a template and returns the result.

RETURN VALUE:

Result of the processing as string.

PARAMETERS:

process(template, part=None)

METHOD: set()

Associate a value with top-level template variable or loop. (class TemplateProcessor)

A template identifier can represent either an ordinary variable (string) or a loop.

To assign a value to a string identifier pass a scalar as the 'value' parameter. This scalar will be automatically converted to string.

To assign a value to a loop identifier pass a list of mappings as the 'value' parameter. The engine iterates over this list and assigns values from the mappings to variables in a template loop block if a key in the mapping corresponds to a name of a variable in the loop block. The number of mappings contained in this list is equal to number of times the loop block is repeated in the output.

RETURN VALUE:

No return value.

PARAMETERS:

set(var, value)

METHOD: reset()

Reset the template data. (class TemplateProcessor)

This method resets the data contained in the template processor instance. The template processor instance can be used to process any number of templates, but this method must be called after a template is processed to reuse the instance,

RETURN VALUE:

No return value.

PARAMETERS:

reset(keep_data=0)


CLASS: TemplateError

Fatal exception. Raised on runtime or template syntax errors.

This exception is raised when a runtime error occurs or when a syntax error in the template is found. It has one parameter which always is a string containing a description of the error.

All potential IOError exceptions are handled by the module and are converted to TemplateError exceptions. That means you should catch the TemplateError exception if there is a possibility that for example the template file will not be accesssible.

The exception can be raised by constructors or by any method of any class.

The instance is no longer usable when this exception is raised.



CLASS: Template

This class represents a compiled template.

This class provides storage and methods for the compiled template and associated metadata. It's serialized by pickle if we need to save the compiled template to disk in a precompiled form.

You should never instantiate this class directly. Always use the TemplateManager or TemplateCompiler classes to create the instances of this class.

The only method which you can directly use is the is_uptodate method.

METHODS:

        is_uptodate     Check whether the compiled template is uptodate.

METHOD: is_uptodate()

Check whether the compiled template is uptodate. (class Template)

Return true if this compiled template is uptodate. Return false, if the template source file was changed on the disk since it was compiled. Works by comparison of modification times. Also takes modification times of all included templates into account.

RETURN VALUE:

True if the template is uptodate, false otherwise.

PARAMETERS:

is_uptodate(compile_params=None)


CLASS: TemplateCompiler

Preprocess, parse, tokenize and compile the template.

This class parses the template and produces a 'compiled' form of it. This compiled form is an instance of the Template class. The compiled form is used as input for the TemplateProcessor which uses it to actually process the template.

This class should be used direcly only when you need to compile a template from a string. If your template is in a file, then you should use the TemplateManager class which provides a higher level interface to this class and also can save the compiled template to disk in a precompiled form.

METHODS:

        __init__     Constructor.
        compile_string     Compile template from a string.
        compile     Compile template from a file.

METHOD: __init__()

Constructor. (class TemplateCompiler)

PARAMETERS:

__init__(include=1, max_include=5, comments=1, gettext=0, debug=0)

METHOD: compile_string()

Compile template from a string. (class TemplateCompiler)

This method compiles a template from a string. The template cannot include any templates. TMPL_INCLUDE statements are turned into warnings.

RETURN VALUE:

Compiled template. The return value is an instance of the Template class.

PARAMETERS:

compile_string(data)

METHOD: compile()

Compile template from a file. (class TemplateCompiler)

RETURN VALUE:

Compiled template. The return value is an instance of the Template class.

PARAMETERS:

compile(file)


CLASS: TemplateManager

Class that manages compilation and precompilation of templates.

You should use this class whenever you work with templates that are stored in a file. The class can create a compiled template and transparently manage its precompilation. It also keeps the precompiled templates up-to-date by modification times comparisons.

METHODS:

        __init__     Constructor.
        update     Update (recompile) a compiled template.
        prepare     Preprocess, parse, tokenize and compile the template.

METHOD: __init__()

Constructor. (class TemplateManager)

PARAMETERS:

__init__(include=1, max_include=5, precompile=1, comments=1, gettext=0, debug=0)

METHOD: update()

Update (recompile) a compiled template. (class TemplateManager)

This method recompiles a template compiled from a file. If precompilation is enabled then the precompiled form saved on disk is also updated.

RETURN VALUE:

Recompiled template. It's ensured that the returned template is up-to-date.

PARAMETERS:

update(template)

METHOD: prepare()

Preprocess, parse, tokenize and compile the template. (class TemplateManager)

If precompilation is enabled then this method tries to load a precompiled form of the template from the same directory in which the template source file is located. If it succeeds, then it compares modification times stored in the precompiled form to modification times of source files of the template, including source files of all templates included via the TMPL_INCLUDE statements. If any of the modification times differs, then the template is recompiled and the precompiled form updated.

If precompilation is disabled, then this method parses and compiles the template.

RETURN VALUE:

Compiled template. The methods returns an instance of the Template class which is a compiled form of the template. This instance can be used as input for the TemplateProcessor.

PARAMETERS:

prepare(file)