NAME

Template::Expansion - a module that can apply variable expansion

SYNOPSIS

use Template::Expansion qw(expand_template);

expand_template(\$data, \%params);

DESCRIPTION

The functions provided by this package are used by the class Template(3). Please do not try to import this class directly. It is only for internal use.

FUNCTIONS

expand_template DATAREF, PARAMS: Expands all recognized variable references in the template DATAREF (string reference) and replaces them by their value. PARAMS is a reference to the hash passed to Template::process.

SYNTAX

Strings which are expanded by this module are comments in SGML/HTML syntax, i.e. they begin with . Boolean values are expressed as either 1 or 0.

The following variables are know to this code:

XX-mode

The current processing mode. Is one of EDIT, SAVE, PREVIEW, REPARSE.

XX-editmode

True if the processor is in mode EDIT.

XX-savemode

True if the processor is in save mode. This means either SAVE, PREVIEW or REPARSE.

XX-previewmode

True if the processor is in mode PREVIEW.

XX-reparsemode

True if the processor is in mode REPARSE.

XX-???

The above example returns the value of the metafield title.

You may specify an escaping mode by prepending the mode name plus a colon, e.g.:

expands to the metavalue title in escaping mode TEXT.

The following modes are supported:

RAW

This is the default mode, it is active if you do not specify a mode. In RAW mode, nothing is escaped - the raw text is printed.

HTML

Just another name for RAW. This is for compatibility with Imperia versions <= 6.0.2.

TEXT

Escapes everything correctly using SGML entities.

TEXTBR

Escapes everything like in TEXT, but translates all newlines to <BR /> first.

URI

Escapes the text as in application/x-www-form-urlencoded, i.e. using the percent sign.

HTMLBR

This is a hack for providing a nice HTML textarea in combination with not having to type <BR/> for every new line.

This mode only replaces newlines by <BR /> and is somewhat like HTML and TEXTBR.

If the selected metavalue is an array, the above expressions only extract the first element. You may also reference other elements of an array:

This refers to the 3rd element of the array title, because arrays are zero-based. For more information about arrays in Imperia templates, please read Template::Array(3).

CC-???

Returns the value of the metafield ???, escaped as value in an URI. This is for compatibility with older Imperia versions, please avoid to use this syntax.

XXDEFINED-???

Returns 1 if the metavalue ??? exists or 0 if the value does not exist.

Xdir???

DEPRECATED. Please use dirlevel instead.

SYSTEM_CONF:NAME

Replaces NAME with the value of the corresponding SYSTEM_CONF variable. NEW: The syntax 'SYSTEM-CONF' (i. e. with a hyphen) is no longer recognized.

USER_CONF:NAME

Replaces NAME with the value of the corresponding USER_CONF variable (see the methods getUserConf()/setUserConf()). The default implementation knows the user configuration variables 'homepage', 'country', 'telnumber', 'language', 'cellular', 'name', 'fname', 'city', 'faxnumber', 'comment', 'zip', 'login', 'email', 'background' and 'street'. NEW: The syntax 'USER-CONF' (i. e. with a hyphen) is no longer recognized.

ENV:VARIABLE

Returns the environment variable VARIABLE.

TEMPLATE:KEY

Returns information from the currently processed template. Valid strings for KEY are id for the template ID, and description for the template description (human-readable name).

DOC_ID:RESERVED

Returns a numerical and system-wide unique document identifier. This is in fact the last part of the document node id with the category information discarded.

TCOUNTER:name+value =item TCOUNTER:name-value =item TCOUNTER:name*value =item TCOUNTER:name/value =item TCOUNTER:name=value

Does some simple arithmetics. An internal variable name is manipulated according to value and the preceding operator. The operator '=' sets the variable and returns an empty string. The operator '+' increments, '-' decrements, '*' multiplies, and '/' divides (or returns the empty string if you try to divide by zero). Instead of value you can also specify another TCOUNTER variable. Variables are automatically created and initialized to 0 if they do not exist.

dirlevel:xxx

Returns the directory name at index xxx.

Xdate:FORMAT

Fills in the current date in a format determined by FORMAT. Valid values for FORMAT are 'default', 'full', 'inverse', 'afiles', 'iso', 'normal', 'american', 'imperia', and 'finddate'. See site_date(3) for details.

Xtime:FORMAT

Fills in the current time in a format determined by FORMAT. Valid values for FORMAT are 'default', 'normal', 'full', 'compact', 'hour', 'minute', and 'second'. See site_date(3) for details.

Xstrftime:LOCALE:FORMAT

NEW: Formats the current date and time via the system strftime(3) facility. Unless LOCALE is left empty, before the call to strftime the current locale is temporarily switched to LOCALE. Valid settings for LOCALE are system-dependent, please look up the system documentation for setlocale(3), locale(1), locale(5), locale(7), ... whatever you find. ``C'' or ``POSIX'' (which beams you into GMT without daylight savings time and English names) should be a safe setting for all systems.

Typical locale settings are ``de_DE'' for German in Germany, ``fr_BE'' for French in Belgium, ``ga_IE'' for Irish in Eire, and so on; your mileage may vary.

All occurencies of HTML special characters (less-than, greater-than, ampersand, double quote, single quote) in the string returned by strftime(3) are properly escaped.

Xstrftimeoff:OFFSET:LOCALE:FORMAT

NEW: Like Xstrftime() but allows to specify an offset to the current date and time (or a fixed date and time). OFFSET is made up of an arbitrary number of tokens of the form SIGN NUMBER UNIT. For each token the optional SIGN must be one of

'+' Add the following value to the current date and time.
'-' Subtract the following value to the current date and time.

The mandatory decimal NUMBER may be followed by an optional unit:

's' seconds
'm' minutes (always 60 seconds)
'h' hours (always 3600 seconds)
'D' days (always 86400 seconds)
'W' weeks (always 604800 seconds, i. e. 7 days)
'M' months (always 2592000 seconds, i. e. 30 days)
'Y' years (always 378432000 seconds, i. e. 365 days)

Leap seconds and leap days are ignored, so are the differences in the number of days for the months of the year.

Examples:

+1W-1D Today plus one week minus one day.: 600 Now plus 600 seconds.

+1M Today plus one month.
+1M Today plus one month.

Note that the algorithm tries to be smart when calculating the resulting date. If you specify an offset of 3 months on the 13th day of the month, you will always end up on the 13th of three months ahead (i. e., 3 months is not simply 3 times 30 days or the like). If the ``target'' day does not exist (31st, 30th, or February, 29th, ...) the first existing day before the non-existing one is selected.

blocklog:xxx

Blocks locking according to value. If zero or empty, logging is enabled, otherwise disabled. NEW: The colon after the keyword is mandatory now! FIMXE: What does that mean???

IMPERIA_MORALBOT:FILTHLEVEL

Filters out swear words, blasphemy, and explicit content from the generated article to a degree specified by FILTHLEVEL. Please use this feature with extreme precaution, carefully increasing the FILTHLEVEL until you reach a value that is still tolerable for your system. Beware not to exaggerate because this feature is quite expansive and may impose an unacceptable load on your system. You should forget altogether about using it unless your processor fan is capable of doing at least one zillion BogoFloppies per moron. Use at your own risk!

SECTION:FIELD:LEVEL

The part FIELD:LEVEL is passed verbatim to the section callback method. For the default implementation, see the documentation for describe() in Category::Talker(3). NEW: This is a new feature.

SECTION_DESCR:LEVEL

Compatibility tweaK. This is equivalent to . Note that the old keyword 'SECTION-DESCR' really referred to the category name, not the category description. NEW: The old syntax 'SECTION-DESCR' is no longer recognized.

AUTHOR