NAME

Text::MagicTemplateX::Core - Core extensions for Text::MagicTemplate.

SYNOPSIS

$mt = new Text::MagicTemplate;

# that means
$mt = new Text::MagicTemplate { -markers    => 'DEFAULT',
                                -behaviours => 'DEFAULT' };
# that explicitly means
$mt = new Text::MagicTemplate { -markers    => [ qw( { / } ) ],
                                -behaviours => [ qw( SCALAR
                                                     REF
                                                     CODE
                                                     ARRAY
                                                     HASH   ) ] };
# with _EVAL_ behaviour
$mt = new Text::MagicTemplate { -behaviours => [ qw( DEFAULT _EVAL_ ) ] };

# with HTML comment-like markers
$mt = new Text::MagicTemplate { -markers    => 'HTML' };

DESCRIPTION

Text::MagicTemplateX::Core is the core collection of behaviour extensions for Text::MagicTemplate. It includes all the 'DEFAULT' markers and behaviours extensions, plus the '_EVAL_' behaviour extension, all distributed with Text::MagicTemplate.

In order to fully understand this documentation, you should have already read:

• Text::MagicTemplate (general documentation about the MagicTemplate system)

• Text::MagicTemplate::Tutorial

• Text::MagicTemplateX

CORE MARKERS

DEFAULT

The default markers:

START MARKER:  {
END_MARKER_ID: /
END_MARKER:    }

Example of block:

{identifier} content of the block {/identifier}

HTML

HTML-comment-like markers. If your output is a HTML text - or just because you prefer that particular look - you can use it instead of using the default markers.

START MARKER:  <!--{
END_MARKER_ID: /
END_MARKER:    }-->

Example of block:

<!--{identifier}--> content of the block <!--{/identifier}-->

Usage:

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

The main advantages to use it are:

• You can add labels and blocks and the template will still be a valid HTML file.

• You can edit the HTML template with a WYSIWYG editor, keeping a consistent preview of the final output

• The normal HTML comments will be preserved in the final output, while the labels will be wiped out.

If you want to use the HTML behaviours extension too, you should install Text::MagicTemplateX::HTML. See Text::MagicTemplateX::HTML for details.

See also Redefine Markers

CORE BEHAVIOURS

DEFAULT

This is the shortcut for the default collection of behaviour extensions that defines the following behaviours:

SCALAR
REF
CODE
ARRAY
HASH

All the default values are based on a condition that check the found value.

Examples of default behaviours:

The same template: '{block}|before-{label}-after|{/block}'

... with these values...               ...produce these outputs
------------------------------------------------------------------------
$label = 'THE VALUE';            >
$block = undef;
------------------------------------------------------------------------
$label = 'THE VALUE';            >  NEW CONTENT
$block = 'NEW CONTENT';
------------------------------------------------------------------------
$label = 'THE VALUE';            >  |before-THE VALUE-after|
$block = {};
------------------------------------------------------------------------
$label = undef;                  >  |before--after|
$block = {};
------------------------------------------------------------------------
$label = 'THE VALUE';            >  |before-NEW VALUE-after|
%block = (label=>'NEW VALUE');
------------------------------------------------------------------------
$label = 'THE VALUE';            >  |before-NEW VALUE-after|
$block = {label=>'NEW VALUE'};
------------------------------------------------------------------------
$label = 'THE VALUE';            >  NEW CONTENT|before-THE VALUE-after|
@block = ('NEW CONTENT',            |before-NEW VALUE-after|
          {},
          {label=>'NEW VALUE'});
------------------------------------------------------------------------
$label = 'THE VALUE';            >  NEW CONTENT|before-THE VALUE-after|
$block = ['NEW CONTENT',            |before-NEW VALUE-after|
          {},
          {label=>'NEW VALUE'}];
------------------------------------------------------------------------
sub label { scalar localtime }   >  |before-Tue Sep 10 14:52:24 2002-
$block = {};                        after|
------------------------------------------------------------------------
$label = 'THE VALUE';            >  |BEFORE-{LABEL}-AFTER|
sub block { uc shift }
------------------------------------------------------------------------

Different combinations of values and zones can easily produce complex ouputs. See the "HOW TO..." in Text::MagicTemplate::Tutorial.

SCALAR

Condition

a SCALAR value

Action

replacement of the zone with the value

REF

Condition

a REFERENCE value (SCALAR or REF)

Action

dereferencing of the value and apply_behaviour method with the dereferenced value

CODE

Condition

a CODE value

Action

code execution and apply_behaviour method with the returned value. The subroutine will receive the zone object as a parameter.

Description

If you want to avoid the execution of subs, triggered by some identifier, just explicitly omit this behaviour:

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

See Avoid unwanted executions for details. See also Pass parameters to a subroutine

ARRAY

Condition

an ARRAY value

Action

apply_behaviour method with each item of the array, and replacement of the zone with the joined results.

Description

This behaviour generates a loop, merging each value in the array with the zone content and replacing the zone with the sequence of the outputs. See Build a loop and Build a nested loop for details.

HASH

Condition

a HASH value

Action

parse method with the zone content using the hash as temporary lookup.

Description

A HASH value type will set that HASH as a temporary lookup for the zone. Text::MagicTemplate first uses that hash to look up the identifiers contained in the block; then, if unsuccessful, it will search into the other elements of the -lookups constructor array. This behaviour is usually used in conjunction with the ARRAY behaviour to generate loops. See Build a loop and Build a nested loop for details.

_EVAL_

Condition

zone identifier equal to '_EVAL_'

Action

perl eval function with the zone content and apply_behaviour method with the returned value

Description

For obvious reasons you should use this behaviour ONLY if you are the programmer AND the designer. In order to use it, you have to explicitly include this behaviour, because the 'DEFAULT' behaviour collection doesn't include it.

$mt = new Text::MagicTemplate { -behaviours => ['DEFAULT', '_EVAL_'] };

WARNING: Since the result of the eval() will be passed to the apply_behaviour method, you must include this behaviour as the last element in the -behaviours constructor array, or your code will go in an infinite loop.

SEE ALSO

• Text::MagicTemplate

• Text::MagicTemplate::Zone

• Text::MagicTemplate::Tutorial

• Text::MagicTemplateX

• 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::Core.

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.