/ 
XAO-Web-1.91
River stage one • 2 direct dependents • 2 total dependents
/ XAO::DO::Web::Config

NAME

XAO::DO::Web::Config - XAO::Web site configuration object

SYNOPSIS

sub init {
    my $self=shift;

    my $webconfig=XAO::Objects->new(objname => 'Web::Config');

    $self->embed(web => $webconfig);
}

DESCRIPTION

This object provides methods specifically for XAO::Web objects. It is supposed to be embedded into XAO::DO::Config object by a web server handler when site is initialized.

METHODS

Adds an HTTP cookie into the internal list. Parameters are a hash in the same format as for CGI->cookie() method (see CGI).

If a cookie with the same name, path (and domain if set) is already in the list from a previous call to add_cookie() then it gets replaced.

Think of it as if you are adding cookies to you final HTTP response as XAO::Web handler will get all the cookies collected during template processing and send them out for you.

Examples:

$config->add_cookie($cookie);

$config->add_cookie(
    -name       => 'sessionID',
    -value      => 'xyzzy',
    -expires    =>'+1h',
);

For convenience, if there is a '-domain' argument and it refers to a list of domains the cookie is expanded into a set of cookies for all these domains.

Parameters may also be configured as defaults or for specific cookie names in the site configuration /xao/cookie section:

'xao' => {
    'cookie' => {
        'common'    => {        # All cookies
            'httponly'  => 1,
            'secure'    => 1,
        },
        'sessionid' => {        # Specific cookie
            'samesite'  => 'None',
        },

Due to incompatible ways various browsers treat "SameSite" cookies a special parameter 'sscompat' can be used to create and read two cookies -- one with "SameSite" value and one without. This alters the behavior of both add_cookie() and get_cookie() methods for simplicity.

        'sessionid' => {
            'samesite'  => 'None',
            'sscompat'  => 1,
        },

$siteconfig->add_cookie(-name => 'sessionid', -value => $sessionid);

Set-Cookie: ...; sessionid=12345; Secure; HttpOnly; SameSite=None
Set-Cookie: ...; sessionid-sscompat=12345; Secure; HttpOnly

The get_cookie() method takes into consideration values that were set with add_cookie() as a priority over CGI cookies received.

cgi (;$)

Returns or sets standard CGI object (see CGI). In future versions this would probably be converted to CGI::Lite or something similar, so do not rely to much on the functionality of CGI.

Obviously you should not call this method to set CGI object unless you are 100% sure you know what you're doing. And even in that case you have to call enable_special_access() in advance.

Example:

my $cgi=$self->cgi;
my $name=$cgi->param('name');

Or just:

my $name=$self->cgi->param('name');
cleanup ()

Removes CGI object, cleans up clipboard. No need to call manually, usually is called as part of XAO::DO::Config cleanup().

clipboard ()

Returns clipboard XAO::SimpleHash object. Useful to keep temporary data between different XAO::Web objects. Cleaned up for every session.

cookies ()

Returns reference to an array of prepared cookies.

disable_special_access ()

Disables use of cgi() method to set a new value.

embeddable_methods ()

Used internally by global Config object, returns an array with all embeddable method names -- add_cookie(), cgi(), clipboard(), cookies(), force_byte_output(), header(), header_args().

enable_special_access ()

Enables use of cgi() method to set a new value. Normally you do not need this method.

Example:

$config->enable_special_access();
$config->cgi(CGI->new());
$config->disable_special_access();
force_byte_output ()

If the site is configured to run in character mode it might still be necessary to output some content as is, without character processing (e.g. for generated images or spreadsheets).

This method is called automatically when content type is set to a non-text value, so normally there is no need to call it directly.

header (@)

Returns HTTP header. The same as $cgi->header and accepts the same parameters. Cookies added before by add_cookie() method are also included in the header.

Returns header only once, on subsequent calls returns undef.

NOTE: In mod_perl environment CGI will send the header itself and return empty string. Be carefull to check the result for if(defined($header)) instead of just if($header)!

As with the most of Web::Config methods you do not need this method normally. It is called automatically by web server handler at the end of a session before sending out session results.

header_args (%)

Sets some parameters for header generation. You can use it to change page status for example:

$config->header_args(-Status => '404 File not found');

Accepts the same arguments CGI->header() accepts.

Header names can be any of 'Header-Name', 'header-name', 'header_name', or '-Header_name'. All variants are normalized to all-lowercase underscored to make values assigned later in the code trump the earlier.

Supplying 'undef' as a header value is the same as removing that header with header_remove().

header_remove (@)

Remove one or more headers that were previously set in the same session.

$config->header_remove('X-Frame-Options');

Return cookie value for the given cookie name. Unless the second parameter is true, for cookies already set earlier in the same session it would return the value as set, not the value as it was originally received.

NOTE: The path and domain of cookies is ignored when checking for earlier set cookies and the last cookie stored with that name is returned!

new ($$)

Creates a new empty configuration object.

AUTHOR

Copyright (c) 2005 Andrew Maltsev

Copyright (c) 2001-2004 Andrew Maltsev, XAO Inc.

<am@ejelta.com> -- http://ejelta.com/xao/

SEE ALSO

Recommended reading: XAO::Web, XAO::DO::Config.