view release on metacpan or  search on metacpan

PLUGINS.md  view on Meta::CPAN

    * This was added partly as a demo, and partly for [use on my site](http://steve.org.uk/Software/templer/).
* `Templer::Plugin::FileContents`
    * Set variable values to the contents of files.
* `Templer::Plugin::FileGlob`
    * Set variable values to lists of files, based on a globbing pattern.
    * dirname, basename and file extension are made available.
    * If the glob matches images then heights and widths will be available to your HTML.
    * If the glob doesn't match images then the contents of the files will also be made available.
    * If the glob matches templer input files then templer input variables will be available to your HTML.
* `Templer::Plugin::ShellCommand`
    * Set variable values to the output of shell commands.
* `Templer::Plugin::RootPath`
    * Allow access to your site prefix, without hardcoding it.
* `Templer::Plugin::RSS`
    * Allow pages to include remote RSS feed data.
* `Templer::Plugin::Redis`
    * Allow variables to be retrieved from a Redis store running on the local system.
* `Templer::Plugin::Timestamp`
    * Allow pages to contain their own modification timestamp.

The following template filter plugins are distributed as part of the project:

* `Templer::Plugin::Dollar`
    * Allow template variables to be written using a simple shell-like syntax.
* `Templer::Plugin::Strict`
    * Allow template tags to be written as empty-element tags conforming to XML syntax.

If you wish you may contain write your own plugins, contained beneath your
templer-site.  The default [templer.cfg](templer.cfg.sample) documents the
`plugin-path` setting.


Plugin Types
------------

There are three types of plugins which are supported:

* Plugins which are used for formatting.
    * These convert your input files from Textile, Markdown, etc, into HTML.

* Plugins which present variables for use in your template(s).
    * Creating variables that refer to file contents, file globs, etc.

* Plugins which filter content of your template(s).
    * Simplify the way template can be written (escaping `HTML::Template` syntax which is too rigid for some text-editors facility, namely `nxml-mode` in Emacs for instance).

Although similar there is a different API for the three plugin-families.


### Formatter Plugins

The formatting plugins are intentionally simple because they are explicitly
enabled on a per-page basis. There is no need to dynamically try them all in
turn, executing whichever matches a particular condition, for example.

A standard input page-file might look like this:

    Title: My page title.
    Format: textile
    ----
    This is a textile page.  It has **bold** text!

When this page is rendered the Textile plugin is created and it is then called
like so:

    if ( $plugin->available() )
    {
        $html = $plugin->format(  $input );
    }

If the named formatter is not present, or does not report itself as "enabled"
then the markup will be returned without any expansion.  To be explicit
any formatter plugin must implement only the following two methods:

* `available`
    * To determine whether this plugin is available.
    * i.e. It might only be enabled if the modules it relies upon are present.
* `format`
    * Given some input text return the rendered content.
    * This method receives all the per-page and global variables.


### Filter Plugins

The template filter plugin is similar in use as the formatter one. The only
difference is at the level it operates. While a formatter plugin operates on
the content of the page, a filter one operates directly on the core template
engine allowing one to escape `HTML::Template` rigid syntax.

A standard input page-file might look like this:

    Title: My page title.
    template-filter: dollar
    ----
    This is a html page with a ${title}.

A standard template layout might look like this:

    <title>${title escape=html}</title>

When this page is rendered the Dollar plugin is created and is used to add a
filter to the `HTML::Template` object creation (through the `filter` property
of the `HTML::Template->new` method).

If the named filter is not present, or does not report itself as "enabled"
then the filter is just not used.  To be explicit any filter plugin must
implement only the following two methods:

* `available`
    * To determine whether this plugin is available.
    * i.e. It might only be enabled if the modules it relies upon are present.
* `filter`
    * Given some input text (read template) return the filtered template.


### Variable Expansion Plugins

For the variable-expansion plugins the approach is similar, but an arbitrary
number of plugins may be registered and each one is executed in turn - so
return values are chained.