NAME

CookieManager - Cookie Management


SYNOPSIS

This module tightly integrates Luci with the HTTP::Cookies and HTTP::Request PERL modules for cookie handling (i.e. using a 'cookie jar' and using a callback function for extracting cookies from a Request.)

CookieManager maintains those cookies set by documents parsed using Luci along with cookies directly related to a user's Luci settings. Cookie data is stored in special 'Luci' cookies which are then maintained by the user's browser.


USAGE

First, a CookieManager object must be created to store the needed member data required by the functions. Create the object with a blank parameter list:

 my $cookie_man = CookieManager->new;

Then, fetch any Luci data currently stored with the user's browser:

 # get some fresh cookies
 my @fresh_cookies = CGI::cookie($config->{cookies}->{storage}); 
 $cookie_man->create_cookie_jar(\@fresh_cookies);

Now the CookieManager object contains a cookie jar that has cookies which Luci can pass along to the requested target.

Retreive a user setting:

 $cookie_man->{_settings}{show_alt_tags};


DESCRIPTION

cookie_to_hash

NOTE: This is a non-member function.

Transforms a single cookie entity stored in the user's browser into a hash containing its properties. Individual cookies are stored in the user's browser as semi-colon delimited, key=value pairs.

returns hash reference to a hash containing key/value pairs of a cookie.

example: used internally by create_cookie_jar

cookie_callback

NOTE: This is a non-member function.

Implements the cookie scan callback function for HTTP::Cookies. Since we are dealing with objects here, and you can't use a member function for the callback, we have to work around it. The variable $g_cookie_array_ref holds the $cookie_array variable for the object that is currently scanning cookies using this call back function. The variable should be set just before scanning and undefed just after scanning. Because of this, 2 cookie manager objects cannot be scanning at the same time. This function will fill the $cookie_array with cookies received from a page.

returns nothing. works on a global variable.

example: used internally by extract_cookies

create_cookie_jar

Takes Luci cookies that are stored in the user's browser and creates a cookie jar containing these cookies. This jar is then used with LWP::UserAgent to pass the cookies to the target page. The cookie jar is stored in the _cj member variable of type HTTP::Cookies.

returns nothing

example:

 my @fresh_cookies = CGI::cookie("cookie_name"); 
 $cookie_man->create_cookie_jar(\@fresh_cookies);

extract_cookies

After a page has been requested, it may have set new cookies. This extracts any new cookies that the fetched page has set (in the cookie jar) by using the cookie callback function and storing each cookie in a separate element of an array reference (_cookie_array, with key=value properties semi-colon delimited.)

returns nothing, results are stored in the array reference _cookie_array.

example:

 $cookie_man->extract_cookies;

new_setting

Takes a setting in the form setting=setting_value and adds it to the setting cookie which is saved to the user's browser.

returns nothing

example:

 $cookie_man->new_setting("show_alt_tags=1");

settings

This is a batch way to load up the user's settings. The only parameter is a hash reference to a hash that contains setting names as the keys and the setting value as the hash value. All settings in the passed hash reference will be merged into any already existing settings.

returns nothing

example:

 %setting_hash = ("show_alt_tags" => 1,
                  "font_size" => "large");
 $cookie_man->settings(\%setting_hash);


LUCI DOCUMENTATION

See Luci Documentation for more information.


AUTHORS