NAME

HTML::Mason::Commands - Mason command reference

DESCRIPTION

The following commands may be used within Mason components. See HTML::Mason::Components (the Mason Developer's Guide), for usage examples.

COMMAND REFERENCE

mc_abort ([return value])

Ends the current execution, finishing the page without returning through components. In a web environment, the optional return value is used as the HTTP status code.

mc_cache ([action=>'retrieve'], [key=>name], [keep_in_memory=>0|1], [expire_if=>sub])

mc_cache (action=>'store', [key=>name], value=>data, [keep_in_memory=>0|1], [expire_at=>time | expire_next=>'hour'|'day' | expire_in=>delta])

mc_cache (action=>'expire', [key=>name])

mc_cache() lets you store and retrieve the results of computation for improved performance. Each component has its own data cache for storing one or more key/value pairs. The cache is implemented as a DBM database. See the "data caching" in Components section of the Component Developer's Guide for examples and caching strategies.

The argument to action is one of:

o retrieve: returns the cache value if successful, or undef if there was no value or if it has expired.

o store: stores a new cache value under the given key. Default key is 'main'.

o expire: expires a given cache value or values. key may be a single key or a list reference. Default key is 'main'.

o keys: returns a list of all the keys in the cache.

value defines what to store. It can be a scalar or a reference to an arbitrary data structure. The allowable size depends on your DBM implementation.

keep_in_memory indicates whether to save the value in memory once it is retrieved. Default is 0, meaning that the value will be retrieved from the cache file each time. If 1, each child server that retrieves this value will save its own copy, which can result in substantial memory usage for larger values. Use sparingly.

The various expiration options are:

o expire_at: takes an absolute expiration time, in Perl time() format (number of seconds since the epoch)

o expire_in: takes a relative expiration time of the form "<num><unit>", where <num> is a positive number and <unit> is one of seconds, minutes, hours, days, or weeks, or any abbreviation thereof. E.g. "10min", "30m", "1hour".

o expire_next: takes a string, either 'hour' or 'day'. It indicates an expiration time at the top of the next hour or day.

o expire_if: calls a given anonymous subroutine and expires if the subroutine returns a non-zero value. The subroutine is called with one parameter, the time when the cache value was last written.

mc_cache_self ([key=>name], [keep_in_memory=>0|1], [expire_if=>sub | expire_at=>time | expire_next=>'hour'|'day' | expire_in=>delta])

Uses mc_cache to cache the entire output of the current component. It is typically used right at the top of a <%perl_init%> section:

    <%perl_init>
        return if mc_cache_self(expire_in=>'3 hours'[, key=>'fookey']);
        ... <rest of perl_init> ...
    </%perl_init%>

The "return if" is necessary. mc_cache_self handles both the retrieve and store, so you can pass both kinds of options to it. See mc_cache for an explanation of options.

mc_cache_self uses a bit of magic to accomplish everything in one line. You don't really need to understand this, but if you're curious, here's how it works:

o A component foo calls mc_cache_self for the first time.

o mc_cache_self sees that the cache is empty and calls foo again recursively, with a STORE option to capture its content into a buffer.

o foo again calls mc_cache_self; this time it returns 0 immediately.

o foo goes about its business and generates content into the mc_cache_self buffer.

o When control is returned to mc_cache_self, it stores the content in the cache and also outputs the content normally. Finally mc_cache_self returns 1, which in turn causes foo to return immediately.

mc_caller ()

Returns the full path of the component that called this component, or undef if this is the top-level component. This is the second element of mc_comp_stack.

mc_comp (compPath, option=>value, ...[, STORE=>ref])

Calls the component designated by compPath with the specified option/value pairs. If the component path is absolute (starting with a '/'), then the component is found relative to the component root. Relative component paths (no leading '/') are relative to the current component directory.

Components work exactly like Perl subroutines in terms of return values and context. A component can return any type of value, which is then returned from the mc_comp call.

If you want to capture the output of a component in a string, send a scalar reference with the STORE option. The output will be placed in the scalar instead of being sent to the default output stream.

mc_comp_exists (compPath)

Returns 1 if compPath is a valid component path, 0 otherwise.

mc_comp_stack ()

Returns the list of components in the call stack, starting with the current component and ending with the top-level component.

mc_date (format)

This command is provided for backward compatibility with early versions of Mason that automatically used the Date::Manip package. Returns the interpreter's notion of the current time or date in the specified format. This works like Date::Manip::UnixDate (see Date::Manip for valid formats). To use this command you must now explicitly "use Date::Manip" inside the HTML::Mason::Commands package. E.g. in your handler.pl,

    { package HTML::Mason::Commands;
      use Date::Manip; }

To allow time and date simulations in the previewer, components should use mc_date() rather than UnixDate directly.

mc_date() works faster than UnixDate for some formats by caching results.

mc_file (filename)

Returns the contents of filename as a string. filename may be an absolute filesystem path (starting with a '/') or relative (no leading '/'); if relative, the static file root is prepended.

Developers are encouraged to use relative paths whenever possible. This eliminates the need for component updates when data files are moved (the administrator just updates the static file root).

mc_file_root ()

Returns the static file root, used by mc_file() to resolve relative filenames.

mc_out (string)

Print the given string. Rarely needed, since normally all HTML is just placed in the component body and output implicitly. mc_out is useful if you need to output something in the middle of a Perl block.

mc_out() should be favored over the lower-level $r->print, since mc_out() may be redirected or buffered, depending on the current state of the interpreter.

mc_time ()

Returns the interpreter's notion of the current time in Perl time() format (number of seconds since the epoch).

To allow time and date simulations in the previewer, components should use mc_time() rather than calling time() directly.

Web-only Commands

The following commands are only available when Mason is running in a Web environment.

mc_dhandler_arg ()

For use in dhandlers. Returns the path_info CGI argument, stripped of its leading slash.

mc_suppress_http_header (0|1)

Mason normally emits any pending HTTP headers just before entering the primary section of a component. To prevent this, call mc_suppress_http_header(1) somewhere in the <%perl_init%> block. You can call mc_suppress_http_header(0) to cancel.

AUTHOR

Jonathan Swartz, swartz@transbay.net

SEE ALSO

HTML::Mason, HTML::Mason::Components