# `cement.ext.ext_genshi`

The Genshi Extension module provides output templating based on the Genshi Text Templating Language.

## Requirements

> - Genshi (`pip install genshi`)

## 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.foundation import CementApp

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

    with MyApp() as app:
        app.run()

        # create some data
        data = dict(foo='bar')

        # render the data to STDOUT (default) via a template
        app.render(data, 'my_template.genshi')

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 Genshi template file in `myapp/templates/my_template.genshi` or `/usr/lib/myapp/templates/my_template.genshi`.

class `cement.ext.ext_genshi.``GenshiOutputHandler`(*args, **kw)

  Bases: `cement.core.output.TemplateOutputHandler`

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

  class `Meta`

    Bases: `object`

    Handler meta-data.

    `interface`

      alias of `cement.core.output.IOutput`

  `render`(data_dict, **kw)

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

    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)

## Genshi Syntax Basics

Printing Variables

    Hello ${user_name}

Where `user_name` is a variable returned from the controller. Will display:

    Hello Johnny

Conditional Statements

    {% if foo %}\\
    Label: ${example.label}
    {% end %}\\

Will only output `Label: <label>` if `foo == True`.

For Loops

    {% for item in items %}\\
      - ${item}
    {% end %}\\

Where `items` is a list returned from the controller. Will display:

    - list item 1
    - list item 2
    - list item 3

Functions

    {% def greeting(name) %}\\
    Hello, ${name}!
    {% end %}\\

    ${greeting('World')}\\
    ${greeting('Edward')}

Will output:

    Hello, World!
    Hello, Edward!

Formatted Columns

    {# --------------------- 78 character baseline --------------------------- #}\\

    label               ver       description
    ==================  ========  ================================================
    {% for plugin in plugins %}\\
    ${"%-18s" % plugin['label']}  ${"%-8s" % plugin['version']}  ${"%-48s" % plugin['description']}
    {% end %}

Output looks like:

    $ helloworld list-plugins

    label               ver       description
    ==================  ========  ================================================
    example1            1.0.34    Example plugin v1.x for helloworld
    example2            2.1       Example plugin v2.x for helloworld