NAME

LedgerSMB::Template - Template support module for LedgerSMB

DESCRIPTION

This module renders templates to an in-memory property.

This module does not handle the output/delivery of the rendered template to browser, file, e-mail etc. For that, see modules such as LedgerSMB::PSGI::Util and LedgerSMB::Legacy_Util.

METHODS

new(user => \%myconfig, template => $string, format => $string, [format_options => $hashref], [locale => $locale], [language => $string], [path => $path], [debug => $bool] );

Instantiates a new template. Accepts the following arguments:

user (optional)

A LedgerSMB::User object defining user preferences.

template

The template to be processed. This is the file that is the template to be processed. When 'path' equals 'DB', the file is retrieved from the database instead of from disk. Based on the specified format, an appropriate extension is appended to resolve to the correct template file.

format_plugin

The formatter to be used. Currently HTML, PS, PDF, TXT, CSV, ODS, XLS, XLSX are supported, through the plugins in LedgerSMB::Template::Plugin modules, subject to their dependencies being available.

format_options (optional)

A hash of format-specific options. See the appropriate LSMB::T::foo for details.

output_options (optional)

A hash of output-specific options, not used internally by LedgerSMB::Template. These options may be used by output/delivery code.

For example, if the output is sent as an HTTP response using LedgerSMB::PSGI::Util::template_to_psgi(), the output option filename causes Content-Disposition headers to be generated of the type attachment (forcing file download).

locale (optional)

The locale object to use for regular gettext lookups. Having this option adds the text function to the usable list for the templates. Has no effect on the gettext function.

language (optional)

The language for template selection.

path (optional)

Overrides the template directory.

The special value 'DB' enforces reading of the template from the current database. Resolving the template takes the 'language' and 'format' values into account.

debug (optional)

Enables template debugging.

With the TT-based renderers, HTML, PS, PDF, TXT, and CSV, the portion of the template to get debugging messages is to be surrounded by <?lsmb DEBUG format 'foo' ?> statements. Example:

    <tr><td colspan="<?lsmb columns.size ?>"></td></tr>
    <tr class="listheading">
  <?lsmb FOREACH column IN columns ?>
  <?lsmb DEBUG format '$file line $line : [% $text %]' ?>
      <th class="listtop"><?lsmb heading.$column ?></th>
  <?lsmb DEBUG format '' ?>
  <?lsmb END ?>
    </tr>

render($variables, $raw_variables)

Returns the LedgerSMB::Template object itself. Dies on error.

The rendered template result is available from the LedgerSMB::Template object's output property, based on variables and raw_variables.

variables are escaped using the specific mechanism to the output format. raw_variables are passed without escaping or processing to the template processor.

get_template_source($extension)

Returns the name of the Template source, incorporating the specified extension as appropriate.

get_template_args($extension)

Returns a hash with the default arguments for the Template and the desired file extention

FUNCTIONS

preprocess ($rawvars, $escape): Preprocess for rendering. This is not an object method, it is a standalone subroutine.

PROPERTIES

output: The result of rendering the template.
mimetype: The mimetype of the rendered template.
output_options: Not used internally by LedgerSMB::Template, but used as a way of passing options to output/delivery code, such as LedgerSMB::PSGI::Util::template_to_psgi().

TEMPLATE FUNCTIONS

Templates can make use of the following functions, installed by the template processor, when available for the current format.

text($string, @args)

This function looks up the translation of $string in the language lexicon, interpolating the string's variable placeholders with the arguments provided in @args. The resulting string will be escaped using the escape function.

Note: This string looks up the exact string $string, which makes it unsuited for translation of string values passed to the template through (escaped) string variable values.

dbfile_path($name) =item dbfile_string($name) =item dbfile_base64($name)

These functions retrieve a file uploaded through System > Files. dbfile_path returns a file name on the file system holding the content of the file in the database. dbfile_string returns the content of the uploaded file in a string, whereas dbfile_base64 returns the content in a string, encoded using base64 encoding.

The file returned by dbfile_path is guaranteed as long as a reference to the template is kept. There are no guarantees beyond the life of the template itself.

FORMATS

The template employs formats for a number of format-specific tasks:

Escaping/encoding of values
Discovery of format specific templates
Evaluation of the template

In order to perform these actions, formats need to implement the following entry-points:

escape($value)

The template calls this function with one scalar value as its argument, repeatedly until all values to be passed to the template have been escaped.

The return value is the escaped value to substitute for $value. The escaping mechanism is format specific.

unescape($value) [optional]

The template calls this function with one scalar value as its argument, in order to reverse the transformation as applied by escape.

setup($parent, $variables, $output)

The template driver calls this function just before the evaluation of the template. The $parent is an instance of this class. The $variables is a hashref containing the escaped variable values which will be passed to the template. $output holds the output destination; either a string (containing a filename) or a scalar reference (for in-memory capturing of template output).

This function returns a tuple with the first value being the (temporary) output destination and the second a configuration hash with at least the following keys:

format_extension: This extension, together with the base name specified by the caller of the renderer, is used to look up the format specific template.
binmode: This value indicates which binmode to use for the output being generated. Valid values are ':utf8', 1 or 0.

The configuration hash can be used as a communication channel between setup and postprocess by adding keys starting with an underscore (_).

initialize_template($parent, $config, $template)

After the Template Toolkit engine has been initialized based on the values returned by setup, the driver calls this function, if a format provides it.

$config corresponds with the second argument returned by setup.

$template is an instance of a Template Toolkit template processor - its value can be used to register plugins if such is required for the specific format.

postprocess($parent, $output, $config)

After having evaluated the template, the driver calls this function. Its arguments are the instance of the driver $parent (same as for setup), $output (the first item of the tuple returned by setup) and the configuration hash $config.

This function does not have a defined return value, but should return undef for forward compatibility.

mimetype()

Returns the MIME content-type for the rendered template.

LICENSE AND COPYRIGHT

This file is licensed under the GNU General Public License version 2, or at your option any later version. A copy of the license should have been included with your software.

LedgerSMB Documentation