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

This module is part of "core" of ZofCMS web-framework/templating system. Please read App::ZofCMS if you haven't done so already. The module is not to be used as a standalone module, thus no synopsys is provided. See CONFIGURATION FILE EXAMPLES section below.

    # sample contents of config.txt ZofCMS configuration file
    {
        data_store      => '../zcms_site/data',
        templates       => '../zcms_site/templates',
        valid_pages => {
            pages   => [
                '/index',
                '/foo/bar/baz',
            ],
            dirs    => [
                '/',
                '/tools/',
                '/tools/ZofCMS/',
            ],
        },
        template_defaults => {
            t   => {
                top => '<a class="back_to_top" href="#">back to top</a>',
            },
            conf    => {
                base    => 'base.tmpl',
            },
            plugins => [ qw/TOC Breadcrumbs/ ],
        },
        dir_defaults => {
            '/' => {
                t => {
                    current_dir => '/',
                }
            },
            '/foos/' => {
                t => {
                    current_dir => '/foos/',
                },
            },
        },
        zcms_template_extension => '.tmpl',
    };

ZofCMS config file is just a text file which contains a perl hashref. Note: the config file will be loaded with do, thus it's perfectly fine to do something perlish in the config file before having a hashref as the last thing in the file; that includes the ability to do something like this:

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

The config file specifies which pages are "valid" pages for displaying. Specifies where is your "data" storage (i.e. your <HTML::Template> files) and your "templates" storage (i.e. your ZofCMS templates). Besides that, in the config file you can specify some of the default parameters which will be included in your ZofCMS templates unless you override them (from the templates). Extra keys in the config files may be introduced by some plugins (e.g App::ZofCMS::Plugin::DBI). Currently, the following keys have meaning for ZofCMS core:

    {
        data_store => '../zcms_site/data',
    }

The data_store key specifies the directory (relative you index.pl) with your "data", i.e. the HTML::Template files which you can reference from ZofCMS templates. More on this in App::ZofCMS::Template documentaion

    {
        templates => '../zcms_site/templates',
    }

Alike data_store, templates key points to the directory where you keep your ZofCMS template files which are explained in App::ZofCMS::Template documentaion. Note: the value of this key is refered to as "templates dir" in the documentation below.

    {
        valid_pages => {
            pages   => [
                '/index',
                '/foo/bar/baz',
            ],
            dirs    => [
                '/',
                '/tools/',
                '/tools/ZofCMS/',
            ],
        },
    }

The valid_pages specify which particular pages are available on your site. If the page provided to index.pl via page and (optionally) dir parameter does not match valid_page the user will be presented with a 404 - Not Found page. The valid_pages value is a hashref with two keys each of which takes an arrayref as an argument; they are explained a little further below, but first:

Which page to display in ZofCMS is determined by two query parameters: page and dir. They are calculated in the following passion:

If page query parameter is not specified it will default to 'index', if dir query parameter is not specified it will default to /. If page query parameter contains a slash (/) the page will be split and the part containing the slash will overwrite anything that you've set to the dir query parameter. In other words these two mean the same thing: index.pl?page=foo/bar index.pl?page=bar&dir=foo. In fact, the index.pl?page=foo/bar will be transformed into index.pl?page=bar&dir=/foo/ by App::ZofCMS::Config module, note how the leading and ending slash was appended to the dir automatically.

Note: personally I use Apache's mod_rewrite to "fix" the query, in other words, the example above the URI can look like http://example.com/foo/bar

    pages   => [
        '/index',
        '/foo/bar/baz',
    ],

The pages key's arrayref contains valid pages, listed one by one. If we would to take site http://example.com/ running on ZofCMS as an example, and would specify only pages => [ '/index', '/foo/bar/baz', ] in the config file and would not specify the dirs key (see below) then the only pages accessible on the site would be http://example.com/ and http://example.com/index.pl?page=foo/bar/baz. Of course, http://example.com/index.pl?page=index&dir=/ is the same as http://example.com/, see Note on page and dir query parameters above.

The way the check on pages is done is: $dir_param . $page_param eq $some_page_in_pages_arrayref. If all of pages from pages arrayref failed then the check against dirs is done.

    dirs => [
        '/',
        '/tools/',
        '/tools/ZofCMS/',
    ],

The check for valid pages using dirs arrayref is a bit different and serves as a shortcut of some sort. What is done with the elements in dirs arrayref is ZofCMS makes a path and a filename in the following form: $templates_dir (see above) + $dir_param (query parameter dir) + $page_param (query parameter page) + '.tmpl' then it checks if that file exists; if it doesn't - user is presented with 404.

Let's make this information into an example. Let's assume that you have set your "templates dir" to ../zcms_site/templates/, you didn't set anything for pages key in valid_pages in your configuration file but you've set dirs => [ '/tools/' ] for valid_pages. On top of all that, you have created a file ../zcms_site/templates/tools/stuff.tmpl which is the only file in that directory. If user would go to http://example.com/index.pl?page=tools/stuff, ZofCMS would interpet ../zcms_site/templates/tools/stuff.tmpl template and display a page, any other pages would give him a 404.

Note: directories specified in dirs arrayref are not recursable, i.e. specifying dirs => [ '/' ] enable pages in '/tools/'. Later, a special flag to indicate recursing may be implemented.

    {
        template_defaults => {
            foo => 'bar',
            t   => {
                top => 'blah',
            },
            d   => {
                foo => 'bar',
            }
            conf    => {
                base    => 'base.tmpl',
            },
            plugins => [ qw/TOC Breadcrumbs/ ],
        },
    }

These are the "defaults" for all of ZofCMS templates of your ZofCMS site. In other words (refering to the example above) if you don't set key foo in any of your ZofCMS templates, it will take on its default value bar.

The exception are special keys (which are described in App::ZofCMS::Template): t, d, conf and plugins, their contents will act as defaults. In other words, (again refering to the sample above) if you set t => { foo => 'bar' } in your ZofCMS template, the result will be as if you have set t => { foo => 'bar', top => 'blah' }. Same applies for special keys d, conf and plugins.

Note: as you will read later, plugins key takes an arrayref, keys of which may be scalars or hashrefs containing priority numbers. If you add the same plugin in the template itself and template_defaults, plugin will be executed only once. If you add the same plugin with different priority numbers, the priority number set in the template itself will be used.

        dir_defaults => {
            '/' => {
                t => {
                    current_dir => '/',
                }
            },
            '/foos/' => {
                t => {
                    current_dir => '/foos/',
                },
            },
        }

The dir_defaults key functions exactly the same as template_defaults (see above) with one exception, it's directory-specific. Once again, it takes a hashref as a value, the keys of that hashref are dirrectories for which you want to apply the defaults specified as values, which are hashrefs identical to template_defaults.

By "directory" is ment the dir query parameter that is calculated as is described in section Note on page and dir query parameters above.

Note: when specifying the "directory keys", make sure to have the leading and ending slash (or just one slash if it's a "root" directory), because that's what the dir query parameter looks like after being processed.

    { zcms_template_extension => '.tmpl', }

Optional. The zcms_template_extension key takes a string as an argument. This string represents the extensions for your ZofCMS Template files. Defaults to: .tmpl

The methods described below can be used either by plugins (see App::ZofCMS::Plugin or by code specified in exec_before and exec keys in ZofCMS template, this is described in App::ZofCMS::Template

    my $cgi = $config->cgi;

Takes no arguments, returns a CGI object which is created during loading of your main config file.

    my $query = $config->query;

    $config->query( { new => 'query', param => 'value' } );

Takes an optional argument which must be a hashref. The keys of this hashref will appear as if they are query parameters and the values will appear as if they are values of those parameters by any plugins/exec_before/exec code which processes query after your call. Returns a hashref keys of which represent query parameters and values are obviously values of those parameters. Note: this hashref is created from CGI's Vars() function. Refer to CGI documentation if something doesn't look right.

    my $conf = $config->conf;
    $config->conf( { data_store => '../zcms_site/data' } );

Returns the hashref of your main config file. Takes one optional argument which is a hashref, it will be appear as if it was loaded from your main config file -- bad idea to set it like this, in my opinion.

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.