view release on metacpan or  search on metacpan

lib/XAO/DO/Web/Page.pm  view on Meta::CPAN

   mode="show-hash"
   fields="*"
   template='<%MEMBER_AGE/f%> -- <%MEMBER_STATUS/f%>'
 %>

If double quotes were used in this example then the parser would try to
expand <%MEMBER_AGE%> and <%MEMBER_STATUS%> variables using the current
object arguments which is not what is intended. Using single quotes it
is possible to let FS object do the expansion and therefore insert
database values in this case.

=item 5

To pass multiple nested arguments literally or to include a single quote
into the string matching pairs of {' and '} can be used:

 <%FS
   uri="/Members/<%MEMBER_ID/f%>"
   mode="show-hash"
   fields="*"
   template={'Member's age is <%MEMBER_AGE/f%>'}
 %>

=back


=head2 BINARY vs UNICODE

By default expanded templates and object arguments are bytes, not
Unicode characters. This does not mean that they cannot be used in
Unicode (or other encoding) web sites, but it does mean that objects
need to convert arguments and expansion results into characters where
and as needed.

Starting with version 1.48 it is possible to switch the engine
into returning perl characters from template expansion and for
passing characters in object arguments. This is achieved by setting
/xao/page/character_mode configuration parameter to '1'.

One exception allowing to retrieve byte data is when a template is
expanded with 'unparsed' qualifier. This is typically used to pass
binary data such as images and spreadsheets to objects such as
L<XAO::DO::Web::Mailer>.

There is an important caveat for using 'unparsed' with binary data in
character mode. A template like the one below wou pass perl characters
in 'data' argument when executing Process.

  <%Process
    data={<%Page
            path='/binary/data.bin'
            unparsed
          %>}
  %>

There is no way to mix byte and character processing mode. Pick one
depending on your needs. Character mode allows a more natural processing
in Perl while byte mode allows more granular control over the data flow.


=head2 EMBEDDING SPECIAL CHARACTERS

Sometimes it is necessary to include various special symbols into
argument values. This can be done in the same way you would embed
special symbols into HTML tags arguments:

=over

=item *

By using &tag; construction, where tag could be "quot", "lt", "gt" and
"amp" for double quote, left angle bracket, right angle bracket and
ampersand respectfully.

=item *

By using &#NNN; construction where NNN is the decimal code for the
corresponding symbol. For example left curly bracket could be encoded as
&#123; and right curly bracket as &#125;. The above example should be
re-written as follows to make it legal:

 name={single &#123; inside}

=back


=head2 OUTPUT CONVERSION

As the very final step in the processing of an embedded object or
variable the parser will check if it has any flags and convert it
accordingly. This can (and should) be used to safely pass special
characters into fields, HTML documents and so on.

For instance, the following code might break if you do not use flags and
variable will contain a duoble quote character in it:

 <INPUT TYPE="TEXT" VALUE="<$VALUE$>">

Correct way to write it would be (note /f after VALUE):

 <INPUT TYPE="TEXT" VALUE="<$VALUE/f$>">

Generic format for specifying flags is:

 <%Object/x ...%> or <$VARIABLE/x$>

Where 'x' could be one of:

=over

=item f

Converts text for safe use in HTML elements attributes. Mnemonic for
remembering - (f)ield.

Will convert '123"234' into '123&quot;234'.

=item h

Converts text for safe use in HTML text. Mnemonic - (H)TML.