NAME

Uttu::Handler::mason

SYNOPSIS

[global]
  content_handler = mason

[mason]
  data_dir /data/apache/uttu/mason_data
  comp_root my/components
  use_object_files
  use_strict

DESCRIPTION

By setting the global content_handler configuration variable to mason, HTML::Mason will be called to parse the web pages and create the content.

GLOBALS

The HTML::Mason content handler makes the following global variables available.

$u

This is the Uttu object responsible for the current request.

$lh

If internationalization is enabled, then this is define and is the Locale::Maketext object providing translation services into the preferred language of the client.

CONFIGURATION

These variables are used to configure the HTML::Mason::ApacheHandler object.

allow_global

List of variable names, complete with prefix ($@%), that you intend to use as globals in components. Normally, global variables are forbidden by strict, but any variable mentioned in this list is defined as a package global in the $mason_in_package package.

allow_global $DBH
allow_global %session

$r and $u are automatically added to this list.

auto_send_headers

If this is true, Mason will send the headers before sending any content. Otherwise, the framework will need to send the headers before the content. This may be useful if cookies are not being sent properly from within the framework, for example.

The default is true.

autohandler_name

File name used for autohandlers.

The default is autohandler.

code_cache_max_size

This specifies, in bytes, the maximum size of the in-memory cache used by the HTML::Mason interpreter.

The following are all equivalent, capitalization is not significant.

code_cache_max_size 2147483648
code_cache_max_size    2097152 k
code_cache_max_size       2048 M
code_cache_max_size          2 G

Each Uttu configuration has its own HTML::Mason objects with their own code cache. The result, for example, is that two configurations, each with 10M cache, will have a combined cache of 20M with no sharing between them.

The default is 10M.

comp_root

This is the Mason component root. All components are under this path.

Uttu supports multiple component roots. If more than one is specified, they must be named.

comp_root site

but

comp_root modules => /usr/local/share/uttu/$global_framework
comp_root local   => site

The component roots will be searched in the order given.

If the component root is a relative path, it is assumed to be relative to the server root.

If the component root is not named, it is given the name local to distinguish the files from the framework or installed function sets.

Two named component roots are expected if a framework is defined in the [global] section: function_sets and framework. If not defined explicitly in the configuration file, they are added automatically.

The framework component root is based on the location of the Uttu::Framework::$framework module, if in %INC or on the default installation path. For example, if the framework module is in /usr/local/MofN/lib/Uttu/Framework/MofN.pm, then the component root is /usr/local/MofN/. Otherwise, if the default installation path is /usr/local/uttu/, then the component root is /usr/local/uttu/framework/MofN.

The function_sets component root is based on the default installation path. If this is /usr/local/uttu/, then the component root is /usr/local/uttu/functionsets/$framework/. Note that the $global_function_set_base setting is not used when looking for files in the function_sets component root.

At least one component root must be defined either explicitly in the configuration file or by defining the framework in the [global] section. Failure to do so will keep Apache from starting.

data_cache_dir

Specifies an absolute directory for data cache files.

The default is $mason_data_dir/cache.

data_dir

This is the directory in which Mason keeps certain files (e.g., the obj, cache, debug directories). This must be writable by the web server after startup.

If the data directory is a relative path, it is assumed to be relative to the server root.

If the interpreter writes any files during configuration, they are chowned to the user and group Apache will become at request time.

This variable must be defined in the configuration file. Failure to do so will keep Apache from starting.

decline_dirs

If this is true, then Mason will not try to handle requests for directories. This must be false for a dhandler to have an opportunity at handling a directory request.

The default is true.

dhandler_name

File name used for dhandlers.

The default is dhandler.

To use a dhandler, map the directory containing the dhandler to a uri directory. For example:

map_uri /cm = my-cm/

This will map /cm/(.*) to my-cm/$1 where the dhandler is my-cm/dhandler (using the default dhandler name) if the uri is one that is normally translated and handled by the content handler (the extension on the uri must be one mentioned in a handle configuration line).

error_format

This default is <html>. This may be used to specify a different output format. The function HTML::Mason::Exception::as_$error_format is called and should return the formatted error report.

ignore_warnings_expr

This is a regular expression indicating which warnings to ignore when compiling subroutines. Any warning that is not ignored will prevent the component from being compiled and executed.

ignore_warnings_expr Global symbol.*requires explicit package

If not defined, all warnings are heeded; if ., all warnings are ignored.

in_package

This indicates the name of the package in which components run. This allows different applications or different virtual hosts to run in different namespaces.

The default is Uttu::Sites::$server::Port_$port::$loc, where $server is the virtual host or server hostname with _ replacing ., $port is the port, and $loc is the path to the root URI for this configuration, with :: replacing / (for all by the initial /, which is discarded). This allows multiple configurations to have separate namespaces without having to explicitely configure them.

For example, for a Uttu site rooted at http://my.server:8000/some/url/, the default package is Uttu::Sites::my_server::Port_8000::some::url.

Changing this requires removal of all object files since this affects the parser.

max_recurse

This is the maximum component stack depth the interpreter is allowed to descend before signalling an error. Note that this is not impacted by the Uttu content handler -- there are no `hidden' components.

The default is 32.

out_mode

Specifies one of two ways to send output: batch or stream. In batch mode, Mason computes the entire page in a memory buffer before transmitting it all at once. In stream mode, Mason outputs data as soon as possible. This does not affect any buffering being done by Perl or the operating system.

The default is batch.

postamble

This is code added automatically by Mason to the end of each component. This can be useful when debugging, for example. Code can be continued onto another line by ending the line with the continuation character (\). Multiple postambles are concatenated.

Changing this requires removal of all object files since this affects the parser.

The following will duplicate the effect of the postamble in the article on the Mason home page about graphing the component tree.

postamble unless($m -> current_comp->title eq '/log') { \
              my $parent=$m->callers(1); \
              if(defined($parent)) { \
                  $m -> comp('/log',    me => $m->current_comp->title, \
                                    parent => $parent->title); \
              } \
          };

This is equivalent to

postamble unless($m -> current_comp->title eq '/log') {
postamble     my $parent=$m->callers(1);
postamble     if(defined($parent)) {
postamble         $m -> comp('/log',    me => $m->current_comp->title,
postamble     }
postamble };

preamble

This is code added automatically by Mason to the beginning of each component. Code can be continued onto another line by ending the line with the continuation character (\). Multiple preambles are concatenated.

Changing this requires removal of all object files since this affects the parser.

preload

This is a list of components which are loaded when the Mason interpreter initializes. These may contain glob wild cards.

preload /foo/index.html
preload /bar/*.pl

static_file_root

Absolute path to prepend to relative filenames passed to $m->file(). This does not require a trailing slash. This is relative to the server root if it is not itself an absolute path.

The default is $mason_comp_root.

status_title

This is the title used in the Apache::Status pages.

Default is Uttu - $server:$port/$location.

system_log_event

This is a list of events to record in the system log. Current events (dependent on HTML::Mason):

ALL     := REQUEST CACHE COMP_LOAD
REQUEST := REQ_START REQ_END
CACHE   := CACHE_READ CACHE_WRITE

The following configurations are equal:

system_log_event REQUEST

and

system_log_event REQ_START
system_log_event REQ_END

The default is to log nothing.

system_log_file

system_log_separator

Separator to use between fields on a line in the system log. Strings are expanded, so control characters can be specified.

The default is ctrl-A (\cA).

taint_check

Setting this flag allows Mason to work even when taint checking is on. If true, Mason will pass all component source and filenames through a dummy regular expression match to untaint them.

The default is false.

use_data_cache

If this is set, then $m->cache and related commands are operational.

The default is true.

use_object_files

If this is set, then Mason creates object files to save the results of parsing components.

The default is true.

use_reload_file

If this is true, disables Mason's automatic timestamp checking on component source files, relying instead on an explicitly updated reload file, kept in $mason_data_dir/etc/reload.lst.

The default is false.

use_strict

Indicates whether to use strict in compiled subroutines.

The default is true.

use

A list of modules to load. The syntax is identical to that of Perl (without the trailing semicolon):

use Error qw(:try)
use Quantum::Superpositions qw(all any)

Symbols will be imported into the package specified by the in_package variable.

SEE ALSO

HTML::Mason.

AUTHOR

James G. Smith <jsmith@cpan.org>

The descriptions of the Mason configuration variables are based on the HTML::Mason documentation.

COPYRIGHT

Copyright (C) 2002 Texas A&M University. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.