# `cement.ext.ext_mustache`

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

## Requirements

> - pystache (`pip install pystache`)

## Configuration

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

    from cement.core import foundation

    class MyApp(foundation.CementApp):
        class Meta:
            label = 'myapp'
            extensions = ['mustache']
            output_handler = 'mustache'
            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 Mustache template file in `myapp/templates/my_template.mustache` or `/usr/lib/myapp/templates/my_template.mustache` and then render a data dictionary with it:

    app.render(some_data_dict, 'my_template.mustache')

## Loading Partials

Mustache supports `partials`, or in other words template `includes`. These are also loaded by the output handler, but require a full file name. The partials will be loaded in the same way as the base templates

For example:

templates/base.mustache

    Inside base.mustache
    {{> partial.mustache}}

template/partial.mustache

    Inside partial.mustache

Would output:

    Inside base.mustache
    Inside partial.mustache

class `cement.ext.ext_mustache.``MustacheOutputHandler`(*args, **kw)

  Bases: `cement.core.output.TemplateOutputHandler`

  This class implements the IOutput interface. It provides text output from template and uses the Mustache Templating Language. Please see the developer documentation on Output Handling.

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

  class `Meta`

    Bases: `object`

    Handler meta-data.

    `interface`

      alias of `IOutput`

    `overridable` = False

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

  `MustacheOutputHandler.``render`(data_dict, template=None, **kw)

    Take a data dictionary and render it using the given template file. Additional keyword arguments passed to `stache.render()`.

    Required Arguments:

    Parameters:

    - data_dict – 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)