/ 
Petal-Utils-0.05
River stage one • 1 direct dependent • 1 total dependent
/ Petal::Utils

NAME

Petal::Utils - Useful template modifiers for Petal.

SYNOPSIS

# install the default set of Petal modifiers:
use Petal::Utils;

# you can also install modifiers manually:
Petal::Utils->install( 'some_modifier', ':some_set' );

# see below for modifiers available & template syntax

DESCRIPTION

The Petal::Utils package contains commonly used Petal modifiers (or plugins), and bundles them with an easy-to-use installation interface. By default, a set of modifiers are installed into Petal when you use this module. You can change which modifiers are installed by naming them after the use statement:

# use the default set:
use Petal::Utils qw( :default );

# use the date set of modifiers:
use Petal::Utils qw( :date );

# use only named modifiers, plus the debug set:
use Petal::Utils qw( UpperCase Date :debug );

# don't install any modifiers
use Petal::Utils qw();

You'll find a list of plugin sets throughout this document. You can also get a complete list by looking at the variable:

%Petal::Utils::PLUGIN_SET;

For details on how the plugins are installed, see the "Advanced Petal" section of the Petal documentation.

MODIFIERS

Each modifier is listed under the set it belongs to.

:text

lowercase:, lc: $string

Make the entire string lowercase.

<p tal:content="lc: $string">lower</p>
uppercase:, uc: $string

Make the entire string uppercase.

<p tal:content="uc: $string">upper</p>
uc_first: $string

Make the first letter of the string uppercase.

<p tal:content="uc_first: $string">uc_first</p>

:date

date: $date

Convert a time() integer to a date string using Date::Format.

<span tal:replace="date: $date">Jan  1 1970 01:00:01</span>
us_date: $date

Convert an international date stamp (e.g., yyyymmdd, yyyy-mm-dd, yyyy/mm/dd) to US format (mm/dd/yyyy).

<p tal:content="us_date: $date">2003-09-05</p>

:logic

if: $expr1 then: $expr2 else: $expr3

Do an if/then/else test and return the value of the expression executed. Truthfulness of $expr1 is according to Perl (e.g., non-zero, non-empty string).

<p tal:attributes="class if: on_a_page then: a_class else: another_class">
  Some text here...
</p>
or: $expr1 $expr2

Do a logical or. Truthfulness is according to Perl (e.g., non-zero, non-empty string).

<p tal:if="or: $first $second">
  first or second = <span tal:replace="or: $first $second">or</span>
</p>
and: $expr1 $expr2

Do a logical and. Truthfulness is according to Perl (e.g., non-zero, non-empty string).

first and second = <span tal:replace="and: $first $second">and</span>
equal:, eq: $expr1 $expr2

Test for equality. Numbers are compared with ==, strings with eq. Truthfulness is according to Perl (e.g., non-zero, non-empty string).

first eq second = <span tal:replace="eq: $first $second">equal</span>
like: $expr $regex

Test for equality to a regular expression (see perlre).

name like regex = <span tal:replace="like: $name ^Will.+m">like</span>

:list

sort: $list

Sort the values in a list before returning it.

<ul>
  <li tal:repeat="item sort: $array_ref">$item</li>
</ul>

:hash

keys: $hash

Return a list of keys for a hashref. Note: It appears that values cannot be accessed with dynamic keys. If you need the keys and values, use "each:".

<ul>
  <li tal:repeat="key keys: $hash_ref"><span tal:replace="key">key</span></li>
</ul>
each: $hash

Return a list of key/value pairs for a hashref.

<ul>
  <li tal:repeat="item each: $hash_ref">
    <span tal:replace="item/key">key</span> => <span tal:replace="item/val">value</span>
  </li>
</ul>

:uri

uri_escape: $expr

Use URI::Escape's uri_escape() to escape the return value of the expression.

<a href="http://foo/get.html?item=${uri_escape: item/key}">get $item/key</a>

:debug

dump: $expr

Dump the data strcture of the value given.

dump name: <span tal:replace="dump: name">dump</span>

SUPERSETS

At the time of writing, the following supersets were available:

':none'    => [],
':all'     => [qw( :default :hash :debug )],
':default' => [qw( :text :date :logic :list )],

See %Petal::Utils::PLUGIN_SET for an up-to-date list.

AUTHORS

William McKee <william@knowmad.com>, and Steve Purkis <spurkis@cpan.org>

COPYRIGHT

Copyright (c) 2003-2004 William McKee & Steve Purkis.

This module is free software and is distributed under the same license as Perl itself. Use it at your own risk.

THANKS

Thanks to Jean-Michel Hiver for making Petal available to the Perl community.

SEE ALSO

Petal