README

=== Flower -- Petal for Perl 6
Petal is the Perl Template Attribute Language (Perl 5), and is derived from the
TAL, METAL and TALES specifications from Zope (Python).
Flower is an implementation of Petal in Perl 6.
It's not the same as the Perl 5 implementation, and has a different
feature-set and parsing model.
That said, it tries to implement as much of Petal as possible in a mostly
compatible form, major differences are listed below.
Status: Flower is currently usable, but there are still plenty of planned
features. See the docs/TODO.txt for a list of things I'm planning.
= Requirements:
- Exemel, the XML library that powers Flower.
http://github.com/supernovus/exemel/
= Optional libraries:
- Temporal-Utils, needed if you want to use Flower::Utils::Date
http://github.com/supernovus/temporal-utils/
= Major Differences from Petal:
* The default local namespace is 'tal', and to override it, you must
declare http://xml.zope.org/namespaces/tal instead of the Petal namespace.
* Flower can use template strings instead of requiring files.
* Flower does not support the multiple template files based on language.
* Adding custom modifiers is completely different in Flower.
* There is NO support for anything but well-formed XML.
There is no equivelant to the Petal::Parser::HTB, and no plans for one.
Use well-formed XML, it's just better.
* Flower supports petal:block elements, as per the PHPTAL project.
* While you can use the 'structure' keyword, it's not really needed.
If you want an unescaped XML structure for a replacement, send an
Exemel object (any class other than Document) and it will be added to
the XML tree. Send an array of Exemel objects, and they will additionally
be parsed for TAL statements.
* Nested repeats cannot use the same attribute name, it will get clobbered.
* The built-in repeat object is implemented as per the Zope/PHPTAL, not
the Petal version. Note: it does not support the 'letter' or 'Letter'
attributes, but instead has some new methods that take paramters:
'every xx' the number (not the index) is divisible by xx.
'skip xx' the number is not divisible by xx.
'gt xx' the number is greater than xx.
'lt xx' the number is less than xx.
'eq xx' the number is equal to xx.
'ne xx' the number is not equal to xx.
* I'm not sure how Petal, PHPTAL or Zope deal with TAL attributes in the
root element (the top-most element of the document), but to avoid death,
destruction and mayhem, Flower only processes 'define', 'attributes'
and 'content' tags on the root element. The rest of the tags are only
processed on children of the root.
The above list will be updated as this project is developed, as I'm sure
other changes will be introduced that will be a gotchya for users of Petal,
Zope or PHPTAL.
= Flower::Utils
Inspired by Petal::Utils, Flower includes a namespace called Flower::Utils::
If you load modules in the Petal::Utils:: namespace, it will add additional
modifiers. The following sets are planned for inclusion (at the current time
there are only a couple available, with a subset of the modifiers):
- Text*, same as the :text set from Petal::Utils
- Logic, same as the :logic set from Petal::Utils
- List*, same as the :list set from Petal::Utils, plus group: which
turns a flat Array into a nested Array, where each inner Array has a
set number of elements in it.
- Hash, same as the :hash set from Petal::Utils
- Date, similar to the :date set from Petal::Utils, using on DateTime::Utils
Not exactly the same, it offers strftime: and rfc: and works on
DateTime and Date objects in addition to epoch timestamps.
If you pass a DateTime or Date object without one of these filters you
will get its standard stringification form (ISO by default.)
- Perl**, makes a 'perl:' modifier available, which is the counterpart
to Zope's 'python:' or PHPTAL's 'php:' modifiers.
- Debug**, similar to :debug set from Petal::Utils.
dump: modifier spits out the .perl representation of the object.
what: modifier spits out the class name of the object.
Sets marked with * have been partially implemented and are included with
the current version of Flower. Sets marked with ** are fully implemented.
The interfaces to the modifiers included with Flower may not be compatible
with the ones from Petal. For instance in Petal::Utils, you could call
<div tal:replace="substr: $string 2 5 1">
whereas with Flower::Utils::Text you would use:
<div tal:replace="substr: 2,5,1 string">
Full documentation for the usage of Flower and the Flower::Utils modifiers
will be included in the docs/ folder in an upcoming release, until then
there are comments in the libraries, and test files in t/ that show the
proper usage.
The URI set from Petal::Utils is not planned for inclusion,
feel free to write it if you need it.
I'm sure new exciting libraries will be made adding onto these.
= Author: Timothy Totten
= License: Artistic License 2.0
http://www.perlfoundation.org/artistic_license_2_0