Cyclically insert into a template from a sequence of values
[% USE cycle('row', 'altrow') %]
<table border="1">
<tr class="[% class %]">
<td>First row</td>
</tr>
<tr class="[% class %]">
<td>Second row</td>
</tr>
<tr class="[% class %]">
<td>Third row</td>
</tr>
</table>
###################################################################
# Alternatively, you might want to make it available to all templates
# throughout an entire application.
use Template::Plugin::Cycle;
# Create a Cycle object and set some values
my $Cycle = Template::Plugin::Cycle->new;
$Cycle->init('normalrow', 'alternaterow');
# Bind the Cycle object into the Template
$Template->process( 'tablepage.html', class => $Cycle );
#######################################################
# Later that night in a Template
<table border="1">
<tr class="[% class %]">
<td>First row</td>
</tr>
<tr class="[% class %]">
<td>Second row</td>
</tr>
<tr class="[% class %]">
<td>Third row</td>
</tr>
</table>
[% class.reset %]
<table border="1">
<tr class="[% class %]">
<td>Another first row</td>
</tr>
</table>
#######################################################
# Which of course produces
<table border="1">
<tr class="normalrow">
<td>First row</td>
</tr>
<tr class="alternaterow">
<td>Second row</td>
</tr>
<tr class="normalrow">
<td>Third row</td>
</tr>
</table>
<table border="1">
<tr class="normalrow">
<td>Another first row</td>
</tr>
</table>
Sometimes, apparently almost exclusively when doing alternating table row backgrounds, you need to print an alternating, cycling, set of values into a template.
Template::Plugin::Cycle is a small, simple, and hopefully \s-1DWIM\s0 solution to these sorts of tasks.
It can be used either as a normal Template::Plugin, or can be created directly and passed in as a template argument, so that you can set up situations where it is implicitly available in every page.
The \*(C`new\*(C' constructor creates and returns a new \*(C`Template::Plugin::Cycle\*(C' object. It can be optionally passed an initial set of values to cycle through.
When called from within a Template, the new constructor will be passed the current Template::Context as the first argument. This will be ignored.
By doing this, you can use it both directly, \s-1AND\s0 from inside a Template. If you need to set the values for a new empty object, of change the values to cycle through for an existing object, they can be passed to the \*(C`init\*(C' method.
The method always returns the '' null string, to avoid inserting anything into the template.
The \*(C`elements\*(C' method returns the number of items currently set for the \*(C`Template::Plugin::Cycle\*(C' object.
The \*(C`list\*(C' method returns the current list of values for the \*(C`Template::Plugin::Cycle\*(C' object.
This is also the prefered method for getting access to a value at a particular position within the list of items being cycled to.
[%# Access a variety of things from the list %] The first item in the Cycle object is [% cycle.list.first %]. The second item in the Cycle object is [% cycle.list.[1] %]. The last item in the Cycle object is [% cycle.list.last %].
The \*(C`next\*(C' method returns the next value from the Cycle. If the end of the list of valuese is reached, it will \*(L"cycle\*(R" back the first object again.
This method is also the one called when the object is stringified. That is, when it appears on its own in a template. Thus, you can do something like the following.
<!-- An example of alternate row classes in a table--> <table border="1"> <!-- Explicitly access the next class in the cycle --> <tr class="[% rowclass.next %]"> <td>First row</td> </tr> <!-- This has the same effect --> <tr class="[% rowclass %]"> <td>Second row</td> </tr> </table>
The \*(C`value\*(C' method is an analogy for the \*(C`next\*(C' method.
If a single \*(C`Template::Plugin::Cycle\*(C' object is to be used it multiple places within a template, and it is important that the same value be first every time, then the \*(C`reset\*(C' method can be used.
The \*(C`reset\*(C' method resets the Cycle, so that the next value returned will be the first value in the Cycle object.
Bugs should be submitted via the \s-1CPAN\s0 bug tracker, located at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Plugin-Cycle <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Plugin-Cycle>
For other issues, or commercial enhancement or support, contact the author..
Adam Kennedy <[email protected]>
Thank you to Phase N Australia (http://phase-n.com/ <http://phase-n.com/>) for permitting the open sourcing and release of this distribution as a spin-off from a commercial project.
Copyright 2004 - 2008 Adam Kennedy.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the \s-1LICENSE\s0 file included with this module.