Template::Iterator
Author: Andy Wardley

TT2 Home Page

- Modules
- Template::*
- Iterator.pm

Click to view the menu. It's very nice. Click to hide the menu and go all widescreen!
Back

#### Template::Grammar

Parser state/rule tables for the TT grammar Up

#### Template::* Modules

Next

#### Template::Namespace::* Modules

# Template::Iterator

## Data iterator used by the FOREACH directive

# Contents

Top

# SYNOPSIS

Top

    my $iter = Template::Iterator->new(\@data, \%options);

# DESCRIPTION

Top

The `Template::Iterator` module defines a generic data iterator for use by the `FOREACH` directive.

It may be used as the base class for custom iterators.

# PUBLIC METHODS

Top

## new($data)

Top

Constructor method. A reference to a list of values is passed as the first parameter. Subsequent calls to get_first() and get_next() calls will return each element from the list.

    my $iter = Template::Iterator->new([ 'foo', 'bar', 'baz' ]);

The constructor will also accept a reference to a hash array and will expand it into a list in which each entry is a hash array containing a '`key`' and '`value`' item, sorted according to the hash keys.

    my $iter = Template::Iterator->new({
        foo => 'Foo Item',
        bar => 'Bar Item',
    });

This is equivalent to:

    my $iter = Template::Iterator->new([
        { key => 'bar', value => 'Bar Item' },
        { key => 'foo', value => 'Foo Item' },
    ]);

When passed a single item which is not an array reference, the constructor will automatically create a list containing that single item.

    my $iter = Template::Iterator->new('foo');

This is equivalent to:

    my $iter = Template::Iterator->new([ 'foo' ]);

Note that a single item which is an object based on a blessed ARRAY references will NOT be treated as an array and will be folded into a list containing that one object reference.

    my $list = bless [ 'foo', 'bar' ], 'MyListClass';
    my $iter = Template::Iterator->new($list);

equivalent to:

    my $iter = Template::Iterator->new([ $list ]);

If the object provides an `as_list()` method then the Template::Iterator constructor will call that method to return the list of data. For example:

    package MyListObject;

    sub new {
        my $class = shift;
        bless [ @_ ], $class;
    }

    package main;

    my $list = MyListObject->new('foo', 'bar');
    my $iter = Template::Iterator->new($list);

This is then functionally equivalent to:

    my $iter = Template::Iterator->new([ $list ]);

The iterator will return only one item, a reference to the `MyListObject` object, `$list`.

By adding an `as_list()` method to the `MyListObject` class, we can force the `Template::Iterator` constructor to treat the object as a list and use the data contained within.

    package MyListObject;

    ...

    sub as_list {
        my $self = shift;
        return $self;
    }

    package main;

    my $list = MyListObject->new('foo', 'bar');
    my $iter = Template::Iterator->new($list);

The iterator will now return the two items, '`foo`' and '`bar`', which the `MyObjectList` encapsulates.

## get_first()

Top

Returns a `($value, $error)` pair for the first item in the iterator set. The `$error` returned may be zero or undefined to indicate a valid datum was successfully returned. Returns an error of `STATUS_DONE` if the list is empty.

## get_next()

Top

Returns a `($value, $error)` pair for the next item in the iterator set. Returns an error of `STATUS_DONE` if all items in the list have been visited.

## get_all()

Top

Returns a `(\@values, $error)` pair for all remaining items in the iterator set. Returns an error of `STATUS_DONE` if all items in the list have been visited.

## size()

Top

Returns the size of the data set or undef if unknown.

## max()

Top

Returns the maximum index number (i.e. the index of the last element) which is equivalent to size() - `1`.

## index()

Top

Returns the current index number which is in the range `0` to max().

## count()

Top

Returns the current iteration count in the range `1` to size(). This is equivalent to index() + `1`.

## first()

Top

Returns a boolean value to indicate if the iterator is currently on the first iteration of the set.

## last()

Top

Returns a boolean value to indicate if the iterator is currently on the last iteration of the set.

## prev()

Top

Returns the previous item in the data set, or `undef` if the iterator is on the first item.

## next()

Top

Returns the next item in the data set or `undef` if the iterator is on the last item.

## parity()

Top

Returns the text string `even` or `odd` to indicate the parity of the current iteration count (starting at 1). This is typically used to create striped zebra tables.

    <table>
    [% FOREACH name IN ['Arthur', 'Ford', 'Trillian'] -%]
      <tr class="[% loop.parity %]">
        <td>[% name %]</td>
      </tr>
    [% END %]
    </table>

This will produce the following output:

    <table>
      <tr class="odd">
        <td>Arthur</td>
      </tr>
      <tr class="even">
        <td>Ford</td>
      </tr>
      <tr class="odd">
        <td>Trillian</td>
      </tr>
    </table>

You can then style the `tr.odd` and `tr.even` elements using CSS:

    tr.odd td {
        background-color: black;
        color: white;
    }

    tr.even td {
        background-color: white;
        color: black;
    }

## odd()

Top

Returns a boolean (0/1) value to indicate if the current iterator count (starting at 1) is an odd number. In other words, this will return a true value for the first iterator, the third, fifth, and so on.

## even()

Top

Returns a boolean (0/1) value to indicate if the current iterator count (starting at 1) is an even number. In other words, this will return a true value for the second iteration, the fourth, sixth, and so on.

# AUTHOR

Top

Andy Wardley <abw@wardley.org> http://wardley.org/

# COPYRIGHT

Top

Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

# SEE ALSO

Top

Template

http://template-toolkit.org/docs/modules/Template/Iterator.html