local-lib5/man/man3/Template::Plugin::Cycle.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Template::Plugin::Cycle 3"
 127 .TH Template::Plugin::Cycle 3 "2008-06-19" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Template::Plugin::Cycle \- Cyclically insert into a Template from a sequence of values
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&  [% USE cycle(\*(Aqrow\*(Aq, \*(Aqaltrow\*(Aq) %]
 138 \&
 139 \&  <table border="1">
 140 \&    <tr class="[% class %]">
 141 \&      <td>First row</td>
 142 \&    </tr>
 143 \&    <tr class="[% class %]">
 144 \&      <td>Second row</td>
 145 \&    </tr>
 146 \&    <tr class="[% class %]">
 147 \&      <td>Third row</td>
 148 \&    </tr>
 149 \&  </table>
 150 \&
 151 \&
 152 \&
 153 \&
 154 \&
 155 \&  ###################################################################
 156 \&  # Alternatively, you might want to make it available to all templates
 157 \&  # throughout an entire application.
 158 \&
 159 \&  use Template::Plugin::Cycle;
 160 \&
 161 \&  # Create a Cycle object and set some values
 162 \&  my $Cycle = Template::Plugin::Cycle\->new;
 163 \&  $Cycle\->init(\*(Aqnormalrow\*(Aq, \*(Aqalternaterow\*(Aq);
 164 \&
 165 \&  # Bind the Cycle object into the Template
 166 \&  $Template\->process( \*(Aqtablepage.html\*(Aq, class => $Cycle );
 167 \&
 168 \&
 169 \&
 170 \&
 171 \&
 172 \&  #######################################################
 173 \&  # Later that night in a Template
 174 \&
 175 \&  <table border="1">
 176 \&    <tr class="[% class %]">
 177 \&      <td>First row</td>
 178 \&    </tr>
 179 \&    <tr class="[% class %]">
 180 \&      <td>Second row</td>
 181 \&    </tr>
 182 \&    <tr class="[% class %]">
 183 \&      <td>Third row</td>
 184 \&    </tr>
 185 \&  </table>
 186 \&
 187 \&  [% class.reset %]
 188 \&  <table border="1">
 189 \&    <tr class="[% class %]">
 190 \&      <td>Another first row</td>
 191 \&    </tr>
 192 \&  </table>
 193 \&
 194 \&
 195 \&
 196 \&
 197 \&
 198 \&  #######################################################
 199 \&  # Which of course produces
 200 \&
 201 \&  <table border="1">
 202 \&    <tr class="normalrow">
 203 \&      <td>First row</td>
 204 \&    </tr>
 205 \&    <tr class="alternaterow">
 206 \&      <td>Second row</td>
 207 \&    </tr>
 208 \&    <tr class="normalrow">
 209 \&      <td>Third row</td>
 210 \&    </tr>
 211 \&  </table>
 212 \&
 213 \&  <table border="1">
 214 \&    <tr class="normalrow">
 215 \&      <td>Another first row</td>
 216 \&    </tr>
 217 \&  </table>
 218 .Ve
 219 .SH "DESCRIPTION"
 220 .IX Header "DESCRIPTION"
 221 Sometimes, apparently almost exclusively when doing alternating table row
 222 backgrounds, you need to print an alternating, cycling, set of values
 223 into a template.
 224 .PP
 225 Template::Plugin::Cycle is a small, simple, and hopefully \s-1DWIM\s0 solution to
 226 these sorts of tasks.
 227 .PP
 228 It can be used either as a normal Template::Plugin, or can be created
 229 directly and passed in as a template argument, so that you can set up
 230 situations where it is implicitly available in every page.
 231 .SH "METHODS"
 232 .IX Header "METHODS"
 233 .ie n .SS "new [ $Context ] [, @list ]"
 234 .el .SS "new [ \f(CW$Context\fP ] [, \f(CW@list\fP ]"
 235 .IX Subsection "new [ $Context ] [, @list ]"
 236 The \f(CW\*(C`new\*(C'\fR constructor creates and returns a new \f(CW\*(C`Template::Plugin::Cycle\*(C'\fR
 237 object. It can be optionally passed an initial set of values to cycle
 238 through.
 239 .PP
 240 When called from within a Template, the new constructor will be passed the
 241 current Template::Context as the first argument. This will be ignored.
 242 .PP
 243 By doing this, you can use it both directly, \s-1AND\s0 from inside a Template.
 244 .ie n .SS "init @list"
 245 .el .SS "init \f(CW@list\fP"
 246 .IX Subsection "init @list"
 247 If you need to set the values for a new empty object, of change the values
 248 to cycle through for an existing object, they can be passed to the \f(CW\*(C`init\*(C'\fR
 249 method.
 250 .PP
 251 The method always returns the \f(CW\*(Aq\*(Aq\fR null string, to avoid inserting
 252 anything into the template.
 253 .SS "elements"
 254 .IX Subsection "elements"
 255 The \f(CW\*(C`elements\*(C'\fR method returns the number of items currently set for the
 256 \&\f(CW\*(C`Template::Plugin::Cycle\*(C'\fR object.
 257 .SS "list"
 258 .IX Subsection "list"
 259 The \f(CW\*(C`list\*(C'\fR method returns the current list of values for the
 260 \&\f(CW\*(C`Template::Plugin::Cycle\*(C'\fR object.
 261 .PP
 262 This is also the prefered method for getting access to a value at a
 263 particular position within the list of items being cycled to.
 264 .PP
 265 .Vb 4
 266 \&  [%# Access a variety of things from the list %]
 267 \&  The first item in the Cycle object is [% cycle.list.first %].
 268 \&  The second item in the Cycle object is [% cycle.list.[1] %].
 269 \&  The last item in the Cycle object is [% cycle.list.last %].
 270 .Ve
 271 .SS "next"
 272 .IX Subsection "next"
 273 The \f(CW\*(C`next\*(C'\fR method returns the next value from the Cycle. If the end of
 274 the list of valuese is reached, it will \*(L"cycle\*(R" back the first object again.
 275 .PP
 276 This method is also the one called when the object is stringified. That is,
 277 when it appears on its own in a template. Thus, you can do something like
 278 the following.
 279 .PP
 280 .Vb 11
 281 \&  <!\-\- An example of alternate row classes in a table\-\->
 282 \&  <table border="1">
 283 \&    <!\-\- Explicitly access the next class in the cycle \-\->
 284 \&    <tr class="[% rowclass.next %]">
 285 \&      <td>First row</td>
 286 \&    </tr>
 287 \&    <!\-\- This has the same effect \-\->
 288 \&    <tr class="[% rowclass %]">
 289 \&      <td>Second row</td>
 290 \&    </tr>
 291 \&  </table>
 292 .Ve
 293 .SS "value"
 294 .IX Subsection "value"
 295 The \f(CW\*(C`value\*(C'\fR method is an analogy for the \f(CW\*(C`next\*(C'\fR method.
 296 .SS "reset"
 297 .IX Subsection "reset"
 298 If a single \f(CW\*(C`Template::Plugin::Cycle\*(C'\fR object is to be used it multiple
 299 places within a template, and it is important that the same value be first
 300 every time, then the \f(CW\*(C`reset\*(C'\fR method can be used.
 301 .PP
 302 The \f(CW\*(C`reset\*(C'\fR method resets the Cycle, so that the next value returned will
 303 be the first value in the Cycle object.
 304 .SH "SUPPORT"
 305 .IX Header "SUPPORT"
 306 Bugs should be submitted via the \s-1CPAN\s0 bug tracker, located at
 307 .PP
 308 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template\-Plugin\-Cycle>
 309 .PP
 310 For other issues, or commercial enhancement or support, contact the author..
 311 .SH "AUTHOR"
 312 .IX Header "AUTHOR"
 313 Adam Kennedy <adamk@cpan.org>
 314 .PP
 315 Thank you to Phase N Australia (<http://phase\-n.com/>) for permitting
 316 the open sourcing and release of this distribution as a spin-off from a
 317 commercial project.
 318 .SH "COPYRIGHT"
 319 .IX Header "COPYRIGHT"
 320 Copyright 2004 \- 2008 Adam Kennedy.
 321 .PP
 322 This program is free software; you can redistribute
 323 it and/or modify it under the same terms as Perl itself.
 324 .PP
 325 The full text of the license can be found in the
 326 \&\s-1LICENSE\s0 file included with this module.