XAO::Web - XAO Web Developer, dynamic content building suite

 use XAO::Web;

 my $web=XAO::Web->new(sitename => 'test');

 $web->execute(cgi => $cgi,
               path => '/index.html');

 my $config=$web->config;

 $config->clipboard->put(foo => 'bar');

Please read XAO::Web::Intro for general overview and setup instructions. Check also misc/samplesite for code examples and a generic site setup.

XAO::Web module provides a frameworks for loading site configuration and executing objects and templates in the site context. It is used in scripts and in Apache web server handler to generate actual web pages content.

Normally a developer does not need to use XAO::Web directly.

When XAO::Web creates a new site (for mod_perl that happens only once during each instance on Apache lifetime) it first loads new 'Config' object using XAO::Objects' new() method and site name it knows. If site overrides Config - it loads site specific Config, if not - the systme one.

After the object is created XAO::Web embeds two standard additional configuration objects into it:

hash

Hash object is primarily used to keep site configuration parameters. It is just a XAO::SimpleHash object and most of its methods get embedded - get, put, getref, delete, defined, exists, keys, values, contains.

web

Web configuration embeds methods that allow cookie, clipboard and cgi manipulations -- add_cookie, cgi, clipboard, cookies, header, header_args.

After that XAO::Web calls init() method on the Config object which is supposed to finish configuration set up and usually stuffs some parameters into 'hash', then connects to a database and embeds database configuration object into the Config object as well. Refer to XAO::Web::Intro for an example of site specific Config object and init() method.

When object initialization is completed the Config object is placed into XAO::Projects registry and is retrieved from there on next access to the same site in case of mod_perl.

Note: that means that if you are embedding a site specific version of an object during initialisation you need to pass 'sitename' into XAO::Objects' new() method.

Methods of XAO::Web objects include:

analyze ($;$$)

Checks how to display the given path (scalar or split up array reference). Always returns valid results or throws an error if that can't be accomplished.

Returns hash reference:

 prefix   => longest matching prefix (directory in case of template found)
 path     => path to the page after the prefix
 fullpath => full path from original query
 objname  => object name that will serve this path
 objargs  => object args hash (may be empty)

Optional second argument can be used to enforce a specific site name.

Optional third argument must be used to allow returning records of types other than 'xaoweb'. This is used by Apache::XAO to get 'maptodir' and 'external' mappings. Default is to look for xaoweb only records.

clipboard ()

Returns site clipboard object.

config ()

Returns site configuration object reference.

execute (%)

Executes given `path' using given `cgi' environment. Prints results to standard output and uses CGI object methods to send header.

Note: Execute() is not re-entry safe currently! Meaning that if you create a XAO::Web object in any method called inside of execute() loop and then call execute() on that newly created XAO::Web object the system will fail and no useful results will be produced.

expand (%)

Expands given `path' using given `cgi' or 'apache' environment. Returns just the text of the page in scalar context and page content plus header content in array context.

This is normally used in scripts to execute only a particular template and get results of execution.

`Objargs' argument may refer to a hash of additional parameters to be passed to the template being executed.

Example:

 my $report=$web->expand(cgi     => CGI->new,
                         path    => '/bits/stat-report',
                         objargs => {
                             CUSTOMER_ID => '123X234Z',
                             MIN_TIME    => time - 86400 * 7,
                         });

See also lower level process() method.

process (%)

Takes the same arguments as the expand() method returning expanded page text. Does not clean the site context and should not be called directly -- for normal situations either expand() or execute() methods should be called.

new (%)

Creates or loads a context for the named site. The only required argument is 'sitename' which provides the name of the site.

Additionally `cgi' argument can point to a CGI object -- this is useful mostly in test cases when one does not want to use execute(), but new() comes handy.

set_current ()

Sets the current site as the current project in the sense of XAO::Projects.

sitename ()

Returns site name.

Nothing.

Copyright (c) 2005 Andrew Maltsev

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

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

Recommended reading: XAO::Objects, XAO::Projects, XAO::DO::Config.