NAME

Slash::Display - Display library for Slash

SYNOPSIS

        slashDisplay('some template', { key => $val });
        my $text = slashDisplay('template', \%data, 1);

DESCRIPTION

Slash::Display uses Slash::Display::Provider to provide the template data from the Slash::DB API.

It will process and display a template using the data passed in. In addition to whatever data is passed in the hashref, the contents of the user, form, and static objects, as well as the %ENV hash, are available.

slashDisplay will print by default to STDOUT, but will instead return the data if the third parameter is true. If the fourth parameter is true, HTML comments surrounding the template will NOT be printed or returned. That is, if the fourth parameter is false, HTML comments noting the beginning and end of the template will be printed or returned along with the template.

Template for more information about templates.

EXPORTED FUNCTIONS

slashDisplay(NAME [, DATA, OPTIONS])

Processes a template.

Parameters
NAME
Can be either the name of a template block in the Slash DB, or a reference to a scalar containing a template to be processed. In both cases, the template will be compiled and the processed, unless it has previously been compiled, in which case the cached, compiled template will be pulled out and processed.

DATA
Hashref of additional parameters to pass to the template. Default passed parameters include constants, env, user, and form, which can be overriden (see _populate).

OPTIONS
Hashref of options. Currently supported options are below. If OPTIONS is the value 1 instead of a hashref, that will be the same as if the hashref were { Return => 1 }.
Return
Boolean for whether to print (false) or return (true) the processed template data. Default is print.

Nocomm
Boolean for whether to include (false) or not include (true) HTML comments surrounding template, stating what template block this is. Default is to include comments if the var ``template_show_comments'' is true, to not include comments if it is false. It is true by default.

Section
Each template is assigned to a section. This section may be a section defined as a site section, or some arbitrary section name. By default, the section that is used is whatever section the user is in, but it can be overridden by setting this parameter. If a template in the current section is not found, it defaults to section ``default''.

Section will also default first to ``light'' if the user is in light mode (and fall back to ``default,'' again, if no template for the ``light'' section exists).

A Section value of ``NONE'' will cause no section to be defined, so ``default'' will be used.

Page
Similarly to sections, each template is assigned to a page. This section may be a page defined in the site, or some arbitrary page name. By default, the page that is used is whatever page the user is on (such as ``users'' for ``users.pl''), but it can be overridden by setting this parameter. If a template in the current page is not found, it defaults to page ``misc''.

A Page value of ``NONE'' will cause no page to be defined, so ``misc'' will be used.

Return value
If OPTIONS->{Return} is true, the processed template data. Otherwise, returns true/false for success/failure.

Side effects
Compiles templates and caches them.

NON-EXPORTED FUNCTIONS

get_template(CONFIG1, CONFIG2)

Return a Template object.

Parameters
CONFIG1
A hashref of options to pass to Template->new (will override any defaults).

CONFIG2
A hashref of options to pass to Slash::Display::Provider->new (will override any defaults).

Return value
A Template object. See TEMPLATE ENVIRONMENT.

PRIVATE FUNCTIONS

_populate(DATA)

Put universal data stuff into each template: constants, user, form, env. Each can be overriden by passing a hash key of the same name to slashDisplay.

Parameters
DATA
A hashref to be populated.

Return value
Populated hashref.

TEMPLATE ENVIRONMENT

The template has the options PRE_CHOMP and POST_CHOMP set by default. You can change these in the vars table in your database (template_pre_chomp, template_post_chomp). Also look at the template_cache_size variable for setting the cache size. Template for more information. The cache will be disabled entirely if cache_enabled is false.

The template provider is Slash::Display::Provider, and the plugin module Slash::Display::Plugin can be referenced by simply ``Slash''.

Additional scalar ops (which are global, so they are in effect for every Template object created, from this or any other module) include uc, lc, ucfirst, and lcfirst, which all do what you think.

        [% myscalar.uc %]  # return upper case myscalar

Additional list ops include rand, which returns a random element from the given list.

        [% mylist.rand %]  # return single random element from mylist

Also provided are some filters. The fixurl, fixparam, fudgeurl, and strip_* filters are just frontends to the functions of those names in the Slash API:

        [% FILTER strip_literal %]
                I think that 1 > 2!
        [% END %]

(Note that [% var | filter %] is a synonym for [% FILTER filter; var; END %].)

        <A HREF="[% env.script_name %]?op=[% form.op | fixparam %]">

Each strip_* function in Slash::Utility is also available as a filter. It might seem simpler to just use the functional form:

        [% form.something | strip_nohtml %]
        [% Slash.strip_nohtml(form.something) %]

But we might make it harder to use the Slash plugin (see the Slash::Display::Plugin manpage) in the future (perhaps only certain seclevs?), so it is best to stick with the filter, which is probably faster, too.

SEE ALSO

Template(3), Slash(3), Slash::Utility(3), Slash::DB(3), Slash::Display::Plugin(3), Slash::Display::Provider(3).