Template::Magic uses the Template::Magic::Zone objects to internally represent zones.
A reference to the Zone object is passed as a parameter to each handler and is passed to your subroutines whenever an identifier trigger their execution.

Note: If you plan to write your own extension,
please,
feel free to ask for more support: the documentation in this distribution is not yet complete for that purpose.

With Template::Magic the output generation is so flexible and customizable,
because it can be changed DURING THE PROCESS by several factors coming both from the code (e.g.
the type of value found by the lookup()),
or from the template (e.g.
the literal id of a zone),
or whatever combination of factors you prefer.

It's important to understand that - for this reason - the output generation is done recursively by several processes (all customizable by the user) that are executed zone-by-zone,
step-by-step,
deciding the next step by evaluating the handlers conditions.

As you can see, the HANDLER loop is nested inside the ZONE loop, not vice versa. This avoids unneeded recursions in zones that could be wiped out by some handler, thus allowing a faster execution. (for example when the value property of a zone is undefined the zone is deleted).

As a general rule, a *_process is a method that executes in sequence the handlers contained in *_handlers constructor array. In details, these process executes the handlers contained in these constructor arrays:

Since it is called first, and just after the creation of each new zone object, this is a very powerful method that allows you to manage the output generation before any other process. With this method you can even bypass or change the way of calling the other processes.

As other process methods, this process simply calls in turn all the handlers in the zone_handlers constructor array until some handler returns a true value: change the zone_handlers to change this process (see "zone_handlers" in Template::Magic).

The scope of this method is finding out a scalar value from the code to pass to the output_process().

As other process methods, this process simply calls in turn all the handlers in the value_handlers constructor array until some handler returns a true value: change the value_handlers to change this process (see "value_handlers" in Template::Magic).

The scope of this method is processing only the text that comes from the template and that goes into the output (in other words the template content between labels).

As other process methods, this process simply calls in turn all the handlers in the text_handlers constructor array until some handler returns a true value: change the zone_handlers to change this process (see "text_handlers" in Template::Magic).

Note: If the text_handlers constructor array is undefined (as it is by default) the text will be processed by the output_process() instead. Use this method only if you need to process the text coming from the template in some special way, different by the text coming from the code.

The scope of this method is processing the text that comes from the code. It is usually used to process the text coming from the template as well if the text_process() method is not used (i.e. no defined text_handlers).

As other process methods, this process simply calls in turn all the handlers in the output_handlers constructor array until some handler returns a true value: change the zone_handlers to change this process (see "output_handlers" in Template::Magic).

This method is called at the end of the process, after the production of the output. It is not used by default. Use it to clean up or log processes as you need.

As other process methods, this process simply calls in turn all the handlers in the post_handlers constructor array until some handler returns a true value: change the zone_handlers to change this process (see "post_handlers" in Template::Magic).

The Zone package has a convenient AUTOLOAD method that allows you to retrive or set a propery of the zone object.

All the properties are lvalue methods, that means that you can use the property as a left value :

# to set classical way (it works anyway)
$z->value('whatever') ;
# to set new way (lvalue type)
$z->value = 'whatever' ;
$the_value = $z->value ; # to retrive

If you plan to customize the behaviours of Template::Magic, you will find useful the AUTOLOAD method. You can automatically set and retrieve your own properties by just using them. The following example shows how you can add a custom 'my_attributes' property to the zone object

In the template zone 'my_zone':

text {my_zone attr1 attr2 attr3} content {/my_zone} text

These are the properties right after the parsing:

$zone->id is set to the string 'my_zone'
$zone->attributes is set to the string ' attr1 attr2 attr3'
$zone->content is set to the string ' content '

If you want to have your own 'my_attributes' property, structured as you want, you could do this:

The following are the properties that Template::Magic uses to do its job: they all are left value properties (lvalue means that you can create a reference to it, assign to it and apply a regex to it; see also "KNOWN ISSUE").

The attributes property allows you to access the attributes string. This string contains everything between the end of the label IDENTIFIER and the END_LABEL marker. It returns the empty string when there are no attributes.

The content property allows you to retrieve the zone content. The zone content is defined only for blocks (i.e. only with zones that have a start and an end label). If the zone is a single label zone, the content property will return the undef value.

This property is added by the _EVAL_ATTRIBUTES_ zone handler (if you explicitly use it), and - in that case - holds the evalued attributes structure. You can use this property to hold your favorite structure: just create it with a simple zone handler as _EVAL_ATTRIBUTES_.

This property holds the reference to the container zone. It is undefined only if the zone is the main template zone and if the file is not included. If the file is included the container is the zone where the INCLUDE_TEMPLATE label was found.

This property holds the number of nesting level of the zone. -1 for the main template zone, 0 for the zones at the template level, 1 for the zone nested in a zone at the template level and so on. In other words ($z->level < 0) for the main template zone and ($z->level > 0) if the zone is nested. The level number of a zone in an included file is relative to the main template file, not to the file itself.

This propery holds the value of the matching identifier at that particular moment of the output generation.

It's important to understand that the value_process() implies a recursive assignation to this property (not to mention that other processes could set the property as well). That means that the value property will return different values in different part of that process. For example: if you have this simple template:

At the beginning of the process, the value property will return a reference, then (after passing through the other value handlers) it will be dereferenced and so the value property, at that point, will return 'I am a simple string'.

Note: In order to make it work, if the found value is a SCALAR or a REFERENCE it must be set the value property 'as is'; if it is anything else, it must be set as a reference. For example:

Due to the perl bug #17663 (Perl 5 Debugger doesn't handle properly lvalue sub assignment), you must know that under the -d switch the lvalue sub assignment will not work, so your program will not run as you expect.

Support for all the modules of the Template Magic System is via the mailing list. The list is used for general support on the use of the Template::Magic, announcements, bug reports, patches, suggestions for improvements or new features. The API to the Magic Template System is stable, but if you use it in a production environment, it's probably a good idea to keep a watch on the list.