<<

NAME

Konstrukt::Plugin::template - Konstrukt templating engine

SYNOPSIS

        <& template src="some.template" &>
                <$ field $>will be inserted in the template<$ / $>
        <& / &>

DESCRIPTION

This is probably the most important plugin of this framework. It provides a mighty and very easy way of templating. There are two interfaces to this plugin. You may use special tags within your documents that will not annoy a non-programmer and fit seemlessly into the other markup. You may also use a perl-interface that will fit into your perl code (plugins or embedded perl).

Tag interface

Within the Konstrukt-templates (*.template) you define fields that will be replaced by content when using this template:

        This is a demotemplate. Some content goes here:
        <+$ content / $+>

Within an other file you call the template like this:

        Other file's text...
        <& template src="demo.template" &>
                <$ content $>This is the content that will be inserted into the template.<$ / $>
        <& / &>

You may specify default values, if no value for a field is passed:

        <+$ content $+>Default content, that may be replaced<+$ / $+>

There is also support for lists. In the template you define one row of the list with some fields.

        <table>
        <+@ my_list @+> <tr><td><+$ field1 / $+></td><td><+$ field2 / $+></td></tr><+@ / @+>
        </table>

You will use the template like this:

        <& template src="list.template" &>
                <@ my_list @>
                        <$ field1 $>1<$ / $><$ field2 $>a<$ / $>
                        <$ field1 $>2<$ / $><$ field2 $>b<$ / $>
                        <$ field1 $>3<$ / $><$ field2 $>c<$ / $>
                <@ / @>
        <& / &>

The row will be repeated on usage of the template. The result would look like this:

        <table>
                <tr><td>1</td><td>a</td></tr>
                <tr><td>2</td><td>b</td></tr>
                <tr><td>3</td><td>c</td></tr>
        </table>

Note that lists of lists are currently not supported.

Perl interface

You may also use a template from your perl code. It will be inserted at the current position in the document where your perl code has been executed. This will be done with the "node" method:

        #get a plugin-object
        my $template = use_plugin 'template';
        
        #values that should be inserted to the template
        my $data = { 
                field1 => 'value1',
                field2 => 'value2'
                some_list => [
                        { field1 => 'a', field2 => 'b' },
                        { field1 => 'c', field2 => 'd' },
                        ...
                ]
        };
        #insert the template
        $self->add_node($template->node('path/to/some.template', $data));

You may also pass tag nodes as the field's content, so nested templates are possible:

        $self->add_node($template->node('some.template', { some_field => $template->node('some_other.template') }));

If you want to pass several nodes as the field's content, you must put them into a field node, which will act like a container:

        #create new field node as a container for some other nodes:
        my $container = Konstrukt::Parser::Node->new({ type => 'tag', handler_type => '$' });
        #add some nodes:
        $container->add_child($some_node);
        #...
        #create template node
        $self->add_node($template->node('some.template', { some_field => $container }));

Take a look at </node> (which has been used in the examples above), which explains the passing of template values a bit more.

CONFIGURATION

For some uncommon situations you may control the behaviour of this plugin with these settings:

        #this setting controls what to do when you have multiple <$ field $>-definitions:
        #0 = overwrite (default). only the last definition will be used
        #1 = join. join all values
        #2 = ignore. only the first definition will be used
        template/join_multiple_fields 0
        
        #this will allow the dynamic generation of <$ field $>'s like this:
        #<& template src="some.template" &>
        #       <$ static_field $>value<$ / $>
        #       <& perl &>print '<$ dynamic_field $>value<$ / $>'<& / &>
        #<& / &>
        #usally you shouldn't do this as it will slow down the execution.
        #if you want dynamic values, you should use the native perl-interface (L</node>) of this plugin.
        #FIXME: additionally this feature doesn't work correctly right now
        template/allow_dynamic_field_value_generation 0

SPEED

This plugin needs another modules to clone data structures. It will try to load them in this order:

        1) Clone
        2) Clone::Any
        3) Scalar::Util::Clone
        4) Storable
        5) Clone::PP

This precedence list is approximateley built to try the module with the best performance first. So you should check, if you've got any of the first modules installed.

METHODS

init

Initialization.

execute_again

Yes, this plugin may return dynamic nodes. E.g. by loading a template containing an perl node.

prepare

Prepare method

Parameters:

execute

Execute method

Parameters:

process

As prepare and execute are almost the same each run will just call this method.

Parameters:

check_preliminary_tags

Traverses the tree and looks for preliminary tags that now may have only plaintext children (as a <+$ variable / $+> might have been replaced by a plaintext node) and thus can be prepared.

Parameters:

scan_for_values

Traverses the tree and creates a handy data structure to easily access the values.

Parameters:

scan_for_templates

Traverses the tree (prepare-result of the block) and creates a handy data structure to easily access the templates.

Parameters:

substitute

Does the template substitution. It will do no parsing, it will just do the substitution on the passed trees.

Parameters:

set_hints

Traverses the tree and adds a reference to the field values to each plugin tag node inside the template (if not already set). Also adds a hint with the path of the current template, which will be used by the parser to track the correct current directory.

The values will then be accessible through $tag->{template_values} and $tag->{template_path}.

Parameters:

node

Return a tag node that will load a template. See "SYNOPSIS" for an example.

Parameters:

normalize_input_data

Will convert the input data, that may be passed in a short form, into the generic form.

Will only be used internally by "node".

Parameters:

AUTHOR

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.

This document is free software. It is distributed under the same terms as Perl itself.

SEE ALSO

Konstrukt::Plugin, Konstrukt

<<