/ 
Text-Xslate-0.3001
River stage two • 72 direct dependents • 86 total dependents
/ Text::Xslate::Manual::FAQ

NAME

Text::Xslate::Manual::FAQ - Frequently asked questions and answers

QUESTIONS

General

How do you pronounce Xslate?

We read it /eks-leit/.

What Xslate stands for?

It stands for XS template, a template engine written in XS, although pure Perl implementations are also provided.

What are 'Kolon', 'Metakolon', and 'TTerse' ?

Xslate supports multiple template syntaxes. Kolon is the default syntax, Metakolon is suitable to output Kolon templates, and TTerse is compatible with Template-Toolkit. You can specify the template syntax by passing syntax option to the Text::Xslate constructor.

my $tx = Text::Xslate->new(
    syntax => 'TTerse', # by moniker
);

my $tx = Text::Xslate->new(
    syntax => 'Text::Xslate::Syntax::TTerse', # by fully qualified name
);

Templates

How can I changes template tags?

Use start_tag, end_tag, and line_start options to new method, which can be joined together with syntax option:

my $tx = Text::Xslate->new(
    syntax     => 'TTerse',
    tag_start  => '{',
    tag_end    => '}',
    line_start => undef,
);
print $tx->render_string('Hello, {lang} world!', { lang => 'Xslate' });

How can I iterate over HASH references?

Convert HASH references into ARRAY references because for methods can deal with ARRAY references.

: # in Kolon
: # iterate $hash by keys
: for $hash.keys() -> $key {
    <: $key :>
: }
: # by values
: for $hash.values() -> $value {
    <: $value :>
: }
: # by key-value pairs
: for $hash.kv() -> $pair {
    <: $pair.key :>=<: $pair.value :>
: }

Note that the above methods return ARRAY references sorted by the keys.

How can I use Template-Toolkit virtual methods and filters?

Xslate itself does not support these methods and filters, but there are modules on CPAN that implement them.

Text::Xslate::Bridge::TT2 provides almost all the TT methods and filters, but it requires Template-Toolkit installed.

Text::Xslate::Bridge::TT2Like provides the same features as T::X::Bridge::TT2, but it does not require the Template-Toolkit distribution.

These bridge modules are useful not only for TTerse users, but also for Kolon users.

How can I (write|get) plugins?

It is unlikely to write plugins for Xslate, because Xslate allows you to export any functions to templates. Any function-based modules are available by the module option to the new method.

Xslate also allows to call methods for object instances, so you can use any object-oriented modules, except for classes which only provide class methods (they need wrappers).

If you want to add methods to builtin data types (nil, scalars, arrays and hashes), you can write bridge modules. See Text::Xslate::Bridge for details.

How to limit while-loop like Template-Toolkit?

While Template-Toolkit has a loop counter to prevent runaway WHILE loop, Xslate has no arbitrary limitation.

Instead, you can use alarm() to limit any runaway code:

eval {
    local $SIG{ALRM} = sub { die @_ };
    alarm(1); # set timeout
    $tx->render('<: while true { } :>', \%vars);
};
if($@ =~ /\b ALRM \b/xms) {
    # timeout!
}

Does Xslate process text strings, or binary strings?

(The meaning of text string and binary string is that of Perl, see perlunifaq.)

Xslate assumes template files to be encoded in UTF-8 by default, so the output is a text string and template parameters must be text strings. However, if you want to process binary strings, you can do by passing :raw for input_encoding.

Functions, filters and macros

How can I use macros as a callback to high-level functions?

Macros are objects that overload &{}, the CODE dereference operator, so all you have to do is to call them, but don't check their types because they are not a real CODE reference.

my $tx = Text::Xslate->new(
    function => {
        count => sub {
            my($a, $cb) = @_;
            # Don't check the type of $cb!
            return scalar grep { $cb->($_) } @{$a};
        },
    },
);

print $tx->render_string('<: count($a, -> $x { $x >= 50 }) :>',
    { a => [ 0 .. 100 ] },
); # => 50

Development

How can I colorize Xslate templates?

If you are a vim user, there is xslate.vim for Kolon: https://github.com/motemen/xslate-vim

Web Application Frameworks

How can I use Xslate into my favorite WAF?

There are bridges that integrate Xslate into WAFs:

SEE ALSO

Text::Xslate

Text::Xslate::Manual