.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Template::Plugin::Cycle 3pm"
.TH Template::Plugin::Cycle 3pm "2008-06-19" "perl v5.12.4" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Template::Plugin::Cycle \- Cyclically insert into a Template from a sequence of values
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  [% USE cycle(\*(Aqrow\*(Aq, \*(Aqaltrow\*(Aq) %]
\&  
\&  <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(\*(Aqnormalrow\*(Aq, \*(Aqalternaterow\*(Aq);
\&  
\&  # Bind the Cycle object into the Template
\&  $Template\->process( \*(Aqtablepage.html\*(Aq, 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>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Sometimes, apparently almost exclusively when doing alternating table row
backgrounds, you need to print an alternating, cycling, set of values
into a template.
.PP
Template::Plugin::Cycle is a small, simple, and hopefully \s-1DWIM\s0 solution to
these sorts of tasks.
.PP
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.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "new [ $Context ] [, @list ]"
.el .SS "new [ \f(CW$Context\fP ] [, \f(CW@list\fP ]"
.IX Subsection "new [ $Context ] [, @list ]"
The \f(CW\*(C`new\*(C'\fR constructor creates and returns a new \f(CW\*(C`Template::Plugin::Cycle\*(C'\fR
object. It can be optionally passed an initial set of values to cycle
through.
.PP
When called from within a Template, the new constructor will be passed the
current Template::Context as the first argument. This will be ignored.
.PP
By doing this, you can use it both directly, \s-1AND\s0 from inside a Template.
.ie n .SS "init @list"
.el .SS "init \f(CW@list\fP"
.IX Subsection "init @list"
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 \f(CW\*(C`init\*(C'\fR
method.
.PP
The method always returns the \f(CW\*(Aq\*(Aq\fR null string, to avoid inserting
anything into the template.
.SS "elements"
.IX Subsection "elements"
The \f(CW\*(C`elements\*(C'\fR method returns the number of items currently set for the
\&\f(CW\*(C`Template::Plugin::Cycle\*(C'\fR object.
.SS "list"
.IX Subsection "list"
The \f(CW\*(C`list\*(C'\fR method returns the current list of values for the
\&\f(CW\*(C`Template::Plugin::Cycle\*(C'\fR object.
.PP
This is also the prefered method for getting access to a value at a
particular position within the list of items being cycled to.
.PP
.Vb 4
\&  [%# 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 %].
.Ve
.SS "next"
.IX Subsection "next"
The \f(CW\*(C`next\*(C'\fR 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.
.PP
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.
.PP
.Vb 11
\&  <!\-\- 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>
.Ve
.SS "value"
.IX Subsection "value"
The \f(CW\*(C`value\*(C'\fR method is an analogy for the \f(CW\*(C`next\*(C'\fR method.
.SS "reset"
.IX Subsection "reset"
If a single \f(CW\*(C`Template::Plugin::Cycle\*(C'\fR 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 \f(CW\*(C`reset\*(C'\fR method can be used.
.PP
The \f(CW\*(C`reset\*(C'\fR method resets the Cycle, so that the next value returned will
be the first value in the Cycle object.
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs should be submitted via the \s-1CPAN\s0 bug tracker, located at
.PP
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template\-Plugin\-Cycle <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Plugin-Cycle>
.PP
For other issues, or commercial enhancement or support, contact the author..
.SH "AUTHOR"
.IX Header "AUTHOR"
Adam Kennedy <adamk@cpan.org>
.PP
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.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004 \- 2008 Adam Kennedy.
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.