TemplateHelper

The TemplateHelper plugin is a connector plugin that adds Python classes and methods to client metadata instances for use in templates. This allows you to easily reuse code that is common amongst multiple templates and add convenience methods.

Using TemplateHelper

First, mkdir /var/lib/bcfg2/TemplateHelper and add TemplateHelper to your plugins line in /etc/bcfg2.conf. Restart bcfg2-server.

Now, any .py file placed in /var/lib/bcfg2/TemplateHelper/ will be read and added to matching client metadata objects. See Writing Helpers below for more information on how to write TemplateHelper scripts.

TemplateHelper does not support group- or host-specific helpers. All helpers will be available to all clients.

Writing Helpers

A helper module is just a Python module with several special conditions:

• The filename must end with .py
• The module must have an attribute, __export__, that lists all of the classes, functions, variables, or other symbols you wish to export from the module.
• data, name, fam, Index, and HandleEvent are reserved names. You should not include symbols with a reserved name in __export__. Additionally, including symbols that start with an underscore or double underscore is bad form, and may also produce errors.

Additionally, the module may have an attribute, __default__, that lists all of the symbols that you wish to include by default in the template namespace. name, metadata, source_path, repo, and path are reserved names, and should not be included in __default__.

See examples/TemplateHelper for examples of helper modules.

Usage

Specific helpers can be referred to in templates as metadata.TemplateHelper[<modulename>]. That returns a HelperModule object which will have, as attributes, all symbols listed in __export__. For example, consider this helper module:

__export__ = ["hello"]
__default__ = ["pining"]

def hello(metadata):
    return "Hello, %s!" % metadata.hostname

def pining(text):
    return "It's pinin' for the %s!" % text

To use this in a Genshi template, we could do:

${metadata.TemplateHelper['hello'].hello(metadata)}
${pining("fjords")}

The template would produce:

Hello, foo.example.com!
It's pinin' for the fjords!

Note that the client metadata object is not passed to a helper module in any magical way; if you want to access the client metadata object in a helper function or class, you must pass the object to the function manually.