view release on metacpan or  search on metacpan

PLUGINS.md  view on Meta::CPAN

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.

Each site page is loaded and the variable names & values are stored in a hash.
Each plugin is free to modify that hash of known variables and their values.

Generally we expect that plugins will look for variable values having a
particular pattern and ignoring those that don't match.  But there is
certainly no reason why you couldn't write a plugin to convert each
variable-value to uppercase, or perform other global operations.

In pseudo-code the processing looks like this:

    $data = ( "foo" => "bar",
              title => "This is my page title .." );

    foreach my $plugin ( $plugins )
    {
         $data = $plugin->expand_variables( $page, $data );
    }

Each plugin will be called once, and once only, for each page.  The
`expand_variables` method is given a reference to the page from which the
variable(s) were loaded, which may be useful in some situations.

It should be noted for completeness that the same expansion happens on global
variables defined within your `templer.cfg` file.


Help?
-----

If you need help writing a plugin, or whish me to supply one for you and your
needs, please do get in touch.