view release on metacpan or  search on metacpan

README.htm  view on Meta::CPAN

<P>This specifies that the loop should execute once for each element in the array-reference 
passed to "index-list".  Each value of index-list will become the subscript to use for 
argument1 and argument2 in it's respective iteration.</P>

<P>NOTE:  If argument1 is a hash-reference instead of an array-reference, then the 
keys used for argument1 will be based on the relative position within an imaginary 
array built on the fly as "sort(keys(%{$argument1))".  For example if the keys for 
argument1 (sorted) were "AA", "BB", "CC", and "DD"; and array referenced by index-list contained the values (in this order):  (1, 3, 2, 0), then the loop would iterate through the keys in the order of:  "BB", then "DD", then "CC", and finally "AA".  ...

<P>LoadHTML can also emulate Template::Toolkit's ability to reference subcomponents of 
a reference by name.  For example:</P>

<BR>&nbsp;&nbsp;&nbsp;&nbsp;my @v ;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;push (@v, {id => 100, name => 'Jack'});
<BR>&nbsp;&nbsp;&nbsp;&nbsp;push (@v, {id => 101, name => 'Jill'});
<BR>&nbsp;&nbsp;&nbsp;&nbsp;push (@v, {id => 102, name => 'Jerry'});
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&loadhtml('template.html', -hashref => \@v);
<BR>

<P>template.html contains:</P>

<br>&lt;table>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&lt;tr>&lt;td>ID&lt;/td>&lt;td>Name&lt;/td>&lt;/tr>
<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;!LOOP hashref, id, name>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;tr>&lt;td>&lt;!:id>&lt;/td>&lt;td>&lt;!:name>&lt;/td>&lt;/tr>
<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;!/LOOP>
<br>&lt;/table>
<br>

<P>This would produce:</P>

<br>&lt;table>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&lt;tr>&lt;td>ID&lt;/td>&lt;td>Name&lt;/td>&lt;/tr>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&lt;tr>&lt;td>100&lt;/td>&lt;td>Jack&lt;/td>&lt;/tr>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&lt;tr>&lt;td>101&lt;/td>&lt;td>Jill&lt;/td>&lt;/tr>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&lt;tr>&lt;td>102&lt;/td>&lt;td>Jerry&lt;/td>&lt;/tr>
<br>&lt;/table>
<br>

<P>NOTE:  "id" and "name" are parameters in the LOOP statement that are NOT DEFINED - 
(no argument is passed to them in the call to "loadhtml()"!  This results in the 
subcomponents of the hashrefs passed to "hashref" (from @v) being used!  This is 
similar to the way Template::Toolkit works and permits easier conversion of templates 
and scripts from that package.  Also NOTE:  a HASH could have been used in leau of "@v"!</P>

<P>There are four special variables that have meaning within a loop construct:</P>

<UL>
<LI>:#    Current increment value.  If no increment expression or index list is specified, the loop 
is driven by the 1st array or hash argument.  In that case, the increment value is the 
zero-based iteration of the loop.  This value is always numeric and represents the index 
subscript of the vectors for the current iteration.

<LI>:*    Always the current zero-based iteration of the loop (numeric).  Normally, this 
is the same as :#, but if an <B>increment expression</B> or <B>index list</B> is specified before the parameters, 
then :# is set to each element of the increment expression/index list, whereas :* is ALWAYS 0,1,...

<LI>:%    Current key value of the 1st (driving) hash (if the 1st argument is a hash-reference).  
Otherwise, this variable is empty (ie. if the loop is driven by an array).

<LI>:^    Always contains the number of iterations (one-based) that the loop will perform.
</UL>

<P>Naming and nesting IF and LOOP constructs.</P>

<P>IF and LOOP constructs can be nested with each other.&nbsp; If nested
within the same construct, however, they must be named (in order for the
parser to match up the proper closing tags).&nbsp; This allows for qualifying the 
special variables (:#, :*, etc.) to the desired loop.  To name an "IF" or "LOOP"
constuct, simply append an alphanumeric string to the keyword, for example:</P>

<P>&lt;!IF2>...&lt;!ELSE2>...&lt;!/IF2></P>

<P>&nbsp;&nbsp;&nbsp; -or-</P>

<P>&lt;!LOOP_OUTER>...&lt;!/LOOP_OUTER></P>

<P>The "IF" is named "2", and the "LOOP" is named "_OUTER".</P>

<P>Multi-loop Matrix example:</P>
<P>Consider the following code:</P>

<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;my $data = $dbh->selectall_arrayref('select name, address, phone from some_database.table');
<BR>&nbsp;&nbsp;&nbsp;&nbsp;...
<br>&nbsp;&nbsp;&nbsp;&nbsp;&loadhtml('rate_specials.html',
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-colHeaders => [qw(Name Address Phone)],
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-matrix => $data,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-names => '$matrix->[*][0]',   #THIS IS AN EXAMPLE OF A COLUMN &quot;Slice&quot;!
<br>&nbsp;&nbsp;&nbsp;&nbsp;);
</P>

<P>Now consider the following template code:</P>

<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&lt;table&gt;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;TR class="heading"&gt;&lt;TH&gt;Link&lt;/TH&gt;&lt;!LOOP_HEADERS colHeaders&gt;&lt;TH&gt;&lt;!:colHeaders:&gt;Field&nbsp;Header&lt;!:/colHeaders&gt;&lt;/TH&gt;&lt;!/LOOP_HEADERS&gt;&lt;/TR...
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;!LOOP_ROWS matrix, names&gt;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;!IF_ODDEVEN1 :#_ROWS % 2&gt;&lt;TR class="oddrow"&gt;&lt;!ELSE_ODDEVEN1&gt;&lt;TR class="evenrow"&gt;&lt;!/IF_ODDEVEN1&gt;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;TD align="center"&gt;&lt;A HREF="cgi-bin/someotherpgm.cgi?name=:{names}"&gt;&lt;!:names&gt;&lt;/A&gt;&lt;/td&gt;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;!LOOP_COLS matrix&gt;&lt;TD&gt;&lt;!:matrix:&gt;Field&nbsp;Value&lt;!:/matrix&gt;&lt;/TD&gt;&lt;!/LOOP_COLS&gt;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/TR&gt;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;!/LOOP_ROWS&gt;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&lt;/table&gt;
<BR>
</P>

<P>This illustrates how simple it is to combine LoadHTML with DBI (the single call to 
DBI::selectall_arrayref fetches all the data from a database query into a two-dimentional 
<b>row-major</B> array referenced by $data).  This HTML template could handle a variety 
of queries, since the number of columns (headers) is also driven by a loop.  The "ODDEVEN1" 
IF-statement is optional and simply allows the table rows to have alternating colors for readability.
Note the nested loops "_ROWS" (outer) and "_COLS" (inner), both are driven by the two-dimentional array-
referencing parameter "matrix".  This will produce a table showing a row for each record 
read by the query and each row will contain all three column values.</P>

<P>An extra, but 
unnecessary level of complexity was added to this example to illustrate another feature - 
the column "slice".  Note that the 1st column header is "Link", and the 1st column of 
each row is a URL link to "someotherpgm.cgi".  The reason for this example is to show access 
to the entire column of data represented by the field "names".  By specifying an