1Template::Plugin::CycleU(s3e)r Contributed Perl DocumentaTteimopnlate::Plugin::Cycle(3)
2
6 Template::Plugin::Cycle - Cyclically insert into a Template from a
7 sequence of values
8
10 [% USE cycle('row', 'altrow') %]
11 <table border="1">
13 <tr class="[% class %]">
14 <td>First row</td>
15 </tr>
16 <tr class="[% class %]">
17 <td>Second row</td>
18 </tr>
19 <tr class="[% class %]">
20 <td>Third row</td>
21 </tr>
22 </table>
23 ###################################################################
29 # Alternatively, you might want to make it available to all templates
30 # throughout an entire application.
31 use Template::Plugin::Cycle;
33 # Create a Cycle object and set some values
35 my $Cycle = Template::Plugin::Cycle->new;
36 $Cycle->init('normalrow', 'alternaterow');
37 # Bind the Cycle object into the Template
39 $Template->process( 'tablepage.html', class => $Cycle );
40 #######################################################
46 # Later that night in a Template
47 <table border="1">
49 <tr class="[% class %]">
50 <td>First row</td>
51 </tr>
52 <tr class="[% class %]">
53 <td>Second row</td>
54 </tr>
55 <tr class="[% class %]">
56 <td>Third row</td>
57 </tr>
58 </table>
59 [% class.reset %]
61 <table border="1">
62 <tr class="[% class %]">
63 <td>Another first row</td>
64 </tr>
65 </table>
66 #######################################################
72 # Which of course produces
73 <table border="1">
75 <tr class="normalrow">
76 <td>First row</td>
77 </tr>
78 <tr class="alternaterow">
79 <td>Second row</td>
80 </tr>
81 <tr class="normalrow">
82 <td>Third row</td>
83 </tr>
84 </table>
85 <table border="1">
87 <tr class="normalrow">
88 <td>Another first row</td>
89 </tr>
90 </table>
91
93 Sometimes, apparently almost exclusively when doing alternating table
94 row backgrounds, you need to print an alternating, cycling, set of
95 values into a template.
96 Template::Plugin::Cycle is a small, simple, and hopefully DWIM solution
98 to these sorts of tasks.
99 It can be used either as a normal Template::Plugin, or can be created
101 directly and passed in as a template argument, so that you can set up
102 situations where it is implicitly available in every page.
103
105 new [ $Context ] [, @list ]
106 The "new" constructor creates and returns a new
107 "Template::Plugin::Cycle" object. It can be optionally passed an
108 initial set of values to cycle through.
109 When called from within a Template, the new constructor will be passed
111 the current Template::Context as the first argument. This will be
112 ignored.
113 By doing this, you can use it both directly, AND from inside a
115 Template.
116 init @list
118 If you need to set the values for a new empty object, of change the
119 values to cycle through for an existing object, they can be passed to
120 the "init" method.
121 The method always returns the '' null string, to avoid inserting
123 anything into the template.
124 elements
126 The "elements" method returns the number of items currently set for the
127 "Template::Plugin::Cycle" object.
128 list
130 The "list" method returns the current list of values for the
131 "Template::Plugin::Cycle" object.
132 This is also the prefered method for getting access to a value at a
134 particular position within the list of items being cycled to.
135 [%# Access a variety of things from the list %]
137 The first item in the Cycle object is [% cycle.list.first %].
138 The second item in the Cycle object is [% cycle.list.[1] %].
139 The last item in the Cycle object is [% cycle.list.last %].
140 next
142 The "next" method returns the next value from the Cycle. If the end of
143 the list of valuese is reached, it will "cycle" back the first object
144 again.
145 This method is also the one called when the object is stringified. That
147 is, when it appears on its own in a template. Thus, you can do
148 something like the following.
149 <!-- An example of alternate row classes in a table-->
151 <table border="1">
152 <!-- Explicitly access the next class in the cycle -->
153 <tr class="[% rowclass.next %]">
154 <td>First row</td>
155 </tr>
156 <!-- This has the same effect -->
157 <tr class="[% rowclass %]">
158 <td>Second row</td>
159 </tr>
160 </table>
161 value
163 The "value" method is an analogy for the "next" method.
164 reset
166 If a single "Template::Plugin::Cycle" object is to be used it multiple
167 places within a template, and it is important that the same value be
168 first every time, then the "reset" method can be used.
169 The "reset" method resets the Cycle, so that the next value returned
171 will be the first value in the Cycle object.
172
174 Bugs should be submitted via the CPAN bug tracker, located at
175 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Plugin-Cycle>
177 For other issues, or commercial enhancement or support, contact the
179 author..
180
182 Adam Kennedy <adamk@cpan.org>
183 Thank you to Phase N Australia (<http://phase-n.com/>) for permitting
185 the open sourcing and release of this distribution as a spin-off from a
186 commercial project.
187
189 Copyright 2004 - 2008 Adam Kennedy.
190 This program is free software; you can redistribute it and/or modify it
192 under the same terms as Perl itself.
193 The full text of the license can be found in the LICENSE file included
195 with this module.
196perl v5.38.0 2023-07-21 Template::Plugin::Cycle(3)