/ 
HTML-MagicTemplate-3.04
/ HTML::MagicTemplate

NAME

HTML::MagicTemplate - HTML handlers for Text::MagicTemplate used in a HTML environment.

VERSION 3.04

SYNOPSIS

$mt = new HTML::MagicTemplate;

# that means
$mt = new Text::MagicTemplate
          markers        => 'HTML' ,
          value_handlers => 'HTML' ;
          
# that explicitly means
$mt = new Text::MagicTemplate
          markers        => [ qw( <!--{ / }--> ) ],
          value_handlers => [ qw( SCALAR
                                  REF
                                  CODE
                                  TableTiler
                                  ARRAY
                                  HASH
                                  FillInForm ) ] ;

DESCRIPTION

HTML::MagicTemplate is a collection of handlers for Text::MagicTemplate useful when used in a HTML environment. It adds a couple of magic HTML specific value handlers to Text::MagicTemplate default value handlers. Just create and use the MagicTemplate object as usual, to have a trasparent interface to HTML::TableTiler and HTML::FillInForm too.

Other interesting readings about how to use this collection are in:

INSTALLATION

Prerequisites
perl                >= 5.005
Text::MagicTemplate >= 3.0
HTML::TableTiler    >= 1.0
HTML::FillInForm    >= 1.0
CPAN

If you want to install this extensions collections and prerequisites plus Text::MagicTemplate, all in one easy step:

perl -MCPAN -e 'install Bundle::Text::MagicTemplate'
Standard installation

From the directory where this file is located, type:

perl Makefile.PL
make
make test
make install
Uninstallation of obsolete modules

If you have installed some 2.xx version you could want to uninstall the obsolete files from that installation. You should manually unlink (delete) the following files and directories (sorry, no automatic uninstallation yet):

Text/MagicTemplate/Tutorial.pm
Text/MagicTemplate/Utilities.pm
Text/MagicTemplateX.pm
Text/MagicTemplateX directory including all its content

HTML VALUE HANDLERS

HTML

This is the shortcut for the complete HTML collection of handlers that defines the following value handlers:

SCALAR
REF
CODE
TableTiler
ARRAY
HASH
FillInForm

See "standard value handlers" in Text::MagicTemplate for details about SCALAR REF CODE ARRAY and HASH handlers.

TableTiler
Condition

a bidimensional array value

Action

magic generation of HTML table. No need to create and use a HTML::TableTiler object: this handler will manage it magically.

Description

The bidimensional array:

$matrix_generating_a_table = [ [1..3], 
                               [4..6], 
                               [7..9] ];

The template could be as simple as a simple label with the same identifier of the bidimensional array:

<p>paragraph text</p>
<!--{matrix_generating_a_table}-->
<p>other paragraph</p>

so the output will be a generic table including the array data:

<p>paragraph text</p>
<table>
<tr>
    <td>1</td>
    <td>2</td>
    <td>3</td>
</tr>
<tr>
    <td>4</td>
    <td>5</td>
    <td>6</td>
</tr>
<tr>
    <td>7</td>
    <td>8</td>
    <td>9</td>
</tr>
</table>
<p>paragraph text</p>

or the template could be a complete table Tile included in a block with the same identifier of the bidimensional array, and with the optional ROW and COL TableTiler modes, passed as label attributes:

<p>paragraph text</p>
<!--{matrix_generating_a_table H_TILE V_TILE}-->
<table border="1" cellspacing="2" cellpadding="2">
<tr>
    <td><b><i>?</i></b></td>
    <td>?</td>
</tr>
<tr>
    <td>?</td>
    <td><b><i>?</i></b></td>
</tr>
</table>
<!--{/matrix_generating_a_table}-->
<p>other paragraph</p>

so the output will be a complete tiled table including the array data:

<p>paragraph text</p>
<table border="1" cellspacing="2" cellpadding="2">
<tr>
    <td><b><i>1</i></b></td>
    <td>2</td>
    <td><b><i>3</i></b></td>
</tr>
<tr>
    <td>4</td>
    <td><b><i>5</i></b></td>
    <td>6</td>
</tr>
<tr>
    <td><b><i>7</i></b></td>
    <td>8</td>
    <td><b><i>9</i></b></td>
</tr>
</table>
<p>paragraph text</p>

See HTML::TableTiler for details about this module.

Note: if your template don't need this specific handler you can avoid its loading by explicitly omitting it:

$mt = new HTML::MagicTemplate
          value_handlers => [ qw( SCALAR
                                  REF
                                  CODE
                                  ARRAY
                                  HASH
                                  FillInForm ) ] ;

Warning: since this handler checks for a bidimensional ARRAY, it must be checked BEFORE the ARRAY value handler in order to work.

FillInForm
Condition

a CGI query object value (or by a blessed object that has a param() method)

Action

magic fill in of a HTML form with the parameter in the CGI object

Description

The CGI object in your code:

$my_query = new CGI;

If you want to fill a form with the param in the $my_query, just transform the form into a block giving it the same identifier.

<!--{my_query}-->
<form action="my.cgi">
...
</form>
<!--{/my_query}-->

One useful application of this handler is when a user submits an HTML form without filling out a required field. FillInForm handler will magically redisplay the form with all the form elements (input, textarea and select tags) filled with the submitted info ($my_query), without any other statement in your code. (No need to create and use a HTML::FillInForm object: this handler will manage it magically).

You can use this handler to fill the form with default values too, To do this, just create a new query object and fill it with the default param that you want in the form:

$query = new CGI;
$query->param( name    => 'John', 
               surname => 'Smith', ...);

See HTML::FillInForm for details about this module.

Note: if your template don't need this specific handler you can avoid its loading by explicitly omitting it:

$mt = new HTML::MagicTemplate
          value_handlers => [ qw( SCALAR
                                  REF
                                  CODE
                                  TableTiler
                                  ARRAY
                                  HASH ) ] ;

SEE ALSO

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/?HTML::MagicTemplate.

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.