/ 
Text-MagicTemplate-2.1
/ Text::MagicTemplateX

NAME

Text::MagicTemplateX - namespace used by the extensions of Text::MagicTemplate

DESCRIPTION

Text::MagicTemplateX:: is the namespace used by the extensions of Text::MagicTemplate. This documentation cover the extension system in general: each extension collection is supposed to be documented with its own POD file.

Extensions are simple files that Text::MagicTemplate will include with the do() statement when it construct a new object. See "-markers" in Text::MagicTemplate and "-behaviours" in Text::MagicTemplate for details.

Naming Conventions and Namespaces

The Text::MagicTemplate package and all packages below it (Text::MagicTemplate::*) are reserved for Text::MagicTemplate. Collection of extensions use the Text::MagicTemplateX:: namespace. An extension collection is a related collection of one or more markers extensions and/or behaviours extensions.

Core extensions names are all capitals (see Text::MagicTemplate::Core), so, in order to avoid confusion, other extension names should just begin with a capital letter (same rules as modules name convenction).

Behaviours extensions that involve the use of reserved identifiers (as the '_EVAL_' core behaviour extension name), should be started and ended with the underscore character '_', to avoid confusion with user identifiers.

If you are planning to write your own extension, please, let me know the namespace you intend to use.

MARKERS EXTENSIONS

Markers extensions are used just as a shortcut, to avoid to remember complicated markers. Markers extensions are files that simply return a reference to a 3 element array of the markers you want to use to define templates zones.

Markers extension files are stored in the Text::MagicTemplateX dir, and have '.m' suffix. For example, the 'Text/MagicTemplateX/HTML.m' file has this content:

[qw(<!--{ / }-->)]

When you type:

$mt = new Text::MagicTemplate { -markers => 'HTML' }

'HTML' is interpreted as the markers extension name and the -markers constructor array will be set to the result of the execution of the Text/MagicTemplateX/HTML.m file. This has the identical effect of:

$mt = new Text::MagicTemplate { -markers => do 'Text/MagicTemplateX/HTML.m' }

that means:

$mt = new Text::MagicTemplate { -markers => [qw(<!--{ / }-->)] };

BEHAVIOURS EXTENSIONS

Behaviours extensions are files stored in the Text::MagicTemplateX dir, and have '.b' suffix.

Behaviours extensions may return a reference to an array of names of other behaviours extensions, or a reference to a subroutine:

reference to array

When you type:

$mt = new Text::MagicTemplate;
# this explicitly means
$mt = new Text::MagicTemplate { -behaviours => 'DEFAULT' };

'DEFAULT' is interpreted as a behaviour extension name and the Text/MagicTemplateX/DEFALT.b file is executed with the do() statement. This has the same effect of:

$mt = new Text::MagicTemplate { -behaviours => do 'Text/MagicTemplateX/DEFALT.b' };

Since the 'Text/MagicTemplateX/DEFAULT.b' file returns a reference to an array of behaviours extension names:

[qw(SCALAR REF CODE ARRAY HASH)]

the previous code line explicitly means:

$mt = new Text::MagicTemplate { -behaviours => [qw(SCALAR REF CODE ARRAY HASH)] };

Since the -behaviour constructor array is used to construct a switch-like condition, in the end, it must contain only references to callback subroutines, so the previous code will be interpreted this way:

$mt = new Text::MagicTemplate { -behaviours => [
                                                  do 'Text/MagicTemplateX/SCALAR.b',
                                                  do 'Text/MagicTemplateX/REF.b',
                                                  do 'Text/MagicTemplateX/CODE.b',
                                                  do 'Text/MagicTemplateX/ARRAY.b',
                                                  do 'Text/MagicTemplateX/HASH.b'
                                                ] };

where each do() statement will return a reference to the sub contained in the behaviours extension file.

reference to subroutine

The final goal of a behaviours extension is to supply a callback subroutine capable of generate a conditional output. (see "-behaviours" in Text::MagicTemplate for details).

The callback subroutine will receive the following parameters:

  • $_[0]

    the magic template object reference: used to execute object methods. (see "PRIVATE METHODS")

  • $_[1]

    the zone object reference, used to access the zone methods. (see "ZONE OBJECT METHODS")

The callback subroutine may use or ignore the received parameter, in order to setup the condition and generate the output.

See these examples:

SCALAR (Core behaviour)

This sub returns the found value ($z->value), if it is not a reference (SCALAR), and ignores all other passed paramenter

sub
{
    my ($s, $z) = @_;
    !ref $z->value
    && $z->value
}
HASH (Core behaviour)

This sub pass the zone object ($z) to the object ($s) parse method, if the found value is a reference to HASH.

sub
{
    my ($s, $z) = @_;
    ref $z->value eq 'HASH'
    && $s->parse($z)
}
_EVAL_ (Core behaviour)

This sub set the value of the zone to the evaluated content and pass the ref to the zone object to the object apply_behaviour method, if the zone identifier is equal to '_EVAL_'.

sub
{
    my ($s, $z) = @_;
    $z->id eq '_EVAL_'
    && $s->apply_behaviour($z->value(eval $z->content))
}
TableTiler (Text::MagicTemplateX::HTML behaviour)

When included with the do() statement, this behaviour extension loads HTML::TableTiler module, then if the value is a reference to an array, it pass the value, the zone content (if it exists), and the zone attributes to the HTML::TableTiler::tile_table funcion. The eval{...} statement traps the possible errors and returns undef if it not succeed, or the tiled table if it succeed.

use HTML::TableTiler ;

sub
{
    my ($s, $z) = @_;
    ref $z->value eq 'ARRAY'
    && eval
    {
        local $SIG{__DIE__};
        HTML::TableTiler::tile_table( $z->value, $z->content && \$z->{content}, $z->{attributes} )
    }
}

Check other behaviours files in the Text/MagicTemplateX dir in order to better understand the possibility of the extension system. See also the behaviours distributed with the Text::MagicTemplateX::HTML collection.

PRIVATE METHODS

This is a brief documentation of the privates method you may need to use in order to write an extension. If you are planning to do so, please, feel free to ask me for additional support.

parse ( self, zone )

This method parses a template_string in order to find template zones, calling the lookup method each time a zone is found, thus generating the output relative to that template string.

lookup ( self, zone )

This method scans the -lookups constructor array to found a value in the code, then it pass it to the apply_behaviour method

apply_behaviour ( self, zone )

This method is pratically a switch conditions that calls in turn each behaviour fallback subroutine, present in the -behaviour constructor array, searching a true value to return to the caller.

ZONE OBJECT METHODS

Since 2.1 version, Text::MagicTemplate uses the Text::MagicTemplate::Zone objects to internally represent zones. A reference to the zone object is passed as a parameter to each behaviour subroutine and is passed to your subroutines whenever an identifier trigger their execution.

id ( [value] )

The id() method allows you to access and set the zone identifier.

attributes ( [value] )

The attributes() method allows you to access and set the attributes string. This string contains everything between the end of the label IDENTIFIER and the END_LABEL marker.

content ( [value] )

The content() method allows you to access and set the zone content

value ( [value] )

The value() method allows you to access and set the found value: since in perl it's impossible to pass multiple values with just one parameter, if the found value is a SCALAR or a REFERENCE it is passed in the $z->value 'as is'; if it is anything else, it is passed as a reference. For example:

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

lookup_element ( [value] )

The lookup_element() method allows you to access and set the lookup element: the element of the -lookups constructor array where the value ($z->value) is found. (see "-lookups" in Text::MagicTemplate for details)

SEE ALSO

Text::MagicTemplate, Text::MagicTemplate::Tutorial, Text::MagicTemplateX::Core, Text::MagicTemplateX::HTML.

SUPPORT and FEEDBACK

I would like to have just a line of feedback from everybody who tries or actually uses this module. PLEASE, write me any comment, suggestion or request. ;-)

More information at http://perl.4pro.net/?Text::MagicTemplateX.

AUTHOR

Domizio Demichelis, <dd@4pro.net>.

COPYRIGHT

Copyright (c)2002 Domizio Demichelis. All Rights Reserved. This is free software; it may be used freely and redistributed for free providing this copyright header remains part of the software. You may not charge for the redistribution of this software. Selling this code without Domizio Demichelis' written permission is expressly forbidden.

This software may not be modified without first notifying the author (this is to enable me to track modifications). In all cases the copyright header should remain fully intact in all modifications.

This code is provided on an "As Is'' basis, without warranty, expressed or implied. The author disclaims all warranties with regard to this software, including all implied warranties of merchantability and fitness, in no event shall the author, be liable for any special, indirect or consequential damages or any damages whatsoever including but not limited to loss of use, data or profits. By using this software you agree to indemnify the author from any liability that might arise from it is use. Should this code prove defective, you assume the cost of any and all necessary repairs, servicing, correction and any other costs arising directly or indrectly from it is use.

The copyright notice must remain fully intact at all times. Use of this software or its output, constitutes acceptance of these terms.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 163:

You forgot a '=back' before '=head1'