htmltmpl

A templating engine for separation of code and HTML.

VERSION: 1.22

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:

• TemplateCompiler: Preprocess, parse, tokenize and compile the template.

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

• Template: This class represents a compiled template.

  is_uptodate

  Check whether the compiled template is uptodate.

• TemplateError: Fatal exception. Raised on runtime or template syntax errors.

• TemplateManager: Class that manages compilation and precompilation of templates.

  	watch_files	Monitor specified files for changes.
  	prepare	Preprocess, parse, tokenize and compile the template.
  	static_data	Define static template variables.
  	update	Update (recompile) a compiled template.
  	__init__	Constructor.

• TemplateProcessor: Fill the template with data and process it.

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

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:

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)

• file

  Filename of the template.

  See the prepare() method of the TemplateManager class for exaplanation of this parameter.

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)

• data

  String containing the template data.

METHOD: __init__()

Constructor. (class TemplateCompiler)

PARAMETERS:

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

• include

  Enable or disable included templates.

• max_include

  Maximum depth of nested inclusions.

• comments

  Enable or disable template comments.

• gettext

  Enable or disable gettext support.

• debug

  Enable or disable debugging messages.

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:

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)

• compile_params

  Only for internal use.

  Do not use this optional parameter. It's intended only for internal use by the TemplateManager.

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: 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:

METHOD: watch_files()

Monitor specified files for changes. (class TemplateManager)

This function can be used to monitor files for changes. If a file changes, then the template will be automatically recompiled.

This is very useful if you use static variables (TMPL_STATIC) and store their values in a separate file. Please consult language documentation for more info on static variables.

RETURN VALUE:

No return value

PARAMETERS:

watch_files(files)

• files:

  An array of names of files to monitor

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, force_precompiled=0)

• file

  Path to the template file to prepare.

  The method looks for the template file in current directory if the parameter is a relative path. All included templates must be placed in subdirectory 'inc' of the directory in which the main template file is located.

• force_precompiled

  Only use precompiled templates.

  This parameter is useful when all your templates are precompiled and located in a read-only directory. If the compiled template cannot be found, an exception is raised. The engine does not check whether the compiled template is uptodate. By default this is disabled.

METHOD: static_data()

Define static template variables. (class TemplateManager)

First parameter is an associative array which contains names of the variables (keys of the array) and their corresponding values (values of the array).

RETURN VALUE:

No return value.

PARAMETERS:

static_data(static)

• static:

  Dictionary of name/value pairs.

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)

• template

  A compiled template.

  This parameter should be an instance of the Template class, created either by the TemplateManager or by the TemplateCompiler. The instance must represent a template compiled from a file on disk.

METHOD: __init__()

Constructor. (class TemplateManager)

PARAMETERS:

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

• include

  Enable or disable included templates.

  This optional parameter can be used to enable or disable TMPL_INCLUDE inclusion of templates. Disabling of inclusion can improve performance a bit. The inclusion is enabled by default.

• max_include

  Maximum depth of nested inclusions.

  This optional parameter can be used to specify maximum depth of nested TMPL_INCLUDE inclusions. It defaults to 5. This setting prevents infinite recursive inclusions.

• precompile

  Enable or disable precompilation of templates.

  This optional parameter can be used to enable or disable creation and usage of precompiled templates.

  A precompiled template is saved to the same directory in which the main template file is located. You need write permissions to that directory.

  Precompilation provides a significant performance boost because it's not necessary to parse the templates over and over again. The boost is especially noticeable when templates that include other templates are used.

  Comparison of modification times of the main template and all included templates is used to ensure that the precompiled templates are up-to-date. Templates are also recompiled if the htmltmpl module is updated.

  The TemplateErrorexception is raised when the precompiled template cannot be saved. Precompilation is enabled by default.

  Precompilation is available only on UNIX and Windows platforms, because proper file locking which is necessary to ensure multitask safe behaviour is platform specific and is not implemented for other platforms. Attempts to enable precompilation on the other platforms result in raise of the TemplateError exception.

• comments

  Enable or disable template comments.

  This optional parameter can be used to enable or disable template comments. Disabling of the comments can improve performance a bit. Comments are enabled by default.

• gettext

  Enable or disable gettext support.

• debug

  Enable or disable debugging messages.

  This optional parameter is a flag that can be used to enable or disable debugging messages which are printed to the standard error output. The debugging messages are disabled by default.

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:

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)

• keep_data

  Do not reset the template data.

  Use this flag if you do not want the template data to be erased. This way you can reuse the data contained in the instance of the TemplateProcessor.

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.

The method can be called with either one or two parameters. When it's called with two parameters, its behaviour is exactly as described above.

When it's called with one parameter only, then the parameter must be an associative array. The function loops over this array, uses keys of the array as names of variables and values of the array as values of the variables. This can be used for fast multiassignemnts. The values itself may be associative arrays, in which case the assignment is a loop assignment.

The correctness of character case is verified only for top-level variables.

RETURN VALUE:

No return value.

PARAMETERS:

set(var, value)

• var

  Name of template variable or loop.

• value

  The value to associate.

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)

• template

  A compiled template.

  Value of this parameter must be an instance of the Template class created either by the TemplateManager or by the TemplateCompiler.

• part

  The part of a multipart template to process.

  This parameter can be used only together with a multipart template. It specifies the number of the part to process. It must be greater than zero, because the parts are numbered from one.

  The parts must be processed in the right order. You cannot process a part which precedes an already processed part.

  If this parameter is not specified, then the whole template is processed, or all remaining parts are processed.

METHOD: __init__()

Constructor. (class TemplateProcessor)

PARAMETERS:

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

• html_escape

  Enable or disable HTML escaping of variables.

  This optional parameter is a flag that can be used to enable or disable automatic HTML escaping of variables. All variables are by default automatically HTML escaped. The escaping process substitutes HTML brackets, ampersands and double quotes with appropriate HTML entities.

• magic_vars

  Enable or disable loop magic variables.

  This parameter can be used to enable or disable "magic" context variables, that are automatically defined inside loops. Magic variables are enabled by default.

  Refer to the language specification for description of these magic variables.

• global_vars

  Globally activate global lookup of variables.

  This optional parameter is a flag that can be used to specify whether variables which cannot be found in the current scope should be automatically looked up in enclosing scopes.

  Automatic global lookup is disabled by default. Global lookup can be overriden on a per-variable basis by the GLOBAL parameter of a TMPL_VAR statement.

• debug

  Enable or disable debugging messages.