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

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

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.

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.

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 => {
            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 => {
            current_time => scalar(localtime),
        },
    }

The special key d (read data) is exactly the same as t key execept 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 => [
            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 => {
            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.

    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 templatee 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)

    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-existant tmpl_var in your HTML::Template templates.

    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.

    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.

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.

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

Please report any bugs or feature requests to bug-app-zofcms at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-ZofCMS. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

You can find documentation for this module with the perldoc command.

    perldoc App::ZofCMS

You can also look for information at:

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-ZofCMS

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/App-ZofCMS

* CPAN Ratings

http://cpanratings.perl.org/d/App-ZofCMS

* Search CPAN

http://search.cpan.org/dist/App-ZofCMS

Copyright 2008 Zoffix Znet, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.