.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Petal::Deprecated 3pm"
.TH Petal::Deprecated 3pm "2020-05-22" "perl v5.30.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Petal::Deprecated \- Documents Petal's deprecated syntax.
.SH "IMPORTANT NOTE"
.IX Header "IMPORTANT NOTE"
This is an article, not a module.
.PP
From version 2.00 onwards Petal *requires* that you use well-formed \s-1XML.\s0 This
is because Petal now uses MKDoc::XML::TreeBuilder rather than
HTML::TreeBuilder and XML::Parser.
.PP
In particular, this version of Petal *CAN* break backwards compatibility if you
were using Petal's \s-1HTML\s0 mode will non well formed \s-1XHTML.\s0
.PP
If you still want to use broken \s-1XHTML,\s0 you can Petal 2.00 in conjunction with
Petal::Parser::HTB which has been created for this purpose.
.SH "INLINE VARIABLES SYNTAX"
.IX Header "INLINE VARIABLES SYNTAX"
.Vb 7
\&
\&
\&
\& This is the variable \*(Aqmy_var\*(Aq : ${my_var}.
\&
\&
.Ve
.PP
And if \f(CW\*(C`my_var\*(C'\fR contained \fIHello World\fR, Petal would have outputted:
.PP
.Vb 5
\&
\&
\& This is the variable \*(Aqmy_var\*(Aq : Hello World.
\&
\&
.Ve
.PP
Now let's say that \f(CW\*(C`my_var\*(C'\fR is a hash reference as follows:
.PP
.Vb 1
\& $VAR1 = { hello_world => \*(AqHello, World\*(Aq }
.Ve
.PP
To output the same result, you would write:
.PP
.Vb 1
\& This is the variable \*(Aqmy_var\*(Aq : ${my_var/hello_world}.
.Ve
.SH "SETTING PETAL OPTIONS AS GLOBALS"
.IX Header "SETTING PETAL OPTIONS AS GLOBALS"
If you want to use an option throughout your entire program and don't want to
have to pass it to the constructor each time, you can set them globally. They
will then act as defaults unless you override them in the constructor.
.PP
.Vb 12
\& $Petal::BASE_DIR (use base_dir option)
\& $Petal::INPUT (use input option)
\& $Petal::OUTPUT (use output option)
\& $Petal::TAINT (use taint option)
\& $Petal::ERROR_ON_UNDEF_VAR (use error_on_undef_var option)
\& $Petal::DISK_CACHE (use disk_cache option)
\& $Petal::MEMORY_CACHE (use memory_cache option)
\& $Petal::MAX_INCLUDES (use max_includes option)
\& $Petal::LANGUAGE (use default_language option)
\& $Petal::DEBUG_DUMP (use debug_dump option)
\& # $Petal::ENCODE_CHARSET (use encode_charset option) \-\- _DEPRECATED_
\& $Petal::DECODE_CHARSET (use decode_charset option)
.Ve
.SH "TAL DIRECTIVES ALIASES"
.IX Header "TAL DIRECTIVES ALIASES"
On top of all that, for people who are lazy at typing the following
aliases are provided (although I would recommend sticking to the
defaults):
.PP
.Vb 6
\& * tal:define \- tal:def, tal:set
\& * tal:condition \- tal:if
\& * tal:repeat \- tal:for, tal:loop, tal:foreach
\& * tal:attributes \- tal:att, tal:attr, tal:atts
\& * tal:content \- tal:inner
\& * tal:replace \- tal:outer
.Ve
.PP
\&\s-1TRAP:\s0
.PP
Don't forget that the default prefix is \f(CW\*(C`petal:\*(C'\fR \s-1NOT\s0 \f(CW\*(C`tal:\*(C'\fR, until
you set the petal namespace in your \s-1HTML\s0 or \s-1XML\s0 document as follows:
.PP
.Vb 1
\&
.Ve
.SH "XINCLUDES"
.IX Header "XINCLUDES"
Let's say that your base directory is \f(CW\*(C`/templates\*(C'\fR,
and you're editing \f(CW\*(C`/templates/hello/index.html\*(C'\fR.
.PP
From there you want to include \f(CW\*(C`/templates/includes/header.html\*(C'\fR
.SS "general syntax"
.IX Subsection "general syntax"
You can use a subset of the XInclude syntax as follows:
.PP
.Vb 3
\&
\&
\&
.Ve
.PP
For backwards compatibility reasons, you can omit the first slash, i.e.
.PP
.Vb 1
\&
.Ve
.SS "relative paths"
.IX Subsection "relative paths"
If you'd rather use a path which is relative to the template itself rather
than the base directory, you can do it but the path \s-1MUST\s0 start with a dot,
i.e.
.PP
.Vb 1
\&
\&
\&
.Ve
.PP
etc.
.SS "limitations"
.IX Subsection "limitations"
The \f(CW\*(C`href\*(C'\fR parameter does not support URIs, no other tag than \f(CW\*(C`xi:include\*(C'\fR is
supported, and no other directive than the \f(CW\*(C`href\*(C'\fR parameter is supported at
the moment.
.PP
Also note that contrarily to the XInclude specification Petal \s-1DOES\s0 allow
recursive includes up to \f(CW$Petal::MAX_INCLUDES\fR. This behavior is very useful
when templating structures which fit well recursive processing such as trees,
nested lists, etc.
.PP
You can \s-1ONLY\s0 use the following Petal directives with Xinclude tags:
.PP
.Vb 4
\& * on\-error
\& * define
\& * condition
\& * repeat
.Ve
.PP
\&\f(CW\*(C`replace\*(C'\fR, \f(CW\*(C`content\*(C'\fR, \f(CW\*(C`omit\-tag\*(C'\fR and \f(CW\*(C`attributes\*(C'\fR are \s-1NOT\s0 supported in
conjunction with XIncludes.
.SH "UGLY SYNTAX"
.IX Header "UGLY SYNTAX"
For certain things which are not doable using \s-1TAL\s0 you can use what
I call the \s-1UGLY SYNTAX.\s0 The \s-1UGLY SYNTAX\s0 is \s-1UGLY,\s0 but it can be handy
in some cases.
.PP
For example consider that you have a list of strings:
.PP
.Vb 2
\& $my_var = [ \*(AqFoo\*(Aq, \*(AqBar\*(Aq, \*(AqBaz\*(Aq ];
\& $template\->process (my_var => $my_var, buz => $buz);
.Ve
.PP
And you want to display:
.PP
.Vb 1
\& Hello : Foo : Bar : Baz
.Ve
.PP
Which is not doable with \s-1TAL\s0 without making the \s-1XHTML\s0 invalid.
With the \s-1UGLY SYNTAX\s0 you can do:
.PP
.Vb 1
\& Hello<?for name="string my_var"?> : <?var name="string"?><?end?>
.Ve
.PP
Of course you can freely mix the \s-1UGLY SYNTAX\s0 with other Petal
syntaxes. So:
.PP
.Vb 1
\& <?for name="string my_var"?> $string <?end?>
.Ve
.PP
Mind you, if you've managed to read the doc this far I must confess
that writing:
.PP
.Vb 1
\& $string
.Ve
.PP
instead of:
.PP
.Vb 1
\& Dummy
.Ve
.PP
is \s-1UGLY\s0 too. I would recommend to stick with \s-1TAL\s0 wherever you can.
But let's not disgress too much.
.SS "variables"
.IX Subsection "variables"
Abstract
.PP
.Vb 1
\&
.Ve
.PP
Example
.PP
.Vb 1
\& <?var name="document/title"?>
.Ve
.PP
Why?
.PP
Because if you don't have things which are replaced by real values in your
template, it's probably a static page, not a template... :)
.SS "if / else constructs"
.IX Subsection "if / else constructs"
Usual stuff:
.PP
.Vb 6
\&
\& Happy Birthday, $user/real_name!
\&
\& What?! It\*(Aqs not your birthday?
\& A very merry unbirthday to you!
\&
.Ve
.PP
You can use \f(CW\*(C`condition\*(C'\fR instead of \f(CW\*(C`if\*(C'\fR, and indeed you can use modifiers:
.PP
.Vb 6
\&
\& What?! It\*(Aqs not your birthday?
\& A very merry unbirthday to you!
\&
\& Happy Birthday, $user/real_name!
\&
.Ve
.PP
Not much else to say!
.SS "loops"
.IX Subsection "loops"
Use either \f(CW\*(C`for\*(C'\fR, \f(CW\*(C`foreach\*(C'\fR, \f(CW\*(C`loop\*(C'\fR or \f(CW\*(C`repeat\*(C'\fR. They're all the same
thing, which one you use is a matter of taste. Again no surprise:
.PP
.Vb 7
\& Listing of user logins
\&
.Ve
.PP
Variables are scoped inside loops so you don't risk to erase an existing
\&\f(CW\*(C`user\*(C'\fR variable which would be outside the loop. The template engine also
provides the following variables for you inside the loop:
.PP
.Vb 9
\&
\& \- iteration number, starting at 0
\& \- iteration number, starting at 1
\& \- is it the first iteration?
\& \- is it the last iteration?
\& \- is it not the first and not the last iteration?
\& \- is the count even?
\& \- is the count odd?
\&
.Ve
.PP
Again these variables are scoped, you can safely nest loops, ifs etc... as
much as you like and everything should be fine.
.SS "Includes"
.IX Subsection "Includes"
.Vb 1
\&
.Ve
.PP
It will include the file 'include.xml', using the current \f(CW@Petal::BASE_DIR\fR
directory list.
.PP
If you want use XML::Parser to include files, you should make sure that
the included files are valid \s-1XML\s0 themselves... \s-1FYI\s0 XML::Parser chokes on
this:
.PP
.Vb 2
\& foo
\& bar
.Ve
.PP
But this works:
.PP
.Vb 4
\&
.Ve
.PP
(Having only one top element is part of the \s-1XML\s0 spec).