/ 
App-ZofCMS-Plugin-Cookies-0.0101
/ App::ZofCMS::Plugin::Cookies

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!

AUTHOR

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

BUGS

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

SUPPORT

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

perldoc App::ZofCMS::Plugin::Cookies

You can also look for information at:

COPYRIGHT & LICENSE

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.