Templa...::Cycle(3pm)

🦋 Template::Plugin::Cycle — the Template::Plugin::Cycle page, section 3pm, straight out of the User Contributed Perl Documentation 💖

okay bestie, sit down, we're talking about cyclically inserting values into a Template from a sequence. it's giving alternating table rows, it's giving iconic, it's giving you're welcome. ✨

---

✨ NAME ✨

Template::Plugin::Cycle — cyclically insert into a Template from a sequence of values. that's it, that's the whole job, and it does it flawlessly. no cap. 💅

---

🌸 SYNOPSIS 🌸

[% 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>

---

💜 DESCRIPTION 💜

so sometimes — and apparently it's almost exclusively when you're doing alternating table row backgrounds, which is honestly so real — you need to print an alternating, cycling set of values into a template. like, striped rows. you know the vibe. 🦓

Template::Plugin::Cycle is a small, simple, and hopefully DWIM solution to these sorts of tasks. she's tiny, she's polite, she just works. 🫶

you can use her either as a normal Template::Plugin, OR you can create her directly and pass her in as a template argument — which means you can set up situations where she's implicitly available in every page. main character energy, truly. 👑

---

🎀 METHODS 🎀

🌟 new [ $Context ] [, @list ]

the new constructor creates and returns a brand new Template::Plugin::Cycle object. it can optionally be handed an initial set of values to cycle through. slay.

when it's called from within a Template, the new constructor gets passed the current Template::Context as the first argument. that argument gets ignored. 🙈

and by doing this lil trick, you can use it both directly AND from inside a Template. best of both worlds, periodt. 💅

🌟 init @list

if you need to set the values for a new empty object, or change the values to cycle through for an object that already exists, you just pass them to the init method. easy.

this method always returns the '' null string — deliberately, so it doesn't insert anything into the template. it's a silent queen. 🤫

🌟 elements

the elements method returns the number of items currently set for the Template::Plugin::Cycle object.

🌟 list

the list method returns the current list of values for the Template::Plugin::Cycle 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. (yes, we're spelling it exactly like the original, don't come for me 💀)

[%# 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 %].

🌟 next

the next method returns the next value from the Cycle. and if the end of the list of values is reached, she will "cycle" right back around to the first object again. iconic behaviour, honestly. 🔁

this method is also the one that gets called when the object is stringified — i.e. when it appears all by itself in a template. so you can do something like this:

<!-- 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>

🌟 value

the value method is an analogy for the next method. same energy, different name. ✨

🌟 reset

if a single Template::Plugin::Cycle object is going to be used in multiple places within a template, and it's important that the same value comes first every time, then the reset method is your girl.

the reset method resets the Cycle so that the next value returned will be the first value in the Cycle object. fresh start, clean slate, new semester energy. 🧚

---

🫶 SUPPORT 🫶

bugs should be submitted via the CPAN bug tracker, located at:

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Plugin-Cycle>

for other issues, or commercial enhancement or support, contact the author. 📬

---

👑 AUTHOR 👑

Adam Kennedy <adamk@cpan.org>

thank you to Phase N Australia (<http://phase-n.com/>) for permitting the open sourcing and release of this distribution as a spin-off from a commercial project. absolute legends, fr fr. 🙏

---

💖 COPYRIGHT 💖

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 LICENSE file included with this module.

---

lowkey important reminder bestie: this page is documented for perl v5.32.0, dated 2021-01-07, and it's the Templa...::Cycle(3pm) page from the User Contributed Perl Documentation. that's the whole thing, you ate it up, no notes. 💅✨🎀