The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-ZofCMS-1.001006
River stage one • 1 direct dependent • 1 total dependent
++
/ App::ZofCMS::Template

NAME

App::ZofCMS::Template - "core" part of ZofCMS - web-framework/templating system

SYNOPSIS

Sample ZofCMS template named 'foo.tmpl' in "templates" directory (see App::ZofCMS::Config):

    {
        body => \'foo.tmpl',
        t   => {
            time => scalar(localtime),
        },
        conf    => {
            base    => 'base.tmpl',
        },
    }

Sample 'base.tmpl' file located in "data store" directory

    Base template
    [ <tmpl name="body"> ]
    In brakets you'll see the output of "body =&amp; \'foo.tmpl'" from
    ZofCMS template

Sample 'foo.tmpl' file in "data store" directory referenced by body key in the ZofCMS template above.

    Current time: <tmpl_var name="time">

Now if the user to access http://example.com/index.pl?page=foo they would see the following:

    Base template
    [ Current time: Sat Jul 26 21:08:26 2008 ]
    In brakets you'll see the output of "body => \'foo.tmpl'" from
    ZofCMS template

DESCRIPTION

This module is used internally by App::ZofCMS and this documentation explains how ZofCMS templates work. This documentation assumes you have read App::ZofCMS::Config.

If you wish to make changes to this module, please contact the author.

STARTING WITH THE BASICS

ZofCMS template is a hashref. Same as the config file, it's loaded with do(), thus you can do perlish stuff in it.

The "first level" keys in this hashref can take a scalar, or a scalar reference. The exception are special keys which are described below.

The "first level" keys' values will be stuffed into <tmpl_var name="name_of_the_first_level_key"> inside your base template (which is explained in the description of conf special key). If the key's value is a scalar, that scalar will be directly inserted into <tmpl_var>. If the value is a scalar reference it's taken as a filename inside your "data storage" directory. The file will be read and its contents will be placed into <tmpl_var> unless the filename ends with .tmpl. If filename ends with .tmpl it will be treated as HTML::Template file, the keys in the special key t (see "SPECIAL KEYS" section below) will be inserted into it, then the ->output() method will be called on it and that output will then by inserted into <tmpl_var> in your base template.

Some plugins may take their input via "first level" keys. However, sane plugins will delete those keys from the ZofCMS template hashref when they are called.

SPECIAL KEYS

There are (currently) four special "first level" keys in ZofCMS template hashref. They will NOT be stuffed into <tmpl_var>s in the base template. Some plugins may take their input via "first level" keys, make sure to read the documentation for any plugins you are using.

t

    {
        t => {
            current_time => scalar(localtime),
        },
    }

The special key t (read template) takes a hashref as a value which contains keys/values which will be inserted into tmpl_* variables inside both, your "base" template (see below) and any HTML::Template files loaded via "first level" keys. Most plugins will populate this hashref when they are executed.

d

    {
        d => {
            current_time => scalar(localtime),
        },
    }

The special key d (read data) is exactly the same as t key except none of its keys/values will be interpolated into any templates. The purpose of this key is to pass around data between the templates and plugins. Currently, I did not find this key useful, however, it is there if you need it. Eventually, plugins may use this key as a clean method of input (as in, they don't have to delete anything from ZofCMS template hashref).

plugins

    {
        plugins => [
            qw/DBI QueryToTemplate/, # these are set to priority 10000
            { TOC => 100 }, # this one has specific priority of 100
            { Plugin => 1000 }, # this one got priority of 1000
        ],
        plugins2 => [ # this is a second level of plugins, allows to run same plugins twice
            qw/Foo Bar Baz/
        ],
    }

Special key plugins takes an arrayref as a value. Can be postfixed by a number to create several levels of plugin sets to run (allows to execute same plugins several times). The higher the number the later that plugin set will execute. Elements of this arrayref can be either scalars or hashrefs. If the element is a scalar it will be treated as the name of the plugin to load/execute; in this case the "priority" of the plugin is set to 10000. If the element is a hashref, the key of that hashref will be treated as the name of the plugin to load and the value will be treated as the value for plugin's "priority".

The "priority" of the plugin determines in what sequence it will be executed among other plugins. Priority can be a negative number, the larger the priority, the later the plugin will be executed. Plugins with the same priority number are executed in non-specified order.

Note: do NOT use the App::ZofCMS::Plugin:: part of the plugin's module name, in other words, if you have installed App::ZofCMS::Plugin::QueryToTemplate plugin, to use it you would specify plugins => [ 'QueryToTemplate' ]

conf

    {
        conf => {
            base        => 'base.tmpl',
            exec_before => sub {
                my ( $query, $template, $config, $base ) = @_;
                $query->{foo} = 'bar'
                    unless $query->{foo} eq 'baz';

                $template->{t} = localtime;
            },
            exec => sub {
                my ( $query, $template, $config, $base ) = @_;
            },
            die_on_bad_params => 1,
        },
    }

The conf key (read configuration) is a special key. It's value is a hashref keys of which are also special.

base

    conf => { base => 'base.tmpl', }

The base key in conf hashref specifies the "base" template to use. This is the "base" template mentioned above in the description of "first level" keys of ZofCMS template hashref. The value of base key must be a scalar containing a filename of the HTML::Template located in "data store" directory. Normally, this would be an HTML::Template template used for your entire site. Of course, this can be set in the template_defaults key in your config file.

NOTE: the base is a (probably the only) mandatory key which MUST be present in your ZofCMS templates (setting it in template_defaults qualifies as such)

die_on_bad_params

    conf => {
        die_on_bad_params => 1,
    }

Takes either true or false values, defaults to a false value. As ZofCMS matured, especially with the invention of plugins like App::ZofCMS::Plugin::QueryToTemplate, use of this option became very limited. What it basically does (when set to a true value) is make your application die every time ZofCMS tries to set a non-existent tmpl_var in your HTML::Template templates.

exec_before

    conf => {
        exec_before => sub {
            my ( $query, $template, $config, $base ) = @_;
            $query->{foo} = 'bar'
                unless $query->{foo} eq 'baz';

            $template->{t} = localtime;
        },
    },

   # OR

   conf => {
        exec_before => 'ModuleName',
   }

The exec_before key in conf hashref specifies which code to run before ZofCMS template is processed. The value can be either a subref or a scalar. If a scalar is specified as a value it must be a module name which is located in $core_directory/App/ZofCMS/Execs/. In other words, if exec_before is set to 'ModuleName', ZofCMS will run $core_directory/App/ZofCMS/Execs/ModuleName.pm. The ModuleName.pm must have two subs: sub new { bless {}, shift} and sub execute {}. Yes, it must be object oriented... don't ask why. What's given to new() may be changed in the future.

If the value of exec_before is a subref it will get the following in its @_ (in that order):

    $query_ref -- a hashref of query parameters, keys are names
                  of the parameters and values are the values.

    $ZofCMS_template -- ZofCMS template hashref. In exec_before,
                       you can change anything here, including values
                       for "first level" keys.

    $config_object -- App::ZofCMS::Config object

    $base  -- HTML::Template object which is loaded with the template
              specified by conf => { base => }

If the value of exec_before is a scalar with the name of the module, the @_ of sub execute {} will look the same except the first element will be $self (i.e. the object)

The return value of exec_before code is disregarded.

exec

    conf => {
        exec => sub {
            my ( $query, $template, $config, $base ) = @_;
            $query->{foo} = 'bar'
                unless $query->{foo} eq 'baz';

            $template->{t} = localtime;
        },
    },

   # OR

   conf => {
        exec => 'ModuleName',
   }

The exec key follows the same principles as exec_before with two exceptions. First, it's called after the template is processed and plugins are executed, meaning setting anything in {t} will have no effect. Second, returning a false value will restart processing of the template from the very beginning. Possibility here is changing query parameters.

NOTE ON exec_before AND exec keys

They were implemented before the plugin system was in place. Currently I find little use for either of them. They will stay as possibilities in ZofCMS but I encourage you to write plugins instead.

REPOSITORY

Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/App-ZofCMS/issues

If you can't access GitHub, you can email your request to bug-App-ZofCMS at rt.cpan.org

AUTHOR

Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.