/ 
Konstrukt-0.5-beta1
River stage zero No dependents
/ Konstrukt::Plugin::template

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:

  • $tag - Reference to the tag (and its children) that shall be handled.

execute

Execute method

Parameters:

  • $tag - Reference to the tag (and its children) that shall be handled.

process

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

Parameters:

  • $tag - Reference to the tag (and its children) that shall be handled.

  • $execute - Should be a true value, when we're in the execute-run

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:

  • $tag - The root tag of the tree to process

scan_for_values

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

Parameters:

  • $tag - The root tag of the tree to process

  • $current - The current list values, which will be merged with the new ones

scan_for_templates

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

Parameters:

  • $tag- The root tag of the result tree

substitute

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

Parameters:

  • $template - The hashref which points to the template elements inside the template file.

  • $values - The hashref which points to the field elements.

  • $tag - The template tag

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:

  • $tag - The root tag of the tree to process

  • $values - Reference to the template values

  • $path - The absolute path of the template file

node

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

Parameters:

  • $filename - The filename of the template to load

  • $data - Hash reference with the data to put into the template. Will look like this:

    #generic form (see SYNOPSIS):
my $data = {
	fields => {
		field1 => 'value1',
		field2 => 'value2'
	},
	lists => {
		list1 => [
			{ fields => { field1 => 'a', field2 => 'b' } },
			{ fields => { field1 => 'c', field2 => 'd' } },
			...
		]
	}
};

#short form:
#all hash keys that do not point to an hash- or array-reference will be interpreted as a field-value.
#all hash keys that point to array references will be interpreted as lists.
#so the short form of the example above would look like this:
my $data = {
	field1 => 'value1',
	field2 => 'value2',
	list1 => [
		{ field1 => 'a', field2 => 'b' },
		{ field1 => 'c', field2 => 'd' },
		...
	]
}
#this will lead to some ambiguities in the short form:
# - you cannot define a list and a field with the same name.
# - you cannot define fields or lists with the name 'fields' or 'lists'
#   as they will be interpreted as the container for those.

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:

  • $data - Hash reference with the data to put into the template

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