.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "WebFrame::TemplateRex 3pm"
.TH WebFrame::TemplateRex 3pm 2005-03-08 "perl v5.40.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
TemplateRex \- A Template toolkit that partitions code from text and uses nestable sections.
.SH SYNOPIS
.IX Header "SYNOPIS"
.Vb 3
\& # Assuming you have the following:
\& # 1. Template file \- "my_template.html"
\& # 2. Hash consisting of the data to merge with the template \- %data_hsh
\&
\& use TemplateRex;
\&
\& $args{\*(Aqfile\*(Aq} = "my_template.html";
\&
\& $t_rex = new TemplateRex( %args );            # Arguments can be either a hash or hash reference
\&
\& $t_rex\->render(\e%data_hsh);                   # Prints to standard out
\& $t_rex\->render(\e%data_hsh, "rendered.html")   # Prints to a file
\&
\& # Or a functional interface
\& render_this(\e%args, \e%data_hsh);
\& render_this(\e%args, \e%data_hsh, "rendered.html");
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The objective of TemplateRex is to achieve complete separation between
code and presentation. While this module was developed with html generation
in mind it works equally well with any text based files (such as gnuplot scripts).
.PP
Most CGI web based application start off with placing all the html text within print
statements in the code or generate html via functions such as with CGI.pm.  For applications
of any size or sophistication this approach quickly develops maintenance issues such as
.IP \(bu 2
Code becomes bloated with embedded html.
.IP \(bu 2
Cannot leaverage the use of wysiwyg html generators (Dreamweaver, Frontpage).
.IP \(bu 2
The html is within the domain of the code programmer and not the html designers.
.PP
Templates solve this problem by outsourcing the presentation or html outside the code.
The next step of evolution is then to place code within the html (asp, php, jsp) to handle
things like generating rows of a table or repeated sections or chunks of html.  The problem
with appoach are
.IP \(bu 2
HTML becomes bloated with embedded code
.IP \(bu 2
If you are using several 'skins' or templates sets for a different look-and-feel
for an application, pieces of code tend to be replicated in different templates sets.
.IP \(bu 2
Cannot leaverage the use of wysiwyg html generators (Dreamweaver, Frontpage).
.IP \(bu 2
Security issues with templates being able to execute code.  That is you need
to be able to 'trust' your template designers.
.PP
It is the opinion of the author that both extremes present their own sets of problems and
that partitioning of code from presentation into their own separate realms is the best approach
for long term maintenance of large and/or sophisticated web applications.
.SS "Variable Replacement"
.IX Subsection "Variable Replacement"
At the most basic level this module replaces "$variables" within your template with
values of a data hash. For example, if you have a hash with a key of "time" and some
value then that value will replace each \f(CW$time\fR in your template.
.PP
\&\f(CW$data\fR{time} = "Fri Jul 19 17:30:20 PDT 2002";
.PP
Template file:
.PP
.Vb 1
\&   It is now \*(Aq$time\*(Aq
.Ve
.PP
Rendered html:
.PP
.Vb 1
\&   It is now \*(AqFri Jul 19 17:30:20 PDT 2002\*(Aq
.Ve
.SS "Triggered Function Calls"
.IX Subsection "Triggered Function Calls"
In addition the template processor can run user definded Perl functions.
For example if a function exists in your code such as:
.PP
sub _get_time { return scaler localtime }
.PP
Template file
.PP
.Vb 1
\&   It is now &get_time()
.Ve
.PP
Rendered html
.PP
.Vb 1
\&   It is now Fri Jul 19 17:30:20 PDT 2002
.Ve
.PP
Note the use of the underscore prefix is to prevent a template author from
running any function within your code.  Therefore all functions that you
want to trigger from the html template should be defined with a prefix.
The underscore is the default prefix but this default can redefined.
.PP
You can even pass arguments to the triggered function.  For example if you have
a defined function such as:
.PP
sub _get_time
{
 \f(CW$arg\fR = shift \f(CW@_\fR;
 return scalar localtime($arg)
}
.PP
Template file:
.PP
.Vb 1
\&   Last modified on &get_time(1042133373)
.Ve
.PP
Rendered html:
.PP
.Vb 1
\&   Last modified on Thu Jan  9 09:32:45 2003
.Ve
.PP
There is one reserved function call &include_file('my_header.html') that will include
the specified file at the location of were the function is specified.
.SS "Template Section Parsing"
.IX Subsection "Template Section Parsing"
However the unique and most useful part of TemplateRex is the ability to parse a template
based on sections. A template can be sectioned up using html comment delimiters such as
.PP
.Vb 1
\&  <!\-\- BEGIN NAME=error_code  \-\->
\&
\&    You Must Enter Your Credit Card Number !
\&
\&  <!\-\- END NAME=error_code  \-\->
.Ve
.PP
This defines a section with the name "error_code" which could be optionally rendered or
ignored.  For example if you had the above section in your template then the following:
.PP
.Vb 1
\& $t_rex = new TemplateRex( { \*(Aqfile\*(Aq=>"my_template.html" }  );
\&
\& unless ($cc_num) {  $t_rex\->render_sec(\*(Aqerror_code\*(Aq) }
\& $t_rex\->render();
.Ve
.PP
Would insert the error string in the rendered template if \f(CW$cc_num\fR was not defined.
If \f(CW$cc_num\fR was defined then the error message would not appear in the rendered
template.
.PP
Sections can be reused and nested.  If a template section is called more than once then the
rendered section is automatically appended or accumulated.  If a section is nested than the
lower level accumulation is not rendered until the parent section is rendered.  This is best
demonstrated with a simple example.
.PP
If we have a template as shown below that consists of a "tbl" section with a nested "row" section.
This template will be used to render a two column table with a header showing the keys and values
of the global \f(CW%ENV\fR hash.
.PP
Template file:
.PP
.Vb 7
\&     Current Environment Settings <br>
\&     <!\-\- BEGIN NAME=tbl  \-\->
\&        <table>
\&          <tr>
\&            <th> Key    </th>
\&            <th> Value  </th>
\&          </tr>
\&
\&          <!\-\- BEGIN NAME=row \-\->
\&          <tr>
\&            <td> $key   </td>
\&            <td> "$value" </td>
\&          </tr>
\&          <!\-\- END NAME=row \-\->
\&
\&        </table>
\&     <!\-\- END NAME=tbl  \-\->
.Ve
.PP
Now assume you have some code such as:
.PP
.Vb 1
\& $t_rex = new TemplateRex( { \*(Aqfile\*(Aq=>"my_template.html" }  );
\&
\& foreach $key (keys %ENV)
\& {
\&   $data_hsh{\*(Aqkey\*(Aq}   = $key;
\&   $data_hsh{\*(Aqvalue\*(Aq} = $value;
\&
\&   $t_rex\->render_sec(\*(Aqrow\*(Aq, \e%data_hsh);   # Render and accumulate rows
\& }
\&
\& $t_rex\->render_sec(\*(Aqtbl\*(Aq);                 # Render the table with the accumulated rows
\&
\& $t_rex\->render();                          # Render the complete template
.Ve
.PP
The code and template would render something like:
.PP
Rendered html
.PP
.Vb 6
\&   Key       Value
\&   HOME      "/home/httpd"
\&   HOST      "webdev"
\&   ...
\&   SHELL     "/bin/tcsh"
\&   TERM      "xterm"
.Ve
.PP
The power in this is that the table can be generated and previewed in
any HTML editor before the data is rendered so that changes to the table can be made completely
independent of the Perl coding and data rendering process.
.SS "Template Where Art Thou"
.IX Subsection "Template Where Art Thou"
Templates are expected by default to be in either the current working directory '.' or './templates'.
If the requested template cannot be found in the current directory then it will look in a
templates sub-directory.  This search path can be modified or appended to by using the 'inc_dir_lst' parameter
and the \fBset_defaults()\fR class method.
.SS "Default Parameters"
.IX Subsection "Default Parameters"
.Vb 2
\& * inc_dir_lst       \- A reference to a list of directories where templates reside.  The list
\& is searched recursively until the a template is found.  Default [ \*(Aq.\*(Aq, \*(Aq./templates\*(Aq ]
\&
\& * cmnt_verbose      \- A flag signalling the template processor to embed the location or source
\& of the underlying templates.  Default 1
\&
\& * cmnt_prefix_char  \- The prefix comment character used if cmnt_verbose flag is set.
\& Default \*(Aq<!\-\-\*(Aq
\&
\& * cmnt_postfix_char \- The postfix comment character used if cmnt_verbose flag is set
\& Default  \*(Aq\-\->\*(Aq
\&
\& * func_prefix       \- The prefix added to an embedded function in a temlate.  A prefix is
\& used to prevent a template from running any user or native function (such as unlink(\*(Aq*\*(Aq)).
\& Default \*(Aq_\*(Aq
\&
\& * func_package      \- The default package where embedded function are called.  This allows
\& an application to restrict all template triggered functions to a specific package. Default
\& "" which translates to the main package.
.Ve
.PP
The default parameters can be retrieved and set using the \fBclass\fR methods
.PP
.Vb 1
\& %config_hsh = TemplateRex\->get_defaults();
\&
\& TemplateRex\->set_defaults(%config_hsh);
.Ve
.PP
The set_defaults class method sets the defaults for all subsequent TemplateRex instances for a session.
Also, the set_defaults methods merges with the existing defaults so that you can change one default without
overwriting the other defaults.
.PP
.Vb 1
\&  $hsh{\*(Aqfunc_prefix\*(Aq} = "my_callbacks_";
\&
\&  TemplateRex\->set_defaults(%hsh);
.Ve
.PP
Will only set the 'func_prefix' parameter leaving the others as they were.  The defaults can also be
set at object creation.  See METHOD below for more infomation.
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
synopsis: \fR\f(CB$trex_obj\fR\fB = new( 'file'=>"my_template.html", \fR\f(CB%config\fR\fB )\fR
.PP
The input to the \fBnew()\fR method requires a hash with at least a 'file' or 'string' parameter defined.  If
\&'file' is provided then the contructor will search the include path for the template and then read and preprocess the
template.  If 'string' is provided then the contructor will preprocess the string template.
.SS render_sec
.IX Subsection "render_sec"
synopsis: \fR\f(CB$str\fR\fB = \fR\f(CB$trex_obj\fR\fB\->render_sec( 'section_name', \e%data_hsh )\fR
.PP
The \fBrender_sec()\fR will render the given 'section_name' using the provided \f(CW%data_hsh\fR for replacement values.
Note: The data hash must be passed down as a reference.  The \fBrender_sec()\fR function will maintain a buffer
that is appended to on each subsequent call.  This section buffer will automatically be rendered upon a call
to \fBrender()\fR.
.PP
If the section is nested (i.e.) within the delimiters of another section then the parent buffer will be
appended to when that section is rendered and child buffer will be reset.
.PP
If this sounds confusing than see the example provided in the description
above.
.PP
Also the rendered section is return on a successful \fBrender_sec()\fR call.
.SS render
.IX Subsection "render"
synopsis: \fR\f(CB$str\fR\fB = \fR\f(CB$trex_obj\fR\fB\->render( \e%data_hsh, 'file_out_spec' )\fR
.PP
This renders the entire template.  If the second arguement is provided than a file will be written, if not
than output will be to standard out (or to the client in a cgi environment).  Also if desired the
output will be returned.
.SS render_this
.IX Subsection "render_this"
synopsis: \fR\f(CB$str\fR\fB = render_this( 'my_template', 'file_out_spec' )\fR
.PP
This is a function-oriented call that renders the entire template in one fell swoop.  As in the case
with the \fBrender()\fR OO method this function outputs to a file if provided or to standard out if
no file_out_spec is provided. If you do not need sectional processing then this is the only function
call you.
.PP
Also the rendered section is return on a successful \fBrender_sec()\fR call.
.SH AUTHOR
.IX Header "AUTHOR"
Steve Troxel       troxelso@nswccd.navy.mil
.SH BUGS
.IX Header "BUGS"
None known. Make reports to troxelso@nswccd.navy.mil
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.SH COPYRIGHT
.IX Header "COPYRIGHT"
2002/2003 Steve Troxel