cement.ext.ext_handlebars

The Handlebars Extension provides output templating based on the Handlebars Templating Language.

Requirements

• pybars3 (pip install pybars3)

Configuration

Application Meta-data

This extension supports the following application meta-data via CementApp.Meta:

• handlebars_helpers - A dictionary of helper functions to register with the compiler. Will override HandlebarsOutputHandler.Meta.helpers.
• handlebars_partials - A list of partials (template file names) to search for, and pre-load before rendering templates. Will override HandlebarsOutputHandler.Meta.partials.

Template Directories

To prepend a directory to the template_dirs list defined by the application/developer, an end-user can add the configuration option template_dir to their application configuration file under the main config section:

[myapp]
template_dir = /path/to/my/templates

Usage

class MyApp(CementApp):
    class Meta:
        label = 'myapp'
        extensions = ['handlebars']
        output_handler = 'handlebars'
        template_module = 'myapp.templates'
        template_dirs = [
            '~/.myapp/templates',
            '/usr/lib/myapp/templates',
            ]
# ...

Note that the above template_module and template_dirs are the auto-defined defaults but are added here for clarity. From here, you would then put a Handlebars template file in myapp/templates/my_template.handlebars or /usr/lib/myapp/templates/my_template.handlebars and then render a data dictionary with it:

app.render(some_data, 'my_template.handlebars')

Helpers

Custom helper functions can easily be registered with the compiler via CementApp.Meta.handlebars_helpers and/or HandlebarsOutputHandler.Meta.helpers.

def my_custom_helper(this, arg1, arg2):
    # do something with arg1 and arg2
    if arg1 == arg2:
        return True
    else:
        return False


class MyApp(CementApp):
    class Meta:
        label = 'myapp'
        extensions = ['handlebars']
        output_handler = 'handlebars'
        handlebars_helpers = {
            'myhelper' : my_custom_helper
        }
# ...

You would then access this in your template as:

This is my template

{{#if (myhelper this that)}}
This will only appear if myhelper returns True
{{/if}}

See the Handlebars Documentation for more information on helpers.

Partials

Though partials are supported by the library, there is no good way of automatically loading them in the context and workflow of a typical Cement application. Therefore, the extension needs a list of partial template names to know what to preload, in order to make partials work. Future versions will hopefully automate this.

Example:

class MyApp(CementApp):
    class Meta:
        label = 'myapp'
        extensions = ['handlebars']
        output_handler = 'handlebars'
        handlebars_partials = [
            'header.bars',
            'footer.bars',
        ]

Where header.bars and footer.bars are template names that will be searched for, and loaded just like other templates loaded from template dirs. These are then referenced in templates as:

{{> "header.bars"}}
This is my template
{{> "footer.bars}}

See the Handlebars Documentation for more information on partials.

class cement.ext.ext_handlebars.HandlebarsOutputHandler(*args, **kw)

Bases: cement.core.output.TemplateOutputHandler

This class implements the IOutput interface. It provides text output from template and uses the Handlebars Templating Language for Python via the pybars library. Please see the developer documentation on Output Handling.

Note This extension has an external dependency on pybars3. You must include pybars3 in your applications dependencies as Cement explicitly does not include external dependencies for optional extensions.

class Meta

Handler meta-data.

helpers = {}

Custom helpers

interface

alias of cement.core.output.IOutput

overridable = False

Whether or not to include handlebars as an available to choice to override the output_handler via command line options.

partials = []

List of partials to preload

_setup(app)

The _setup function is called during application initialization and must setup the handler object making it ready for the framework or the application to make further calls to it.

Parameters:app_obj – The application object. Returns:None

render(data, template)

Take a data dictionary and render it using the given template file.

Required Arguments:

Parameters:

• data – The data dictionary to render.
• template – The path to the template, after the template_module or template_dirs prefix as defined in the application.

Returns:

str (the rendered template text)