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

cpanm Petal::Utils

perl -MCPAN -e shell
install Petal::Utils