NAME

Sympa::Template - Template parser

SYNOPSIS

use Sympa::Template;

$template = Sympa::Template->new;
$template->parse($data, $tpl_file, \$output);

DESCRIPTION

Methods

• new ( $that, [ property defaults ] )

  Constructor. Creates new Sympa::Template instance.

  Parameters:

  • $that

    Context. Site, Robot or List.

  • property defaults

    Pairs to specify property defaults.

• parse ( $data, $tpl, $output, [ has_header => 1 ] )

  Instance method. Parses template and outputs result.

  Parameters:

  • $data

    A HASH ref containing the data.

  • $tpl

    A string that contains the file name. Or, scalarref or arrayref that contains the template.

  • $output

    A file descriptor or a reference to scalar for the output.

  • has_header => 0|1

    If 1 is set, prepended header fields are assumed, i.e. one newline will be inserted at beginning of output.

  • is_not_template => 0|1

    This option was obsoleted.

  Returns:

  On success, returns 1 and clears {last_error} property. Otherwise returns undef and sets {last_error} property.

Properties

Instance of Sympa::Template may have following attributes.

• {allow_absolute}

  If set, absolute paths in INCLUDE directive are allowed.

• {include_path}

  Reference to array containing additional template search paths.

• {last_error}

  Read only. Error occurred at the last execution of parse, or undef.

• {subdir}, {lang}, {lang_only}

  TBD.

Filters

These custom filters are defined by Sympa::Template. See Template::Manual::Filters about usage of filters.

• canonic_email

  Canonicalize e-mail address.

  This filter was added by Sympa 6.2.17.

• decode_utf8

  No longer used.

• encode_utf8

  No longer used.

• escape_cstr

  Applies C-style escaping of a string (not enclosed by quotes).

  This filter was added on Sympa 6.2.37b.1.

• escape_quote

  Escape quotation marks.

  Deprecated. Use escape_cstr.

• escape_url

  Escapes URL.

  This was OBSOLETED. Use “mailtourl” instead.

• escape_xml

  OBSOLETED. Use “xml” in Template::Manual::Filters.

• helploc ( parameters )
• l ( parameters )

• loc ( parameters )

  Translates text using catalog. Placeholders (%1, %2, …) are replaced by parameters.

• locdt ( argument )

  Generates formatted (i18n’ized) date/time.

  • Filtered text

    strftime() style format string.

  • argument

    A string representing date/time: “YYYY/MM”, “YYYY/MM/DD”, “YYYY/MM/DD/HH/MM” or “YYYY/MM/DD/HH/MM/SS”.

• mailbox ( email, [ comment ] )

  Generates mailbox string appropriately encoded to suit for addresses in header fields.

  • Filtered text

    Display name, if any.

  • email

    E-mail address.

  • comment

    Comment, if any.

  This filter was introduced on Sympa 6.2.42.

• mailto ( email, [ {key => val, …}, [ nodecode ] ] )

  Generates HTML fragment linking to mailto: URL, i.e. <a href="mailto:_email_">_filtered text_</a>.

  • Filtered text

    Content of linking element. If it does not contain nonspaces, e-mail address will be used.

  • email

    E-mail address(es) to be linked.

  • {key => val, …}

    Optional query.

  • nodecode

    If true, assumes arguments are not encoded as HTML entities. By default entities are decoded at first.

    This option does not affect filtered text.

  Note: This filter was introduced by Sympa 6.2.14.

• mailtourl ( [ {key = val, …} ] )

  Generates mailto: URL.

  • Filtered text

    E-mail address(es). Note that any characters must not be encoded as HTML entities.

  • {key = val, …}

    Optional query. Note that any characters must not be encoded as HTML entities.

  Note: This filter was introduced by Sympa 6.2.14.

• obfuscate ( mode )

  Obfuscates email addresses in the HTML text according to mode.

  • Filtered text

    HTML document or fragment.

  • mode

    Obfuscation mode. at or javascript. Invalid mode will be silently ignored.

  Note: This filter was introduced by Sympa 6.2.14.

• optdesc ( type, withval )

  Generates i18n’ed description of list parameter value.

  As of Sympa 6.2.17, if it is called by the web templates (in web_tt2 subdirectories), special characters in result will be encoded.

  • Filtered text

    Parameter value.

  • type

    Type of list parameter value: Special types (See “field_type” in Sympa::ListDef) or others (default).

  • withval

    If parameter value is added to the description. False by default.

• permalink_id

  Calculate permalink ID from message ID.

  Note: This filter was introduced by Sympa 6.2.71b.

• qencode

  Encode string by MIME header encoding. Despite its name, appropriate encoding scheme (Q or B) will be chosen.

• unescape

  No longer used.

• url_abs ( … )

  Same as “url_rel” but gives absolute URI.

  Note: This filter was introduced by Sympa 6.2.15.

• url_rel ( [ paths, [ query, [ fragment ] ] ] )

  Gives relative URI for specified action.

  If it is called by the web templates (in web_tt2 subdirectories), HTML entities in the arguments will be decoded and special characters in resulting URL will be encoded.

  • Filtered text

    Name of action.

  • paths

    Array. Additional path components.

  • query

    Hash. Optional query.

  • fragment

    Scalar. Optional fragment.

  Note: This filter was introduced by Sympa 6.2.15.

• wrap ( init, subs, cols )

  Generates folded text.

  • init

    Indentation (or its length) of each paragraph if any.

  • subs

    Indentation (or its length) of other lines if any.

  • cols

    Line width, defaults to 78.

Note:

Calls of “helploc”, “loc” and “locdt” in template files are extracted during packaging process and are added to translation catalog.

Plugins

Plugins may be placed under LIBDIR/Sympa/Template/Plugin. See <https://www.sympa.community/manual/customize/template-plugins.html> about usage of plugins.

SEE ALSO

Template::Manual.

HISTORY

Sympa 4.2b.3 adopted template engine based on Template Toolkit.

Plugin feature was added on Sympa 6.2.

tt2 module was renamed to Sympa::Template on Sympa 6.2.