iA::Page - Object oriented interface to handling sections within
templated webpages with iAct.
package My::App;
use strict;
use iA;
# call me with <% call "My::App::some_function" %>
sub some_function {
my ($self, $args) = @_;
# return the piece of HTML that gets inserted
# in place of the <% call %>
return do_something($args->{some_param});
}
iAct is a web development and templating framework built on
Apache and mod_perl. See the iA.pm documentation for a
general overview.
When iAct handles a request, an iA::Page objects is created for each
HTML or TMPL file processed (there can be quite a few of them, with
<% parent %> and <% import %> commands).
The iA::Page object defines a number of methods, which can be used
to access, assign and handle the contents of <% sections %> within
the page.
(Some of the methods are public wrt the iA::Page object, but are
meant to be used by other pieces of iAct, and not by the application
writer; their names are not in bold in this documentation).
- new($filename, $options)
-
Open an iAct-HTML page, going through the cache and parsing the
sections, but not taking any <% parent %> or <% import %>s into
account. Returns an iA::Page object.
-
The $filename is absolute. $options is a hashref with parameters to
be passed to iA::Page. The only recognized option is 'lang', which
introduces an arrayref of language names, by preference order.
-
This constructor is not generally meant to be used by application
code directly; in most cases, you will want to use iA::get_page(),
iA::get_template(), or iA::Template->new() instead.
clone()
-
The
clone() method makes an copy of an iA::Page object, copying all
the cache-able stuff (including section contents in all languages,
but not including any dependent files, such as imports, or any
eval-time information).
-
This is mainly used by Page::Cache, to keep serialized copies of
iA::Page objects instead of re-parsing HTML files every time.
parentfile()
-
Get the name of the <% parent %> file for this page. Returns undef
if there is no parent. If the parent was dynamic (eg. with <%
parent sub=``Some::Module::function'' %>, the function gets called at
this point.
importfiles()
-
Get the names of the <% import %> files for this page. Returns an
arrayref with their names.
-
If there are dynamic imports (eg. with <% import
sub=``Some::Module::function'' %>, the functions gets called at this
point.
setchild($page)
-
Set the 'child' property of the current page. The argument must be
a reference to another iA::Page object.
getchild()
-
Get the iA::Page object for the page that has this one as its <%
parent %>. Returns undef if this page was not requested as a <%
parent %>.
setparent($page)
-
Set the 'parent' property of the current page. The argument must be
a reference to another iA::Page object.
language()
-
Get or set the 'language' property of this file. This is the
2-letter code of the language that this file is mainly in, if known.
Page::Lang uses this method to set the language from the file
extension.
addimports()
-
This method processes the <% import %> statements in an iA::Page
object, by copying over the missing sections from the imported
pages.
-
This is called from iA::Template.
- has_section($name)
-
Checks whether an iA::Page object has a section or not. Note that
this does not follow the parent/child chain at all. Use the find_*
functions if you want that.
- has_lang($lang)
-
Checks whether an iA::Page object has any content in the given
language code, or not.
run_inits_set_langs()
-
Follows the parent chain, starting at the final child, running 'init'
blocks and setting the 'evallangs' property. Called by iA::Template.
- eval($section, $lang, $sec_args>
-
Evaluates the given section in the current page, returning the
section's HTML (including any dynamic parts generated by <% call
%>.
-
$section is the section's name; $lang must be an arrayref of
language codes in preference order. $sec_args is a hashref with
section-arguments (pass { } if you don't need any).
-
This is mostly used by iA::Template; user code might want to use
one of the fetch_* functions instead.
- find_here($name)
-
Looks for a section with the given name in the current page. Returns
the page object itself if found, and undef if not.
- find_forw($name)
-
Looks for a section with the given name in the current page, or in
its child, or in the child's child, and so on. Returns the first
page object that has the given section, or undef if not found.
- find_back($name)
-
Looks for a section with the given name in the current page, or in
its parent, or in the parent's parent, and so on. Returns the
closest page object that has the given section, or undef if not
found.
- find_last($name)
-
Looks for a section with the given name in the current page, or in
its child, or in the child's child, and so on. Returns the last
page object that has the given section, or undef if not found.
- find_first($name)
-
Looks for a section with the given name in the current page, or in
its parent, or in the parent's parent, and so on. Returns the
farthest page object (in the direction of the parents) that has
the given section, or undef if not found.
- find_next($name)
-
Looks for a section with the given name in this page's child, or in
the child's child, and so on, but skipping the current page.
Returns the first page object that has the given section, or undef
if not found.
- find_prev($name)
-
Looks for a section with the given name in this page's parent, or in
the parent's parent, and so on, but skipping the current page.
Returns the first page object that has the given section, or undef
if not found.
- languages()
-
Returns a list of language codes, in order of preference. Called
subs might want to use this in order to generate content in the
right language.
- main_lang()
-
Returns the first (main) language code for the page that is being
generated.
- available_langs()
-
Returns a list of languages for which content is available in this page.
- clear($name)
-
Clears the given section; this is the same as $page->assign_raw($name, ``'');
- fetch($name, $method, $args)
-
Fetches (and evaluates) the contents of a given section, by name.
-
$method refers to how the system will look for the current section;
it's one of 'here', 'forw', 'back', 'last', 'first', 'next' and
'prev'. The default is 'here'.
-
$args is an optional hashref with section-arguments.
- fetch_here($name, $args)
-
Fetches (and evaluates) the contents of a given section, by name.
Searches for the section in the current page only.
-
$args is an optional hashref with section-arguments.
- fetch_forw($name, $args)
-
Fetches (and evaluates) the contents of a given section, by name.
Searches for the section in the current page, then in the direction
of the children, stopping as soon as a matching section is found.
-
$args is an optional hashref with section-arguments.
- fetch_back($name, $args)
-
Fetches (and evaluates) the contents of a given section, by name.
Searches for the section in the current page, then in the direction
of the parents, stopping as soon as a matching section is found.
-
$args is an optional hashref with section-arguments.
- fetch_last($name, $args)
-
Fetches (and evaluates) the contents of a given section, by name.
Searches for the section in the current page, then in the direction
of the children, keeping the last matching section.
-
$args is an optional hashref with section-arguments.
- fetch_first($name, $args)
-
Fetches (and evaluates) the contents of a given section, by name.
Searches for the section in the current page, then in the direction
of the parents, keeping the last matching section (which is the
'first' if you think of the parents as coming first).
-
$args is an optional hashref with section-arguments.
- fetch_next($name, $args)
-
Fetches (and evaluates) the contents of a given section, by name.
Searches for the section in the the direction
of the parents, skipping the current page, and stopping as soon as a
matching section is found.
-
$args is an optional hashref with section-arguments.
- fetch_prev($name, $args)
-
Fetches (and evaluates) the contents of a given section, by name.
Searches for the section in the the direction of the children,
skipping the current page, and stopping as soon as a matching
section is found.
-
$args is an optional hashref with section-arguments.
- assign($name, $content)
-
Assigns the given content to the given section name. The content
is HTML-escaped, so any <tags> will show up as <tags> to the end user.
-
This is suitable for non-HTML content which doesn't need to be
trusted, e.g. content from the database or from the user's
iA::param()s.
-
Use assign_raw if you don't want the HTML-escaping behavior, and
use assign_parse if you want your assigned content to be parsed
for <% commands %>.
- assign_raw($name, $html)
-
Assigns the given HTML text to the given section name. The HTML is
not parsed for any <% commands %>, and will be sent straight to the
browser if the section is evaluated.
- assign_parse($name, $html)
-
Assigns the given HTML text to the given section name. The HTML is
parsed and any <% commands %> are evaluated.
- add($name, $content)
-
Appends the given HTML text to the given section name.
-
The content is HTML-escaped; use add_raw() if you don't
want that behavior.
- add_raw($name, $html)
-
Appends the given HTML text to the given section name. The HTML is
not parsed for any <% commands %>, and will be sent straight to the
browser if the section is evaluated.
- add_parse($name, $html)
-
Appends the given HTML text to the given section name. The HTML is
parsed and any <% commands %> are evaluated; use add_raw() if you
don't want that behavior.
- add_filter($section, ``Module::sub'', { any = ``params'' })>
-
Adds a filter to a section. Filters are evaluated at the very end
of a section's evaluation, and they can read and modify the
section's output.
- parse($name1, $name2)
-
Evaluate the section $name2 (here) and assign it (raw) into the
section $name1.
-
If you prepend a dot ('.') to $name1, the contents of the $name2
section are appeneded, rather than assigned, to $name1.
-
This is a confusing interface, provided only for compatibility with
CGI::FastTemplate. You will probably want to avoid it, except when
porting code that uses CGI::FastTemplate.