NAME

App::ZofCMS::Plugin::Cookies - HTTP Cookie handling plugin for ZofCMS

SYNOPSIS

In your ZofCMS template, or in your main config file (under template_defaults or dir_defaults):

    set_cookies => [
        [ 'name', 'value' ],
        {
            -name    => 'sessionID',
            -value   => 'xyzzy',
            -expires => '+1h',
            -path    => '/cgi-bin/database',
            -domain  => '.capricorn.org',
            -secure  => 1,
        },
    ],

DESCRIPTION

This module is a plugin for App::ZofCMS which provides means to read and set HTTP cookies.

SETTING COOKIES

    # example 1
    set_cookies => [ 'name', 'value' ],

    # OR

    # example 2
    set_cookies => {
            -name    => 'sessionID',
            -value   => 'xyzzy',
            -expires => '+1h',
            -path    => '/cgi-bin/database',
            -domain  => '.capricorn.org',
            -secure  => 1,
    },

    # OR

    # example 3
    set_cookies => [
        [ 'name', 'value' ],
        {
            -name    => 'sessionID',
            -value   => 'xyzzy',
            -expires => '+1h',
            -path    => '/cgi-bin/database',
            -domain  => '.capricorn.org',
            -secure  => 1,
        },
    ],

To set cookies use set_cookies first level key of your ZofCMS template. It's value can be either an arrayref or a hashref. When the value is an arrayref elements of which are not arrayrefs or hashrefs (example 1 above), or when the value is a hashref (example 2 above) it is encapsulated into an arrayref automatically to become as shown in (example 3 above). With that in mind, each element of an arrayref, which is a value of set_cookies key, specifies a certain cookie which plugin must set. When element of that arrayref is an arrayref, it must contain two elements. The first element will be the name of the cookie and the second element will be the value of the cookie. In other words:

    set_cookies => [ 'name', 'value', ]

    # which is the same as

    set_cookies => [ [ 'name', 'value', ]

    # which is the same as

    CGI->new->cookie( -name => 'name', -value => 'value' );

When the element is a hashref, it will be dereferenced directy into CGI's cookie() method, in other words:

    set_cookies => { -name => 'name', -value => 'value' }

    # is the same as

    CGI->new->cookie( -name => 'name', -value => 'value' );

See documentation of CGI module for possible values.

If set_cookies key is not present, no cookies will be set.

READING COOKIES

All of the cookies are read by the plugin automatically and put into {d}{cookies} (the special key {d} (data) of your ZofCMS template)

You can read those either via exec code (NOT exec_before, plugins are run after) (If you don't know what exec or exec_before are read App::ZofCMS::Template). Other plugins can also read those cookies, just make sure they are run after the Cookies plugin is run (set higher priority number). Below is an example of reading a cookie and displaying it's value in your HTML::Template template using App::ZofCMS::Plugin::Tagged plugin.

    # In your ZofCMS template:

        plugins     => [ { Cookies => 10 }, { Tagged => 20 }, ],
        set_cookies => [ foo => 'bar' ],
        t => {
            cookie_foo => '<TAG:TNo cookies:{d}{cookies}{foo}>',
        },

    # In one of your HTML::Template templates which are referenced by
    # ZofCMS plugin above:

    Cookie 'foo': <tmpl_var name="cookie_foo">

When this page is run the first time, no cookies are set, thus {d}{cookies} will be empty and you will see the default value of "No cookies" which we set in Tagged's tag:

    Cookie 'foo': No cookies

When the page s run the second time, Cookies plugin will read cookie 'foo' which it set on the first run and will stick its value into {d}{cookies}{foo}. Our Tagged tag will read that value and enter it into the <tmpl_var> we allocated in HTML::Template plugin, thus the result will be:

    Cookie 'foo': bar

That's all there is to it, enjoy!

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.