• DESCRIPTION</PRE>

DESCRIPTION</PRE> <P>This library is another template module for the generation of HTML pages. Why ?. Well primarily i wanted a module: light, that keeps mod_perl power and flow control like HTML::Template, good interaction with external contents administrators, have the chance of using naturally the print statement for generating web content, but, for some situations have the chance of directly replace keywords in the template with values. In some way this module centralizes the feature of a hash with values for replacing that you find in HTML::Template and the XMLSubsMatch feature of Apache::ASP.</P> <P>This module keeps the basic mod_perl flow, and permits the replacing with dynamic content using two forms of marking. Is very well suited for working in parallel with the designers team, living each group advance on its own.</P> <P>HTML::Myasp export the send_page function by default, you can attach the dynamic content using:</P> <UL> <LI> A callback style for special tags delimiting zones. <P></P> <LI> Direct replacing of keywords by values. <P></P></UL> <P>In order to improve performance it uses a global pages CACHE hash, avoiding parsing files unless modified.</P> <P> <HR> <H1><A NAME=``recommended''>RECOMMENDED</A></H1> <PRE> The recomended way to use this system is Design the page with a graphic tool and when designing consider:</PRE> <UL> <LI> Try to keep the maximum of design in the Template. Create the page as it will be in production with dummy data when appropriate, <P></P> <LI> Delimit with the special tags the zones of HTML you now you're going to produce dynamically. All the HTML in the zone is considered dummy, but can be used if the application wants. <P></P> <LI> Use keywords replacement where you will provide an atomic value, like user name or date. <P></P></UL> <P> <HR> <H1><A NAME=``parameters''>PARAMETER/A</H1> <P>The send_page function receives three parameters: filename, tags_hash, keywords_replace_hash</P> <P> <H2><A NAME=``filename''>filename</A></H2> <P>This is the HTML file that acts as a template for the page that will be produced. The physical file is open and taken relative to the $r-&gt;document_root call (the Document Root). When not running under mod_perl the file given as parameter is open as it comes.</P> <P> <H2><A NAME=``tags_hash''>tags_hash</A></H2> <P>The keys of this hash are the tags we put in the HTML file, the values correspond to a reference to subroutines that, for each key, will generate the content for everything between the initial and ending tag. In our Example:</P> <P>The TagPrefix Parameter of httpd.conf is xx. If not set, is assumed the value myasp. If the environment variable TagPrefix exists it's value superseded all other settings.</P> <P>In the HTML file we put the mark:</P> <PRE> &lt;xx:users&gt; &lt;tr&gt;&lt;td&gt;dummy id 1&lt;/td&gt;&lt;td&gt;dummy name 1&lt;/td&gt;&lt;/tr&gt; &lt;tr&gt;&lt;td&gt;dummy id 2&lt;/td&gt;&lt;td&gt;dummy name 2&lt;/td&gt;&lt;/tr&gt; &lt;/xx:users&gt; </PRE> <PRE>

 In the call to send_page:
 send_page('myfile.html', 
 {
        -users => \&list_users,
        -other_data => sub { print "this is the other data";  ... }
 }, 
 {
        __user__ => $sesion->current_user,
        __date__ => localtime(time),
 });</PRE>
<P>The first key of the second parameter (the tags_hash) is ``-users '' and it points to a reference of a subroutine.</P>
<P>All this means this:</P>
<P>``All the content found in the template between the marks &lt;xx:users&gt; and &lt;/xx:users&gt;, the marks inclusive, will be replaced with whatever the subroutine ''list_users`` prints, using the standard print command''.</P>
<P>The second key ``-other_data'', is shown just to illustrate the declaration of an inline anonymous subroutine.</P>
<P>As in the module Apache::ASP, the subroutines will receive as the first parameter a hash reference with the attributes of the tag, and as a second argument the body of the tag. This may be useful in some cases when you want to use a micro template zone, for example, to predesign the rows in a table.</P>
<P>In the case of tables, is suggested to leave the table declaration in the template as in the example, and leave the rows marked, in order to be generate dynamically.</P>
<P>
<H2><A NAME="keywords_replace_hash">keywords_replace_hash</A></H2>
<P>This parameter (optional), contains the keywords that will be replaced with the specified content. Note that no printing is allowed here, the value asigned to the keyword will be put in the resulting page. Each keyword will be replace as many times as it appear in the document.</P>
<P>No prefixing or sufixing is enforced here, the developer (or designer) can chose the keywords to replace at will.</P>
<P>This form is very well suited for the dynamic content associated with atomic values. As shown in the example:</P>
<P>The HTML file:<;/P>
<PRE>
 &lt;html&gt;
 ....
 __user__
 __date__
</PRE>
<PRE>

 With the keywords_replace_hash
 ...
 {
        __user__ => $sesion->current_user,
        __date__ => localtime(time),
 });</PRE>
<P>Will render an HTML file with the result of calling $sesion-&gt;current_user instead of the string __user__. __date__ will be replaced with the result of calling localtime(time).</P>
<P>If you allways name the marks with initial and ending double underline __, like in the example, here is the code of a shell script that receives a file as parameter and generate a skeleton keywords hash:</P>
<P>#!/bin/sh</P>
<P>perl -ne 'print ``$1\t=&gt;\ttextfield(-name=&gt;\''$2\``),\n'' while  /\b(__([\w-]+)__\b)/g' $1</P>
<P>
<HR>
<H1><A NAME="global processing">Global Processing</A></H1>
<P>In the web sites, there are sections that must be present in many pages (if not in all the pages). The system provides two functions that access associative arrays (hashs) that will be allways processed as if they were present in the call to send_page. For example, if you want to allways translate the __user__ mark with the current user and supossing there is some $sesion-&gt;current_user method that return this value, you cant at the begining of the request in some handler call:</P>
<P>HTML::Myasp::add_replace_entry(_user__ =&gt; $sesion-&gt;current_user);</P>
<P>And if you have some sections delimited to replace, you can call:</P>
<P>HTML::Myasp::add_sub_entry(``-section'' =&gt; sub { my ($attr, $body) = @_; my $s = new OV::Section($attr-&gt;{id}); $s-&gt;home_page_news });</P>
<P>The last call, is an example where there are multiple section marks in the html file, in this case, an electronic newspaper, for example:</P>
<P>&lt;myasp:section id=foo&gt;&lt;p&gt;This is dummy data not used for now. Here must be the top foo.&lt;/p&gt;&lt;/myasp:section&gt;
&lt;myasp:section id=bar&gt;&lt;p&gt;This is dummy data not used for now. Here must be the bar section.&lt;/p&gt;&lt;/myasp:section&gt;</P>
<P>The id attribute is used to pass a parameter to  the call to the funcion that will produce the content.</P>
<P>
<HR>
<H1><A NAME="debugging">Debugging</A></H1>
<P>At this time, there is a Package variable DEBUG that you can set to see aditional information in standard error (traditionally the file error_log in apache).</P>
<P>$HTML::Myasp::DEBUG=1;</P>
<P>There is only one level of debugging, and shows too much information.</P>
<P>
<HR>
<H1><A NAME="todo">TODO</A></H1>
<P>Many things. It uses a rude regex based parser i expect to polish it with something better in the future. Do a finer debugging control.</P>
<P>
<HR>
<H1><A NAME="export">EXPORT</A></H1>
<P>send_page</P>
<P>
<HR>
<H1><A NAME="author">AUTHOR</A></H1>
<P>Hans Poo, <A HREF="mailto:hans@opensource.cl";>hans@opensource.cl</A></P>
<P>
<HR>
<H1><A NAME="see also">SEE ALSO</A></H1>
<P>perl(1). Apache::ASP (XMLSubsMatch) HTML::Template</P>
<TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
<TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
<FONT SIZE=+1><STRONG><P CLASS=block>&nbsp;HTML::Myasp - Generate HTML pages based on Templates. JATP (Just Another
Template Parser).</P></STRONG></FONT>
</TD></TR>
</TABLE>

</BODY>

</HTML>