/ 
Template-Magic-1.3
River stage one • 2 direct dependents • 2 total dependents
/ Template::Magic::Zone

NAME

Template::Magic::Zone - The Zone object

VERSION 1.3

Included in Template-Magic 1.3 distribution.

The latest versions changes are reported in the Changes file in this distribution.

DESCRIPTION

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: Unless you plan to write an extension or some custom solution, you will find useful just the "attributes", "content" and "param" properties that you can use to retrieve parameters from your subroutines (see "Pass parameters to a subroutine" in Template::Magic), and the "include_template()" method that you can use to include templates from inside your code (see "Conditionally include and process a template file" in Template::Magic).

ZONE OBJECT METHODS

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.

This is a sloppy code to better understand the whole process:

ZONE: while ($zone = find_and_create_the_zone)
      {
        foreach $process (@all_the_process)
        {
          HANDLER: foreach $handler (@$process)
                   {
                     $handler->($zone)
                   }
        }
      }

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).

These are the processes that are executed for any single zone:

content process
  nested zones creation
    zone process
    lookup process
    value process
    text & output processes
  post process

As 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:

zone_process()    zone_handlers
value_process()   value_handlers
text_process()    text_handlers
output_process()  output_handlers
post_process()    post_handlers

Note: the lookup_process and the content_process are exceptions to this rule.

content_process()

This method starts (and manage) the output generation for the zone: it process the zone content, creates each new zone object and apply the appropriate process on the new zones.

Note: You can change the way of parsing by customizing the markers constructor array. You can change the resulting output by customizing the other constructor arrays.

zone_process()

The scope of this method is organizing the Zone object.

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).

lookup([identifier])

This method tries to match a zone id with a code identifier: if it find a match it returns the value of the found code identifier, if it does not find any match it returns the undef value.

If identifier is omitted, it will use the zone id. Pass an identifier to lookup values from other zones.

This method looks up first in the containers found values, then in the lookups locations. You can customize the lookup by changing the items in the lookups constructor array.

lookup_process()

The scope of this method is setting the zone value with a value from the code. It executes the lookup() method with the zone id

Note: it works only IF the zone value property is undefined.

value_process()

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).

Note: it works only IF the zone value property is defined.

text_process()

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.

output_process()

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).

post_process()

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).

include_template( template )

This method loads and process a template. It is useful specially if you want to conditionally load and process a template from inside your code. (see "Conditionally include and process a template file" in Template::Magic)

AUTOLOAD()

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:

# creates a 'my_attributes' property
# and set it to an array ref containing one word per element
$zone->my_attributes = [ split /\s+/,  substr( $zone->attributes, 1) ]

From now on you can retrieve the attributes your way:

# retrieves the second attribute
print $zone->my_attributes->[1]

# would print
attr2

PROPERTIES

The following are the properties that Template::Magic uses to do its job: they all are left value properties.

tm

The tm property allows you to access the Template::Magic object.

Note: this is a read only property.

mt

Obsolete and deprecated property: use tm instead.

id

The id property allows you to access the zone identifier. It is undefined only if the zone is the main template zone

Note: this is a read only property.

attributes

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.

Note: this is a read only property.

content

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.

Note: this is a read only property.

param

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_.

container

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.

Note: this is a read only property.

level

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.

location

This property holds the package name, the blessed object or the hash reference from which comes the matching identifier at that particular moment of the process.

Usually you don't need to set this property, but you could find it very useful, for example, to access the object methods of a lookup element from inside an extension. (more documentation to come)

value

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:

text {my_id_label} text

and this simple code where Template::Magic is looking up:

$scalar = 'I am a simple string';
$reference = \$scalar;
$my_id_label = $reference;

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:

found values          value of $zone->value
------------------------------------
'SCALAR'              'SCALAR'
(1..5)                [1..5]
[1..5]                [1..5]
(key=>'value')        {key=>'value'}
{key=>'value'}        {key=>'value'}
------------------------------------

output

This property holds the output string coming from the code.

is_main

Boolean property: it returns true if the zone is a main template zone.

Note: this is a read only property.

_t

This property holds the reference to the template structure.

_s

This property holds the offset of the template chunk where the content starts. Use it to re-locate the content of a zone and only if you know what you are doing.

_e

This property holds the offset of the template chunk where the content ends. Use it to re-locate the content of a zone and only if you know what you are doing.

SEE ALSO

SUPPORT

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.

You can join the Template Magic System mailing list at this url:

http://lists.sourceforge.net/lists/listinfo/template-magic-users

AUTHOR and COPYRIGHT

© 2004 by Domizio Demichelis (http://perl.4pro.net)

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 483:

Non-ASCII character seen before =encoding in '©'. Assuming CP1252