%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Copyright 2001 by Object Craft P/L, Melbourne, Australia.
% LICENCE - see LICENCE file distributed with this software for details.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Templates Reference\label{tag-ref}}

Albatross provides an HTML templating system that applications use to
provide the presentation layer.

The template parser uses regular expressions to locate all of the
template tags.  All text that is not recognised as an Albatross tag
or associated trailing whitespace is passed unchanged through the
parser.  In practice this means that you can use the templating system
for non-HTML files.

The parser regular expressions recognise all tags names that are
prefixed by either ``al-'' or ``alx-''.  All standard Albatross tags
use the ``al-''.  The ``alx-'' prefix is provided to ensure extension
tag names do not clash with standard names.

For Albatross tags that enclose content you can use the XML empty tag
syntax to indicate that there is no content.  The parser transforms
all tag and attribute names to lowercase and allows attributes on
multiple lines.  For example the following two constructs are
identical.

\begin{verbatim}
<al-for iter="i" expr="seq" pagesize="10" prepare>
</al-for>

<AL-FOR ITER="i"
        EXPR="seq"
        PAGESIZE="10"
        PREPARE/>
\end{verbatim}

The parser handles attribute values enclosed with either single or
double quotes.  The enclosing quote character can be used in the
attribute string if it is escaped by a backslash (``$\backslash$'').
Attribute values can be broken over multiple lines.

\section{Fake Application Harness\label{tag-fakeapp}}

Some of the explanatory examples in this chapter require application
functionality.  The following fake application is used as an execution
harness to drive the interactive examples.

\verbatiminput{fakeapp.py}

\section{Enhanced HTML Tags\label{tag-enhhtml}}

Tags in this section are used in place of standard HTML tags to access
values from the execution context.

All attributes that are not recognised by Albatross are passed without
modification to the generated HTML.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-form>

\subsection{\texttt{<al-form>}\label{tag-form}}

Albatross browser request merging depends upon the functionality
provided by the \texttt{<al-form>} tag.  If you do no use this tag in
applications then the standard request merging will not work.

The tag will automatically generate the HTML \texttt{<form>}
\texttt{action} (\ref{tag-form-action}) and \texttt{enctype}
(\ref{tag-form-enctype}) attributes as required.

If you are using an execution context that inherits from the
\class{NameRecorderMixin} (nearly all do --- see chapter
\ref{pack-overview}) then the execution context will raise a
\exception{ApplicationError} exception if multiple instances of some
types of input tag with the same name are added to a form.  The
\texttt{list} attribute of the \texttt{<al-input>} tag is used
indicate that multiple instances are intentional.

\subsubsection{\texttt{action="..."} attribute\label{tag-form-action}}

If you do not supply an \texttt{action} attribute the tag will
generate one with based on the value returned by the
\method{current_url()} method of the execution context.

\verbatiminput{doctest/tags-form-action}

Note that the generated \texttt{action} attribute is relative to the
document root.

\subsubsection{\texttt{enctype="..."} attribute\label{tag-form-enctype}}

If you include any file input fields then the open tag will
automatically supply an \texttt{enctype="multipart/form-data"}
attribute.

\verbatiminput{doctest/tags-form-file}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-input>

\subsection{\texttt{<al-input>}\label{tag-input}}

Albatross browser request merging depends upon the functionality
provided by the \texttt{<al-input>} tag.  If you do no use this tag in
applications then the standard request merging will not work.

In the most common usage a \texttt{value} (\ref{tag-input-value})
attribute is generated by evaluating the \texttt{name}
(\ref{tag-input-name}) attribute in the execution context.  This can
be overridden by supplying a \texttt{value} (\ref{tag-input-value}) or
\texttt{expr} (\ref{tag-input-expr}) attribute.

There are a number of attributes that automatically generate the
\texttt{name} attribute.

When merging browser requests the application object places the
browser supplied value back into the execution context value
referenced by the \texttt{name} attribute.  The application request
merging will not merge variable names prefixed by underscore.  Use
this to protect application values from browser modification.

\subsubsection{\texttt{alias="..."} attribute\label{tag-input-alias}}

This attribute is ignored is any of the following attributes are
present; \texttt{prevpage}, \texttt{nextpage} (\ref{tag-input-page}),
\texttt{treefold}, \texttt{treeselect}, or \texttt{treeellipsis}
(\ref{tag-input-tree}).

The value of the \texttt{alias} attribute is passed to the
\method{make_alias()} method of the execution context.  The return
value is then used as the generated \texttt{name}
(\ref{tag-input-name}) attribute.

The execution context \method{make_alias()} method splits the
\texttt{alias} attribute at the last '.' and resolves the left hand
side to an object reference.  The \method{albatross_alias()} method is
then called on that object and the result is combined with the '.'
and the right hand side of the of the \texttt{alias} attribute to
produce the generated \texttt{name} attribute.  The resolved object is
entered in the the local namespace and the session using the name
returned by the \method{albatross_alias()} method.

The template \texttt{samples/tree/tree1.html} contains an example of
this method for generating a \texttt{name} attribute.

\begin{verbatim}
<al-tree iter="n" expr="tree">
 <al-for iter="c" expr="range(n.depth())">
  <al-value expr="n.line(c.value())" lookup="indent">
 </al-for>
 -<al-input type="checkbox" alias="n.value().selected">
  <al-value expr="n.value().name" whitespace="newline">
</al-tree>
\end{verbatim}

Note that each node in the tree has a checkbox that controls whether
or not the node is selected.  When processing the \texttt{alias}
attribute the toolkit isolates the left hand side (\texttt{n.value()})
which happens to be the current tree node of \class{TreeIterator}
\texttt{n}.  To generate the alias the \method{albatross_alias()}
method of the current node is called.  In
\texttt{samples/tree/tree1.py} the implementation of that method looks
like:

\begin{verbatim}
class Node:
    def albatross_alias(self):
        return 'node%d' % self.node_num
\end{verbatim}

When the template is executed a unique name is generated for each
checkbox.  The exact HTML produced by the above fragment from the
sample looks like this:

\begin{verbatim}
-<input type="checkbox" name="node12.selected" value="on">a
 |-<input type="checkbox" name="node2.selected" value="on">a
 | |-<input type="checkbox" name="node0.selected" value="on">a
 | \-<input type="checkbox" name="node1.selected" value="on">b
 \-<input type="checkbox" name="node11.selected" value="on">b
   |-<input type="checkbox" name="node6.selected" value="on">a
   | \-<input type="checkbox" name="node5.selected" value="on">a
   |   |-<input type="checkbox" name="node3.selected" value="on">a
   |   \-<input type="checkbox" name="node4.selected" value="on">b
   |-<input type="checkbox" name="node7.selected" value="on">b
   \-<input type="checkbox" name="node10.selected" value="on">c
     |-<input type="checkbox" name="node8.selected" value="on">a
     \-<input type="checkbox" name="node9.selected" value="on">b
\end{verbatim}

The \texttt{alias} handling uses the fact that all Python objects are
stored by reference.  It obtains a reference to an existing object by
resolving an expression and stores that reference under a new name.
Since both the original expression and the new name are the same
reference, the toolkit can modify the object referenced by the
original expression by using the new name.

Looking further into the \texttt{samples/tree/tree1.py} code you will
note that the tree being iterated is generated once and placed into
the session.  This ensures that the alias names generated always
contain references to the nodes in the tree.  If the tree was not
entered into the session but was generated from scratch every request,
the nodes referenced in the alias names would not be the same nodes as
those in the tree so all input would be lost.

\subsubsection{\texttt{checked} attribute\label{tag-input-checked}}

This attribute is generated in \texttt{radio} and \texttt{checkbox}
input field types if the generated \texttt{value} (\ref{tag-input-value})
attribute matches the comparison value from \texttt{valueexpr}
(\ref{tag-input-valueexpr}) (or the literal \code{'on'} for the
\texttt{checkbox} input field type).

Refer to the documentation for individual input types for more
details.

\subsubsection{\texttt{expr="..."} attribute\label{tag-input-expr}}

For \texttt{text}, \texttt{password}, \texttt{submit}, \texttt{reset},
\texttt{hidden}, and \texttt{button} input field types the expression
in the \texttt{expr} attribute is evaluated and the result is used to
generate the \texttt{value} (\ref{tag-input-value}) attribute.  If the
result is \code{None} then no \texttt{value} attribute will be
written.

For \texttt{radio} and \texttt{checkbox} input field types the
expression in the \texttt{expr} attribute is evaluated and the result
is compared with the generated \texttt{value} attribute to determine
whether or not the \texttt{checked} (\ref{tag-input-checked})
attribute should be written.

Refer to the documentation for individual input types for more
details.

\subsubsection{\texttt{list} attribute\label{tag-input-list}}

If you are using an execution context that inherits from the
\class{NameRecorderMixin} (nearly all do --- see chapter
\ref{pack-overview}) then the execution context will raise a
\exception{ApplicationError} exception if multiple instances of some
types of input tag with the same name are added to a form.  The
\texttt{list} attribute of the \texttt{<al-input>} tag is used
indicate that multiple instances are intentional.

The presence of the \texttt{list} attribute on an \texttt{<al-input>}
tag makes the request merging in the \class{NameRecorderMixin} class
place any browser request values for the field into a list (field not
present is represented by the empty list).

The attribute must not be used for input field types \texttt{radio},
\texttt{submit}, and \texttt{image}.  The attribute is ignored for the
\texttt{file} input field type.

\subsubsection{\texttt{name="..."} attribute\label{tag-input-name}}

When determining the generated \texttt{name} attribute the tag looks
for a number of attributes.  Any supplied \texttt{name} attribute will
be ignored if any of the following attributes are present;
\texttt{prevpage}, \texttt{nextpage} (\ref{tag-input-page}),
\texttt{treefold}, \texttt{treeselect}, \texttt{treeellipsis}
(\ref{tag-input-tree}), \texttt{alias} (\ref{tag-input-alias}), or
\texttt{nameexpr} (\ref{tag-input-nameexpr}).

All of the attributes that automatically generate names and are looked
up in the above sequence.  The first of those attributes found will be
used to determine the name used in the tag.

\subsubsection{\texttt{nameexpr="..."} attribute\label{tag-input-nameexpr}}

This attribute is ignored if any of the following attributes are
present; \texttt{prevpage}, \texttt{nextpage} (\ref{tag-input-page}),
\texttt{treefold}, \texttt{treeselect}, \texttt{treeellipsis}
(\ref{tag-input-tree}), or \texttt{alias} (\ref{tag-input-alias}).

The expression in the value of the \texttt{nameexpr} attribute is
evaluated to determine the generated \texttt{name}
(\ref{tag-input-name}) attribute.

One shortcoming of the \texttt{alias} attribute is that you can only
perform input on object attributes.  The \texttt{nameexpr} enables you
to perform input on list elements.

\verbatiminput{doctest/tags-input-nameexpr}

When the browser request is merged into the execution context the
names elements of the \texttt{names} list will be replaced.

\subsubsection{\texttt{node="..."} attribute\label{tag-input-node}}

The \texttt{node} attribute is used in conjunction with the
\texttt{treeselect}, \texttt{treefold} and \texttt{treeellipsis}
(\ref{tag-input-tree}) attributes.  It is ignored otherwise.

When this attribute is present the node identified by evaluating the
expression in the attribute value will be used when generating the
\texttt{name} attribute.

The \texttt{name} (\ref{tag-input-name}) attribute is generated as
follows:

\verbatiminput{doctest/tags-input-treeselect-node}

Refer to the documentation for \texttt{treeselect}, \texttt{treefold}
and \texttt{treeellipsis} (\ref{tag-input-tree}) attributes for more
information.

\subsubsection{\texttt{noescape} attribute\label{tag-input-noescape}}

The \texttt{noescape} attribute can be used in conjunction with the
\texttt{text}, \texttt{password}, \texttt{submit}, \texttt{reset},
\texttt{hidden}, and \texttt{button} input fields, it is ignored
otherwise.

When this attribute is present the \texttt{value}
(\ref{tag-input-value}) attribute will not be escaped.

\verbatiminput{doctest/tags-input-noescape}

\subsubsection{\texttt{prevpage="..."} and \texttt{nextpage="..."} attributes\label{tag-input-page}}

The \texttt{prevpage} and \texttt{nextpage} attributes respectively
select the previous and next pages of an \texttt{<al-for>}
\class{ListIterator} (\ref{tag-for-listiter}).

An attribute value must be supplied that specifies the name of the
iterator.

The \texttt{name} (\ref{tag-input-name}) attribute is generated as
follows:

\verbatiminput{doctest/tags-input-nextpage}

When merging the browser request the
\method{NamespaceMixin.set_value()} (\ref{mixin-namespace}) method
looks for field names that contain commas.  These names are split into
\emph{operation}, \emph{iterator}, and optional \emph{value} then the
\method{set_backdoor()} method of the identified iterator is invoked.

During request merging the above example will execute code equivalent
to the following.

\begin{verbatim}
ctx.locals.i.set_backdoor('nextpage', 'nextpage,i')
\end{verbatim}

\subsubsection{\texttt{treeselect="..."}, \texttt{treefold="..."} and \texttt{treeellipsis="..."} attributes\label{tag-input-tree}}

The \texttt{treeselect}, \texttt{treefold}, and \texttt{treeellipsis}
attributes respectively select, open/close, or expand the ellipsis of
an \texttt{<al-tree>} node via a \class{LazyTreeIterator}
(\ref{tag-tree-lazytreeiter}) or \class{EllipsisTreeIterator}
(\ref{tag-tree-ellipsistreeiter}) iterator.

These attributes are ignored if any of the following attributes are
present; \texttt{prevpage}, or \texttt{nextpage}
(\ref{tag-input-page}).

An attribute value must be supplied that specifies the name of the
\class{LazyTreeIterator} iterator.

The \texttt{name} (\ref{tag-input-name}) attribute is generated as
follows:

\verbatiminput{doctest/tags-input-treeselect}

When merging the browser request the
\method{NamespaceMixin.set_value()} (\ref{mixin-namespace}) method
looks for field names that contain commas.  These names are split into
\emph{operation}, \emph{iterator}, and optional \emph{value} then the
\method{set_backdoor()} method of the identified iterator is invoked.

During request merging the above example will execute code equivalent
to the following.

\begin{verbatim}
ctx.locals.n.set_backdoor('treeselect', 'ino81489', 'treeselect,n,ino81489')
\end{verbatim}

The ``ino81489'' string is generated by calling the
\method{albatross_alias()} method for the tree node.

If the \texttt{node}(\ref{tag-input-node}) attribute is not specified,
the node referenced by the current value of the iterator will be used
to determine the alias.

\subsubsection{\texttt{value="..."} attribute\label{tag-input-value}}

When determining the generated \texttt{value} attribute the tag looks
for a number of attributes.  Any supplied \texttt{value} attribute
will be ignored if either \texttt{expr} (\ref{tag-input-expr}) or
\texttt{valueexpr} (\ref{tag-input-valueexpr}) attributes (depending
upon input type) present.

If no \texttt{expr}, \texttt{valueexpr}, or \texttt{value} attribute
is present then the value identified by the generated \texttt{name}
(\ref{tag-input-name}) attribute will be taken from the local
namespace.  If this value is \code{None} then no \texttt{value}
attribute will be written.  The name used to look into the local
namespace is the result of evaluating all \texttt{name} related
attributes.

For input field types \texttt{radio} and \texttt{checkbox} the
\texttt{valueexpr} attribute if present takes priority over and
specified \texttt{value} attribute.

Refer to the documentation for individual input types for more
details.

\subsubsection{\texttt{valueexpr="..."} attribute\label{tag-input-valueexpr}}

This attribute is used to generate a \texttt{value}
(\ref{tag-input-value}) attribute for \texttt{radio} and
\texttt{checkbox} input field types.  It is ignored for in all other
cases.

Refer to the documentation for individual input types for more
details.

\subsubsection{\texttt{type="..."} attribute (text, password, submit, reset, hidden, button)\label{tag-input-generic}}

The tag determines the generated \texttt{name} (\ref{tag-input-name})
from the \texttt{name} related attributes.

To determine the generated \texttt{value} (\ref{tag-input-value})
attribute the tag first looks for an \texttt{expr}
(\ref{tag-input-expr}) attribute, then a \texttt{value} attribute, and
then if that fails it looks up the generated \texttt{name} in the
execution context.

If the generated \texttt{name} contains a non-empty value it will be
written as the \texttt{name} attribute.  If the generated
\texttt{value} is not \code{None} it will be escaped and written as
the \texttt{value} attribute.  Escaping values makes all \texttt{\&},
\texttt{<}, \texttt{>}, and \texttt{"} characters safe.

For example:

\verbatiminput{doctest/tags-input-generic}

After writing all tag attributes the execution context
\method{input_add()} method is called with the following arguments;
input field type (\code{'text'}, \code{'password}, \code{'submit},
\code{'reset}, \code{'hidden}, or \code{'button'}), the generated
\texttt{name}, the generated \texttt{value}, and a flag indicating
whether or not the \texttt{list} (\ref{tag-input-list}) attribute was
present.

Application code handling browser requests typically determines the
\texttt{submit} input pressed by the user via the execution context
\method{req_equals()} method.  The \method{req_equals()} method simply
tests that the named input is present in the browser request and
contains a non-empty value.

For example:

\begin{verbatim}
def page_process(ctx):
    if ctx.req_equals('login'):
        user = process_login(ctx.locals.username, ctx.locals.passwd)
        if user:
            ctx.locals._user = user
            ctx.add_session_vars('_user')
            ctx.set_page('home')
\end{verbatim}

\subsubsection{\texttt{type="..."} attribute (radio)\label{tag-input-radio}}

The tag determines the generated \texttt{name} (\ref{tag-input-name})
from the \texttt{name} related attributes.  Then an internal
comparison value is determined by evaluating the \texttt{expr}
(\ref{tag-input-expr}) attribute if it is present, or by looking up
the generated \texttt{name} in the execution context.

If the comparison value equals the generated \texttt{value}
(\ref{tag-input-value}) attribute then the \texttt{checked}
(\ref{tag-input-checked}) attribute is written.  Both values are
converted to string before being compared.

To determine the generated \texttt{value} attribute the tag first
looks for a \texttt{valueexpr} (\ref{tag-input-valueexpr}) attribute,
then a \texttt{value} attribute.

For example:

\verbatiminput{doctest/tags-input-radio1}

The \texttt{expr} attribute can be used to generate the internal
comparison value.  This is then compared with the \texttt{value}
attribute to control the state of the \texttt{checked} attribute.

For example:

\verbatiminput{doctest/tags-input-radio2}

The \texttt{valueexpr} attribute can be used to dynamically generate
the \texttt{value} attribute.

For example:

\verbatiminput{doctest/tags-input-radio3}

After writing all tag attributes the execution context
\method{input_add()} method is called with the arguments; input field
type (\code{'radio'}), the generated \texttt{name}, the generated
\texttt{value}, and a flag indicating whether or not the \texttt{list}
(\ref{tag-input-list}) attribute was present.

\subsubsection{\texttt{type="..."} attribute (checkbox)\label{tag-input-checkbox}}

The tag determines the generated \texttt{name} (\ref{tag-input-name})
from the \texttt{name} related attributes.  Then an internal
comparison value is determined by evaluating the \texttt{expr}
(\ref{tag-input-expr}) attribute if it is present, or by looking up
the generated \texttt{name} in the execution context.

If the comparison value equals the generated \texttt{value}
(\ref{tag-input-value}) attribute then the \texttt{checked}
(\ref{tag-input-checked}) attribute is written.  Both values are
converted to string before being compared.

If the internal comparison value is either a list or tuple the
\texttt{checked} attribute is written if the generated \texttt{value}
attribute is present in the list/tuple.

To determine the generated \texttt{value} attribute the tag first
looks for a \texttt{valueexpr} (\ref{tag-input-valueexpr}) attribute,
then a \texttt{value} attribute, and then if that fails it defaults to
the value \texttt{'on'}.

For example:

\verbatiminput{doctest/tags-input-checkbox}


After writing all tag attributes the execution context
\method{input_add()} method is called with the arguments; input field
type (\code{'checkbox'}), the generated \texttt{name}, the generated
\texttt{value}, and a flag indicating whether or not the \texttt{list}
(\ref{tag-input-list}) attribute was present.

\subsubsection{\texttt{type="..."} attribute (image)\label{tag-input-image}}

The tag determines the generated \texttt{name} (\ref{tag-input-name})
from the \texttt{name} related attributes.

For example:

\verbatiminput{doctest/tags-input-image}

After writing all tag attributes the execution context
\method{input_add()} method is called with the arguments; input field
type (\code{'image'}), the generated \texttt{name}, \code{None}, and a
flag indicating whether or not the \texttt{list}
(\ref{tag-input-list}) attribute was present.

When a browser submits input to an \texttt{image} input it sends an
\code{x} and \code{y} value for the field.  Application code should
check for either of these when checking if the user clicked the image.

For example, if an image input named \texttt{map} was clicked by the
user, then the code to detect the input would look something like
this:

\begin{verbatim}
def page_process(ctx):
    if ctx.req_equals('map.x'):
        map_clicked_at(ctx.locals.map.x, ctx.locals.map.y)
\end{verbatim}

\subsubsection{\texttt{type="..."} attribute (file)\label{tag-input-file}}

The tag determines the generated \texttt{name} (\ref{tag-input-name})
from the \texttt{name} related attributes.

If you are using an execution context that inherits from the
\class{NameRecorderMixin} (\ref{mixin-recorder}) then using this input
field type will automatically cause the enclosing \texttt{<al-form>}
(\ref{tag-form}) tag to include an
\texttt{enctype="multipart/form-data"} (\ref{tag-form-enctype})
attribute.

For example:

\verbatiminput{doctest/tags-input-file}

After writing all tag attributes the execution context
\method{input_add()} method is called with the arguments; input field
type (\code{'file'}), the generated \texttt{name}, \code{None}, and
a flag indicating whether or not the \texttt{list}
(\ref{tag-input-list}) attribute was present.

The request merging allows the user to submit more than one file in a
\texttt{file} input field.  To simplify application code the
\class{Request} always returns a list of \class{FileField} objects for
\texttt{file} inputs.

Application code to process \texttt{file} inputs typically looks like
the following:

\begin{verbatim}
def page_process(ctx):
    if ctx.req_equals('resume'):
        for r in ctx.locals.resume:
            if r.filename:
                save_uploaded_resume(r.filename, r.file.read())
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-select>

\subsection{\texttt{<al-select>}\label{tag-select}}

Albatross browser request merging depends upon the functionality
provided by the \texttt{<al-select>} tag.  If you do no use this tag
in applications then the standard request merging will not work.

To determine the \texttt{name} (\ref{tag-select-name}) attribute in
the generated tag a number of attributes are used.  The generated name
is evaluated in the execution context to determine an internal compare
value.

The compare value is used to control which option tags are generated
with the \texttt{selected} (\ref{tag-option-selected}) attribute.
\texttt{<select>} tags in multi-select mode are supported by list or
tuple compare values.

The \texttt{<al-select>} tag can automatically generate the list of
enclosed \texttt{<option>} tags using the \texttt{optionexpr}
(\ref{tag-select-optionexpr}) attribute, or can work with enclosed
\texttt{<al-option>} (\ref{tag-option}) tags.

\subsubsection{\texttt{alias="..."} attribute\label{tag-select-alias}}

The value of the \texttt{alias} attribute is passed to the
\method{make_alias()} method of the execution context.  The return
value is then used as the generated \texttt{name}
(\ref{tag-select-name}) attribute.

The execution context \method{make_alias()} method splits the
\texttt{alias} attribute at the last '.' and resolves the left hand
side to an object reference.  The \method{albatross_alias()} method is
then called on that object and the result is combined with the '.'
and the right hand side of the of the \texttt{alias} attribute to
produce the generated \texttt{name} attribute.  The resolved object is
entered in the the local namespace and the session using the name
returned by the \method{albatross_alias()} method.

Refer to the documentation of the \texttt{alias} attribute of the
\texttt{<al-input>} tag (\ref{tag-input-alias}) for an example of the
mechanism described above.

\subsubsection{\texttt{list} attribute\label{tag-select-list}}

If you are using an execution context that inherits from the
\class{NameRecorderMixin} (nearly all do --- see chapter
\ref{pack-overview}) then the execution context will raise a
\exception{ApplicationError} exception if multiple instances of a
non-multi-select \texttt{<al-select>} tag with the same name are added
to a form.  The \texttt{list} attribute is used indicate that multiple
instances are intentional.

The presence of the \texttt{list} attribute on an \texttt{<al-select>}
tag makes the request merging in the \class{NameRecorderMixin} class
place any browser request values for the field into a list (field not
present is represented by the empty list).

\subsubsection{\texttt{multiple} attribute\label{tag-select-multiple}}

For the purposes of the \class{NameRecorderMixin} class, this
attribute performs the same role as the \texttt{list}
(\ref{tag-select-list}) attribute.  It tells the browser request
merging to place all input values into a list (field not present is
represented by the empty list).

\subsubsection{\texttt{name="..."} attribute\label{tag-select-name}}

When determining the generated \texttt{name} attribute the tag looks
for a number of attributes.  Any supplied \texttt{name} attribute will
be ignored if either the \texttt{alias} (\ref{tag-select-alias}) or
\texttt{nameexpr} (\ref{tag-select-nameexpr}) attributes are present.

\subsubsection{\texttt{nameexpr="..."} attribute\label{tag-select-nameexpr}}

This attribute is ignored if the \texttt{alias}
(\ref{tag-select-alias}) attribute is present.

The expression in the value of the \texttt{nameexpr} attribute is
evaluated to determine the generated \texttt{name}
(\ref{tag-select-name}) attribute.

One shortcoming of the \texttt{alias} attribute is that you can only
perform input on object attributes.  The \texttt{nameexpr} enables you
to perform input on list elements.

Refer to the documentation of the \texttt{nameexpr} attribute of the
\texttt{<al-input>} tag (\ref{tag-input-nameexpr}) for an example.

\subsubsection{\texttt{noescape} attribute\label{tag-select-noescape}}

The \texttt{noescape} attribute is used with the \texttt{optionexpr}
(\ref{tag-select-optionexpr}) attribute to suppress escaping of each
option value returned by the expression.

\subsubsection{\texttt{optionexpr="..."} attribute\label{tag-select-optionexpr}}
If this attribute is present the expression in the attribute value is
evaluated to determine a sequence of option values.  One
\texttt{<option>} tag is generated for each item in the sequence.

When this attribute is not present all of the directly enclosed
\texttt{<al-option>} (\ref{tag-option}) tags are processed to generate
the enclosed \texttt{<option>} tags.

If an item in the \texttt{optionexpr} sequence is not a tuple, it is
converted to string and then compared with the comparison value
derived from the \texttt{name} (\ref{tag-select-name}) attribute.

To support multiple selected \texttt{<option>} tags the comparison
value must be either a list or tuple.

For example:

\verbatiminput{doctest/tags-input-select3}

If an item in the \texttt{optionexpr} sequence is a tuple it must
contain two values.  The first value is used to specify the
\texttt{value} attribute of the generated \texttt{<option>} tag and
the second value provides the \texttt{<option>} tag content.

For example:

\verbatiminput{doctest/tags-input-select4}

All values generated by the \texttt{optionexpr} method are escaped to
make all \texttt{\&}, \texttt{<}, \texttt{>}, and \texttt{"}
characters safe.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-option>

\subsection{\texttt{<al-option>}\label{tag-option}}

Albatross browser request merging depends upon the functionality
provided by the \texttt{<al-option>} tag.  If you do no use this tag
in applications then the standard request merging will not work.

Currently \texttt{<al-option>} tags must be immediate children of the
enclosing \texttt{<al-select>} (\ref{tag-select}) tag otherwise they
are ignored.  The following illustrates the limitation.

\verbatiminput{doctest/tags-input-select5}

\subsubsection{\texttt{selected} attribute\label{tag-option-selected}}

When generating the \texttt{<option>} tag the presence of a
\texttt{selected} attribute is controlled by the comparison value from
the enclosing \texttt{<al-select>} (\ref{tag-select}) tag.  The
comparison value is compared with the value of the
\texttt{<al-option>} tag.

The value of the \texttt{<al-option>} tag is specified either in a
\texttt{value} (\ref{tag-option-value}) attribute, or if that
attribute is not present, by the content enclosed by the
\texttt{<al-option>} tag.  The enclosed content of the tag is
evaluated before it is compared.  This allows the content to be
generated using other Albatross tags.

For example --- this shows how the \texttt{<al-option>} content is
evaluated before it is compared with the \texttt{<al-select>} value:

\verbatiminput{doctest/tags-input-select1}

\subsubsection{\texttt{value="..."} attribute\label{tag-option-value}}

Use the \texttt{value} attribute to specify a value to be compared
with the comparison value of the enclosing \texttt{<al-select>}
(\ref{tag-select}) tag.

\verbatiminput{doctest/tags-input-select2}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-textarea>

\subsection{\texttt{<al-textarea>}\label{tag-textarea}}

Albatross browser request merging depends upon the functionality
provided by the \texttt{<al-textarea>} tag.  If you do no use this tag
in applications then the standard request merging will not work.

\subsubsection{\texttt{alias="..."} attribute\label{tag-textarea-alias}}

The value of the \texttt{alias} attribute is passed to the
\method{make_alias()} method of the execution context.  The return
value is then used as the generated \texttt{name}
(\ref{tag-textarea-name}) attribute.

The execution context \method{make_alias()} method splits the
\texttt{alias} attribute at the last '.' and resolves the left hand
side to an object reference.  The \method{albatross_alias()} method is
then called on that object and the result is combined with the '.'
and the right hand side of the of the \texttt{alias} attribute to
produce the generated \texttt{name} attribute.  The resolved object is
entered in the the local namespace and the session using the name
returned by the \method{albatross_alias()} method.

Refer to the documentation of the \texttt{alias} attribute of the
\texttt{<al-input>} tag (\ref{tag-input-alias}) for an example of the
mechanism described above.

\subsubsection{\texttt{list} attribute\label{tag-textarea-list}}

If you are using an execution context that inherits from the
\class{NameRecorderMixin} (nearly all do --- see chapter
\ref{pack-overview}) then the execution context will raise a
\exception{ApplicationError} exception if multiple instances of an
\texttt{<al-textarea>} tag with the same name are added to a form.
The \texttt{list} attribute is used indicate that multiple instances
are intentional.

The presence of the \texttt{list} attribute on an
\texttt{<al-textarea>} tag makes the request merging in the
\class{NameRecorderMixin} class place any browser request values for
the field into a list (field not present is represented by the empty
list).

\subsubsection{\texttt{name="..."} attribute\label{tag-textarea-name}}

When determining the generated \texttt{name} attribute the tag looks
for a number of attributes.  Any supplied \texttt{name} attribute will
be ignored if either the \texttt{alias} (\ref{tag-textarea-alias}) or
\texttt{nameexpr} (\ref{tag-textarea-nameexpr}) attributes are
present.

If the value identified by the generated \texttt{name} attribute does
not exist in the execution context then the enclosed content will be
supplied as the initial tag value.

For example:

\verbatiminput{doctest/tags-textarea1}

Before the tag value is written it is escaped to make all \texttt{\&},
\texttt{<}, \texttt{>}, and \texttt{"} characters safe.

\subsubsection{\texttt{nameexpr="..."} attribute\label{tag-textarea-nameexpr}}

This attribute is ignored if the \texttt{alias}
(\ref{tag-textarea-alias}) attribute is present.

The expression in the value of the \texttt{nameexpr} attribute is
evaluated to determine the generated \texttt{name}
(\ref{tag-textarea-name}) attribute.

One shortcoming of the \texttt{alias} attribute is that you can only
perform input on object attributes.  The \texttt{nameexpr} enables you
to perform input on list elements.

Refer to the documentation of the \texttt{nameexpr} attribute of the
\texttt{<al-input>} tag (\ref{tag-input-nameexpr}) for an example.

\subsubsection{\texttt{noescape} attribute\label{tag-textarea-noescape}}

The \texttt{noescape} attribute is used to suppress escaping of the
execution context value associated with the \texttt{name}
(\ref{tag-textarea-name}) attribute.

\verbatiminput{doctest/tags-textarea2}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-a>

\subsection{\texttt{<al-a>}\label{tag-a}}

This tag acts as an enhanced version of the standard HTML \texttt{<a>}
tag.

\subsubsection{\texttt{expr="..."} attributes\label{tag-a-expr}}

This attribute is ignored is any of the following attributes are
present; \texttt{prevpage}, \texttt{nextpage} (\ref{tag-a-page}),
\texttt{treefold}, \texttt{treeselect}, or \texttt{treeellipsis}
(\ref{tag-a-tree}).

The specified expression is evaluated to generate an \texttt{href}
(\ref{tag-a-href}) attribute.  The generated attribute is then
processed as per the \texttt{href} attribute.

\subsubsection{\texttt{href="..."} attributes\label{tag-a-href}}

This attribute is ignored is any of the following attributes are
present; \texttt{prevpage}, \texttt{nextpage} (\ref{tag-a-page}),
\texttt{treefold}, \texttt{treeselect}, \texttt{treeellipsis}
(\ref{tag-a-tree}), or \texttt{expr} (\ref{tag-a-expr}).

When the \texttt{expr} attribute is used, then generated value is
processed in the same as a value supplied in the \texttt{href}
attribute.

If the \texttt{href} does not contain a '?' (separates the path from
the query), but does contain a '=' then the \texttt{href} is rewritten
as \emph{current_url}?\emph{href}.

\verbatiminput{doctest/tags-a2}

If the \texttt{href} does not contain either a '?' or a '=' then the
\texttt{href} is assumed to be a page identifier so it is transformed
into a redirect url by the \method{redirect_url()} execution context
method.

\verbatiminput{doctest/tags-a3}

\subsubsection{\texttt{node="..."} attribute\label{tag-a-node}}

The \texttt{node} attribute is used in conjunction with the
\texttt{treeselect}, \texttt{treefold} and \texttt{treeellipsis}
(\ref{tag-a-tree}) attributes.  It is ignored otherwise.

When this attribute is present the node identified by evaluating the
expression in the attribute value will be used when generating the
\texttt{href} (\ref{tag-a-href}) attribute.

\subsubsection{\texttt{prevpage="..."} and \texttt{nextpage="..."} attributes\label{tag-a-page}}

The \texttt{prevpage} and \texttt{nextpage} attributes generate an
\texttt{href} (\ref{tag-a-href}) attribute that respectively selects
the previous and next pages of an \texttt{<al-for>}
\class{ListIterator} (\ref{tag-for-listiter}).

The attribute value specifies the name of the iterator.

The generated \texttt{href} attribute is of the form
\emph{current_url}?\emph{name},\emph{iter}=1 where \emph{current_url}
is the path component returned from the Python
\function{urlparse.urlparse()} function (via the execution context
\method{current_url()} method), \emph{name} is either
\texttt{prevpage} or \texttt{nextpage}, and \emph{iter} is the
specified iterator.

For example:

\verbatiminput{doctest/tags-a1}

\subsubsection{\texttt{treeselect="..."}, \texttt{treefold="..."} and \texttt{treeellipsis="..."} attributes\label{tag-a-tree}}

These attributes are ignored if any either the \texttt{prevpage}
(\ref{tag-a-page}), or \texttt{nextpage} attributes are present.

The \texttt{treeselect}, \texttt{treefold}, and \texttt{treeellipsis}
attributes generate an \texttt{href} (\ref{tag-a-href}) attribute that
respectively select, open/close, or expand the ellipsis of an
\texttt{<al-tree>} (\ref{tag-tree}) node via a
\class{LazyTreeIterator} (\ref{tag-tree-lazytreeiter}) or
\class{EllipsisTreeIterator} (\ref{tag-tree-ellipsistreeiter})
iterator.

Refer to the \texttt{<al-input>} tag for more information on how to
use these attributes (\ref{tag-input-tree}).

If the \texttt{node} (\ref{tag-a-node}) attribute if it is present it
defines the node to operate upon.  Otherwise the node operated upon is
the current value of the \class{LazyTreeIterator} iterator.

The attribute value specifies the name of the \class{LazyTreeIterator}
iterator.

The generated \texttt{href} attribute is of the form
\emph{current_url}?\emph{name},\emph{iter},\emph{alias}=1 where
\emph{current_url} is the path component returned from the Python
\function{urlparse.urlparse()} function (via the execution context
\method{current_url()} method), \emph{name} is either
\texttt{treeselect}, \texttt{treefold} or \texttt{treeellipsis},
\emph{iter} is the specified iterator, and \emph{alias} is the values
returned by the \method{albatross_alias()} method of the specified
node.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-img>

\subsection{\texttt{<al-img>}\label{tag-img}}

Use this tag to dynamically generate the \texttt{src}
(\ref{tag-img-src}) attribute of an \texttt{<img>} tag.

\subsubsection{\texttt{expr="..."} attribute\label{tag-img-expr}}

You must supply an \texttt{expr} attribute containing an expression
that is evaluated to generate the output \texttt{src}
(\ref{tag-img-src}) attribute of the \texttt{<img>} tag.

For example:

\verbatiminput{doctest/tags-img}

\subsubsection{\texttt{noescape} attribute\label{tag-img-noescape}}

The \texttt{noescape} attribute can be used to suppress escaping of
the \texttt{src} (\ref{tag-img-src}) attribute.

\verbatiminput{doctest/tags-img-noescape}

\subsubsection{\texttt{src="..."} attribute\label{tag-img-src}}

This attribute is ignored.  Use the \texttt{expr} (\ref{tag-img-expr})
attribute to generate the \texttt{<src>} attribute.

\section{Execution and Control Flow\label{tag-execflow}}

Tags in this section provide just enough programming capability to
allow template files to react to and format values from the execution
context.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-include>

\subsection{\texttt{<al-include>}\label{tag-include}}

Use this tag to load and execute another template file at the current
location.  You can specify the name of the included template file by
name using the \texttt{name} (\ref{tag-include-name}) attribute or by
expression using the \texttt{expr} (\ref{tag-include-expr}) attribute.

\subsubsection{\texttt{expr="..."} attribute\label{tag-include-expr}}

If the \texttt{expr} attribute is present it is evaluated when the
template is executed to generate the name of a template file.  The
specified template file is loaded and executed with the output
replacing the \texttt{<al-include>} tag.

For example:

\verbatiminput{doctest/tags-include1}

\subsubsection{\texttt{name="..."} attribute\label{tag-include-name}}

This attribute is ignored if the \texttt{expr} attribute is present.

When the template is executed the specified template file is loaded
and executed with the output replacing the \texttt{<al-include>} tag.

For example:

\verbatiminput{doctest/tags-include2}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-comment>

\subsection{\texttt{<al-comment>}\label{tag-comment}}

This tag suppresses the execution and output of any contained content,
although the contained content must be syntactically correct.

For example:

\verbatiminput{doctest/tags-comment}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-flush>

\subsection{\texttt{<al-flush>}\label{tag-flush}}

When the template file interpreter encounters an \texttt{<al-flush>}
during execution it flushes all accumulated HTML to output.

Usually HTML is accumulated in the execution context and is not sent
to the output until the \method{flush_content()} is called.  This
gives programs the opportunity to handle exceptions encountered during
template execution without partial output leaking to the browser.

When the program is performing an operation that runs for some time
this behaviour may give user the impression that the application has
entered an infinite loop.  In these cases it is usually a good idea to
provide incremental feedback to the user by placing
\texttt{<al-flush>} tags in your template files.

\verbatiminput{doctest/tags-flush}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-if>

\subsection{\texttt{<al-if>}/\texttt{<al-elif>}/\texttt{<al-else>}\label{tag-if}}

Use of these tags parallels the
\keyword{if}/\keyword{elif}/\keyword{else} keywords in Python.

The \texttt{<al-if>} tag is a content enclosing tag while
\texttt{<al-elif>} and \texttt{<al-else>} are empty tags that
partition the content of the enclosing \texttt{<al-if>} tag.

\subsubsection{\texttt{expr="..."} attribute\label{tag-if-expr}}

The \texttt{expr} attribute is used in the \texttt{<al-if>} and
\texttt{<al-elif>} tags to specify a test expression.  The expression
is evaluated when the template is executed.

If the text expression in the \texttt{expr} attribute of the
\texttt{<al-if>} tag evaluates to a \code{TRUE} value then the
enclosed content up to either the next \texttt{<al-elif>} or
\texttt{<al-else>} tag will be executed.

For example:

\verbatiminput{doctest/tags-if1}

If the expression in the \texttt{expr} attribute of the
\texttt{<al-if>} tag evaluates \code{FALSE} then the enclosed content
following the \texttt{<al-else>} tag is executed.

For example:

\verbatiminput{doctest/tags-if2}

The \texttt{<al-elif>} tag is used to chain a number of expression
that are tested in sequence.  The first test that evaluates
\code{TRUE} determines the content that is executed.

For example:

\verbatiminput{doctest/tags-if3}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-value>

\subsection{\texttt{<al-value>}\label{tag-value}}

This tag allows you to evaluate simple expressions and write the
result to output.

\subsubsection{\texttt{date="..."} attribute\label{tag-value-date}}

If a \texttt{date} attribute is specified then the enclosed format
string is passed to the Python \function{time.strftime()} function
along with the result of the expression in the \texttt{expr}
(\ref{tag-value-expr}) attribute.  The result of
\function{time.strftime()} is then written to the output.

For example:

\verbatiminput{doctest/tags-value3}

\subsubsection{\texttt{expr="..."} attribute\label{tag-value-expr}}

This attribute must the specified.  It contains an expression that is
evaluated when the template is executed and the result is written as a
string to the output.

For example:

\verbatiminput{doctest/tags-value1}

\subsubsection{\texttt{lookup="..."} attribute\label{tag-value-lookup}}

When the \texttt{lookup} attribute is specified the result of the
expression in the \texttt{expr} (\ref{tag-value-expr}) attribute is
used to retrieve content from the lookup table named in the
\texttt{lookup} attribute.  This is a very useful way to separate the
internal representation of program value from the presentation of that
value.

For example:

\verbatiminput{doctest/tags-value4}

Please refer to the \texttt{<al-lookup>} tag reference for an
explanation that tag and more complex examples.

\subsubsection{\texttt{noescape} attribute\label{tag-value-noescape}}

If the \texttt{noescape} attribute is present then the value is not
escaped.  Only use this attribute when you are sure that the result of
the expression is safe.  Without this attribute all \texttt{\&},
\texttt{<}, \texttt{>}, and \texttt{"} are escaped.

For example:

\verbatiminput{doctest/tags-value2}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-exec>

\subsection{\texttt{<al-exec>}\label{tag-exec}}

This tag allows you to place arbitrary Python code in a template file.

\subsubsection{\texttt{expr="..."} attribute\label{tag-exec-expr}}

The expression is specified in the \texttt{expr} attribute.  It is
compiled using \var{kind}\code{~=~'exec'} and evaluated when the
template is executed.

For example:

\verbatiminput{doctest/tags-exec1}

If you need to include the same quote character used to enclose the
attribute value in your expression you can escape it using a backslash
(``$\backslash$'').

For example:

\verbatiminput{doctest/tags-exec2}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-for>

\subsection{\texttt{<al-for>}\label{tag-for}}

This tag implements a loop in almost the same way as the \keyword{for}
keyword in Python.

The tag uses an instance of the \class{ListIterator}
(\ref{tag-for-listiter}) identified in the local namespace by the
\texttt{iter} (\ref{tag-for-iter}) attribute to iterate over the
sequence defined by the expression in the \texttt{expr}
(\ref{tag-for-expr}) attribute.

\verbatiminput{doctest/tags-for1}

Note that you must use the \method{value()} method of the iterator to
retrieve the current sequence value.

When using pagination mode via the \texttt{pagesize}
(\ref{tag-for-pagesize}) attribute the \texttt{prevpage} and
\texttt{nextpage} attributes of the \texttt{<al-input>}
(\ref{tag-input}) and \texttt{<al-a>} (\ref{tag-a}) tags can be used
to automatically page forwards and backwards through a sequence.

The following simulates pagination via the \method{set_backdoor()}
\class{ListIterator} method and shows other data that is maintained by
the iterator.

\verbatiminput{doctest/tags-for7}

\subsubsection{\texttt{cols="..."} attribute\label{tag-for-cols}}

This attribute is used to format a sequence as multiple columns.  The
attribute value is an integer that specifies the number of columns.

Rather than evaluate the enclosed content once for each item in the
sequence, the tag evaludates the content for each \emph{row of items}
in the sequence.  The items in each row can be formatted by using an
inner \texttt{<al-for>} tag.

By default the items flow down columns.  To flow across columns you
must use the \texttt{flow} (\ref{tag-for-flow})

For example:

\verbatiminput{doctest/tags-for5}

Multi-column formatting does not support pagination.

\subsubsection{\texttt{continue} attribute\label{tag-for-continue}}

When paginating items via the \texttt{pagesize}
(\ref{tag-for-pagesize}) attribute, the iterator index will reset to
the first index displayed on the page if you use an iterator more than
once on the page.  The \texttt{continue} attribute suppresses the
sequence index reset causing the elements to flow on from the previous
page.

For example:

\verbatiminput{doctest/tags-for3}

\subsubsection{\texttt{expr="..."} attribute\label{tag-for-expr}}

The \texttt{expr} attribute specifies an expression that yields a
sequence that the iterator specified in the \texttt{iter}
(\ref{tag-for-iter}) attribute will iterate over.  All of the enclosed
content is then evaluated for each element in the sequence.

For example:

\verbatiminput{doctest/tags-for1}

\subsubsection{\texttt{flow="..."} attribute\label{tag-for-flow}}

This attribute is used with the \texttt{cols} (\ref{tag-for-cols})
attribute to control the flow of values across columns.  The default
value is \texttt{"down"}.  Use the value \texttt{"across"} to flow
items across columns.

Rather than evaluate the enclosed content once for each item in the
sequence, the tag evaludates the content for each \emph{row of items}
in the sequence.  The items in each row can be formatted by using an
inner \texttt{<al-for>} tag.

For example:

\verbatiminput{doctest/tags-for6}

Multi-column formatting does not support pagination.

\subsubsection{\texttt{iter="..."} attribute\label{tag-for-iter}}

This attribute specifies the name of the \class{ListIterator}
(\ref{tag-for-listiter}) that will be used to iterate over the items
in the sequence defined by the expression in the \texttt{expr}
(\ref{tag-for-expr}) attribute.

\subsubsection{\texttt{pagesize="..."} attribute\label{tag-for-pagesize}}

This attribute is used to present a sequence of data one page at a
time.  The attribute value must be an integer that specifies the
number of items to display in each page.

Use of the \texttt{pagesize} attribute places the sequence iterator
into page mode and limits the number of elements that will be
displayed.

For example:

\verbatiminput{doctest/tags-for2}

Pagination support requires that session support be present in the
execution context.  All of the Albatross application objects provide
session capable execution contexts by default.  The
\class{SimpleContext} class does not support sessions so it is
necessary to augment the class for the above example.  Note also that
when the \texttt{<al-for>} tag processes the \texttt{pagesize}
attribute it places the sequence iterator into the session.

\subsubsection{\texttt{prepare} attribute\label{tag-for-prepare}}

This attribute allows you to place pagination controls before the
formatted sequence content.

When the \texttt{prepare} attribute is present the \texttt{<al-for>}
tag will perform all processing but will not write any output.  This
allows you to test pagination results before presenting output.

For example:

\verbatiminput{doctest/tags-for4}

Note the XML empty tag syntax on the \texttt{<al-for~prepare>} tag.

\subsubsection{ListIterator Objects\label{tag-for-listiter}}

The iterator named in the \texttt{iter} (\ref{tag-for-iter}) attribute
of the \texttt{<al-for>} tag is an instance of this class.  By using
an object to iterate over the sequence the toolkit is able to provide
additional data that is useful in formatting HTML.

The iterator will retrieve each value from the sequence exactly once.
This allows you to use objects that act as sequences by implementing
the Python sequence protocol.  Only \method{__getitem__()} is required
unless you use pagination, then \method{__len__()} is also required.

\begin{methoddesc}[ListIterator]{pagesize}{}
Returns the pagesize that was set in the \texttt{pagesize} attribute.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{has_prevpage}{}
Returns \code{TRUE} if the page \member{start} index is greater than
zero indicating that there is a previous page.  
\end{methoddesc}

\begin{methoddesc}[ListIterator]{has_nextpage}{}
Returns \code{TRUE} if the sequence length is greater than the page
\member{start} index plus the \member{_pagesize} member indicating
that there is a next page.

If the iterator has not been placed into ``page mode'' by the presence
of a \texttt{pagesize} attribute a \class{ListIteratorError} exception
will be raised.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{index}{}
Returns the index of the current sequence element.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{start}{}
Returns the index of the first sequence element on the page.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{count}{}
Returns the index of the current sequence element within the current
page.  This is equivalent to \code{index()~-~start()}.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{value}{}
Returns the current sequence element.
\end{methoddesc}

Most of the methods and all of the members are not meant to be
accessed from your code but are documented below to help clarify how
the iterator behaves.

\begin{memberdescni}[ListIterator]{_index}
Current sequence index --- returned by \member{index()}.
\end{memberdescni}

\begin{memberdescni}[ListIterator]{_start}
Sequence index of first element on page --- returned by
\member{start()}.
\end{memberdescni}

\begin{memberdescni}[ListIterator]{_count}
Sequence index of current element on page --- returned by
\member{count()}.
\end{memberdescni}

\begin{memberdescni}[ListIterator]{_seq}
Sequence being iterated over --- initialised to \code{None} and set by
\method{set_sequence()}.
\end{memberdescni}

\begin{memberdescni}[ListIterator]{_have_value}
Indicates the state of the current element.  There are three possible
values: \code{None} indicates that the state is unknown and will be
established when the sequence is next accessed, zero indicates that
the end of sequence has been reached and there is no valid element,
and one indicates the current element is valid.
\end{memberdescni}

\begin{memberdescni}[ListIterator]{_pagesize}
Current page size --- initialised to \code{0} and set by the presence
of a \texttt{pagesize} attribute in the \texttt{<al-for>} tag.
\end{memberdescni}

\begin{methoddesc}[ListIterator]{__getstate__}{}
When ``page mode'' is enabled the iterator is saved into the session
(via the execution context \method{add_session_vars()} method).  This
restricts the Python pickler to saving only the \member{_start} and
\member{_pagesize} members.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{__setstate__}{tup}
Restores an iterator from the Python pickler.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{__len__}{}
When in ``page mode'' it returns the \member{_pagesize} member else it
returns the length of the sequence.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{set_backdoor}{op, value}
The \texttt{<al-input>} and \texttt{<al-a>} tags provide
\texttt{nextpage} and \texttt{prevpage} attributes that generate
names using a special backdoor format.  When the browser request is
merged the \method{set_value()} method of the \class{NamespaceMixin}
directs list backdoor input fields to this method.  Refer to the
documentation in section \ref{mixin-namespace}.

The \var{value} argument is the browser submitted value for the
backdoor field.  If a value was submitted for the backdoor field then
the \var{op} argument is processed.  If \var{op} equals
\code{"prevpage"} or \code{"nextpage"} then the iterator selects
the previous or next page respectively.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{get_backdoor}{op}
When generating backdoor fields for the \texttt{<al-input>} and
\texttt{<al-a>} tags the toolkit calls this method to determine the
value that will assigned to that field.  The method returns \code{1}.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{set_pagesize}{size}
Sets the \member{_pagesize} member to \var{size}.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{has_sequence}{}
Returns whether or not a sequence has been placed into the iterator
(\member{_seq} is not \code{None}).
\end{methoddesc}

\begin{methoddesc}[ListIterator]{set_sequence}{seq}
Sets the \member{_seq} to \var{seq}.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{reset_index}{}
If the \texttt{<al-for>} tag does not contain a \texttt{continue}
attribute then this is called just before executing the tag content
for the first element in the sequence.  It sets the \member{_index}
member to \member{_start}.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{reset_count}{}
This is called just before executing the tag content for the first
element in the sequence.  It sets the \member{_count} member to zero.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{clear_value}{}
Sets the \member{_have_value} member to \code{None} which causes the
next call of \member{has_value()} to retrieve the sequence element
indexed by \member{_index}.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{has_value}{}
When the \member{_have_value} member is \code{None} this method tries
to retrieve the sequence element indexed by \member{_index}.  If an
element is returned by the sequence it is saved in the \member{_value}
member and \member{_have_value} is set to one.  If an
\exception{IndexError} exception is raised by the sequence then
\member{_have_value} is set to zero.

The method returns TRUE if a sequence member is contained in
\member{_value}.

By this mechanism the iterator retrieves each value from the sequence
exactly once.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{next}{}
Retrieves the next value (if available) from the sequence into the
\member{_value} member.
\end{methoddesc}

\begin{methoddesc}[ListIterator]{set_value}{value}
A back door hack for multi-column output that sets respective values
of the iterator to sequences created by slicing the sequence in the
\texttt{expr} attribute of the \texttt{<al-for>} tag.
\end{methoddesc}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-lookup>

\subsection{\texttt{<al-lookup>}\label{tag-lookup}}

The \texttt{<al-lookup>} tag is used primarily to allow internal
application values to be converted to display form.

Enclosed by the \texttt{<al-lookup>} tag is a series of
\texttt{<al-item>} (\ref{tag-item}) tags.  Each \texttt{<al-item>} tag
defines a unique translation of an internal application value to
template HTML.

The content enclosed by an \texttt{<al-item>} tag is executed only
when the lookup is referenced by an \texttt{<al-value>} tag.  If the
lookup value does not reference an item then the tag returns from the
\texttt{<al-lookup>} any content that was not enclosed by an
\texttt{<al-item>} tag.

\subsubsection{\texttt{name="..."} attribute\label{tag-lookup-name}}

The \texttt{name} attribute is used to uniquely identify the lookup
table in the application.  Other template HTML accesses the lookup
table via the \texttt{<al-value>} (\ref{tag-value}) tag.

For example:

\verbatiminput{doctest/tags-lookup}

By placing lookup tables in separate template files you can eliminate
redundant processing via the \method{run_template_once()} execution
context method.  This method is defined in the \class{AppContext}
class that is used as a base for all application execution contexts.

As the above example demonstrates, you are able to place arbitrary
template HTML inside the lookup items.  As the content of the item is
only executed when referenced, all expressions are evaluated in the
context of the template HTML that references the item.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-item>

\subsection{\texttt{<al-item>}\label{tag-item}}

The \texttt{<al-item>} tag must only be used as a child tag of an
\texttt{<al-lookup>} (\ref{tag-lookup}) tag.  to allow internal
application values to be converted to display form.

\subsubsection{\texttt{expr="..."} attribute\label{tag-item-expr}}

The \texttt{expr} attribute defines an expression that is evaluated to
generate a lookup table key for the parent \texttt{<al-lookup>}
(\ref{tag-lookup}) tag.  When the parent \texttt{<al-lookup>} is
executed all of the \texttt{expr} expressions are evaluated to build a
dictionary of items.

For example:

\verbatiminput{doctest/tags-item}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-tree>

\subsection{\texttt{<al-tree>}\label{tag-tree}}

This tag is used to display tree structured data.  A pre-order
traversal (node visited before each child) of the tree is performed
and the enclosed content is evaluated for each node in the tree.

The \texttt{treefold}, \texttt{treeselect}, and \texttt{treeellipsis}
attributes on the \texttt{<al-input>} (\ref{tag-input}) tag allow the
user to open, close, and select lazy tree nodes.

Section \ref{tug-tree} contains an example of a simple usage of the
\texttt{<al-tree>} tag.

The \texttt{samples/tree/tree1} sample program takes the simple
example further and implements an application that places a checkbox
next to the name of each node name.  A unique input field name is
generated for each checkbox by using the \texttt{alias} attribute
described in section \ref{tag-input} on page \pageref{tag-input-alias}.

The \texttt{samples/tree/tree2} sample program demonstrates the use of
the \texttt{lazy} \texttt{<al-tree>} attribute that enables lazy child
loading mode.

The \texttt{samples/tree/tree3} sample program demonstrates the use of
the \texttt{ellipsis} \texttt{<al-tree>} attribute.

\subsubsection{\texttt{ellipsis} attribute\label{tag-tree-ellipsis}}

The \texttt{ellipsis} attribute extends the \texttt{lazy}
(\ref{tag-tree-lazy}) traversal.  It collapses nodes close to the root
of tree as deeper nodes are opened.

\subsubsection{\texttt{expr="..."} attribute\label{tag-tree-expr}}

The \texttt{expr} attribute defines the root of the tree traversal.

\subsubsection{\texttt{iter="..."} attribute\label{tag-tree-iter}}

This attribute specifies the name of the \class{TreeIterator}
(\ref{tag-tree-treeiter}) that will be used to iterate over the nodes
in the tree defined by the expression in the \texttt{expr}
(\ref{tag-tree-expr}) attribute.

\subsubsection{\texttt{lazy} attribute\label{tag-tree-lazy}}

The \texttt{lazy} attribute allows lazy traversal of the tree, with child
nodes only being loaded when their parent is open.

\subsubsection{\texttt{single} attribute\label{tag-tree-single}}

The \texttt{single} attribute places the tree in single select mode.
Whenever a new node is selected by browser input the previous selected
node(s) will be deselected.

\subsubsection{TreeNode Objects\label{tag-treenode}}

There is no actual \class{TreeNode} class.  Trees can be constructed
from objects of any class as long as they implement the interface
described here.

\begin{memberdesc}[TreeNode]{children}
This member must only be present in non leaf nodes.  It contains a
list of immediate child nodes of this node.

When using lazy loaded trees this member should be initialised to an
empty list in the constructor.  The presence of the \member{children}
member makes the toolkit treat the node as a non-leaf node.
\end{memberdesc}

\begin{memberdesc}[TreeNode]{children_loaded}
This member needs only be present in non leaf nodes that are
referenced by an \texttt{<al-tree>} tag in lazy mode.  It should be
initialised to \code{0} in the node constructor.  The toolkit will set
the member to \code{1} once it has called the \method{load_children()}
method of the node.
\end{memberdesc}

\begin{methoddesc}[TreeNode]{load_children}{ctx}
This method must be defined for nodes that are referenced by an
\texttt{<al-tree>} tag in lazy mode.  It should must populate the
\member{children} member with the immediate child nodes.

The toolkit will call this method when it needs to display the child
nodes of a node and they have not yet been loaded
(\member{children_loaded}\code{~==~0}).

The toolkit ``knows'' when it needs to see the child nodes of a
particular node so it asks that node to load the children.  This
allows potentially huge trees to be browsed by having the toolkit only
load those nodes that are visible.
\end{methoddesc}

\begin{methoddesc}[TreeNode]{albatross_alias}{}
This method must be defined for nodes that are referenced by an
\texttt{<al-tree>} tag in lazy mode.  It must return a unique string
identifier for this node that is suitable for use as part of an HTML
input field name or URL component via the special \texttt{treeselect},
\texttt{treefold} and \texttt{treeellipsis} attributes.  The identifier
must be the same each time the program is run (so \code{str(id(self))}
will not work).

The \class{TreeIterator} uses the node identifier to record which
nodes are open and which are selected.  The same identifier is also
used when the node is referenced via an \texttt{alias}
(\ref{tag-input-alias}) attribute of an \texttt{<al-input>} tag.
\end{methoddesc}

\subsubsection{TreeIterator Objects\label{tag-tree-treeiter}}

An instance of \class{TreeIterator} class (or the sub-classes
\class{LazyTreeIterator} (\ref{tag-tree-lazytreeiter}) or
\class{EllipsisTreeIterator} (\ref{tag-tree-ellipsistreeiter})) will
be placed into the execution context using the name specified in the
\texttt{iter} (\ref{tag-tree-iter}) attribute.  This iterator will
contain traversal data for the current node each time the tag content
is executed.

Note that it is also acceptable to create an instance of one of the
TreeIterator classes prior to rendering the template.  The
\method{set_selected_aliases()} or \method{set_open_aliases()} methods
can then be used to render the tree with nodes already selected or
open.

By using an object to iterate over the tree the toolkit is able to
provide additional data that is useful in formatting HTML.  The
toolkit also places the iterator into the session (you must be using
an application class that supports sessions).

\begin{methoddesc}[TreeIterator]{value}{}
Returns the current node.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{tree_depth}{}
Returns the depth of the visible tree, from the root to deepest node.
A single node tree has a depth of one.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{depth}{}
Returns the depth of the current node.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{span}{}
Is shorthand for \code{n.tree_depth()~-~n.depth()}.  It is intended to
be used for the \texttt{colspan} of the table cell containing the node
name when laying the tree out in a table.  See the
\texttt{samples/tree/tree2.html} template for just such an example.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{line}{depth}
Only useful when displaying a tree in tabular form where the root is
in the first column of the first row.  Returns the type of line that
should be displayed in each column up to the depth of the current
node.

A return value of \code{0} indicates no line, \code{1} indicates a
line that joins a node later than this node, and \code{2} indicates a
line that terminates at this node.

The example in section \ref{tug-tree} uses this method.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{is_open}{}
Returns \code{TRUE} if the current node is open.  For non-lazy iterators, 
this is always \code{TRUE} except on leaf nodes.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{is_selected}{}
For non-lazy iterators, this always returns \code{FALSE}.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{has_children}{}
Returns \code{TRUE} if the current node has children (ie. it defines a
\member{children} member).
\end{methoddesc}

Most of the methods and all of the members are not meant to be
accessed from your code but are documented below to help clarify how
the iterator behaves.

\begin{memberdescni}[TreeIterator]{_value}
Stores a reference to the current tree node --- returned by
\method{value()}.
\end{memberdescni}

\begin{memberdescni}[TreeIterator]{_stack}
As the tree is being traversed this list attribute records all parent
nodes between the current node and the root.  This is used to
determine which branch lines should be drawn for the current node.
\end{memberdescni}

\begin{memberdescni}[TreeIterator]{_line}
Stores the branch line drawing information for the current node.
Elements of this list are returned by \method{line(depth)}.
\end{memberdescni}

\begin{memberdescni}[TreeIterator]{_tree_depth}
Stores the depth of the tree from the root to the deepest visible
node.  A single node tree has a depth of 1.  This is calculated
immediately before the tree is displayed.  This is returned by
\method{tree_depth()}.
\end{memberdescni}

\begin{methoddesc}[TreeIterator]{set_line}{line}
Saves the \var{line} argument in \member{_line}.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{set_value}{node}
Sets the \member{_value} to the \var{node} argument.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{node_is_open}{ctx, node}
Called internally whenever the toolkit needs to determine the open state
of a tree node.  For non-lazy iterators, it returns whether or not the
node in the \var{node} argument has children (because non-lazy iterators
are always open).
\end{methoddesc}

\subsubsection{LazyTreeIterator Objects\label{tag-tree-lazytreeiter}}

\texttt{<al-tree>} tags that include the \texttt{lazy} attribute use an
instance of the \class{LazyTreeIterator} class. This class supports all
the methods of the \class{TreeIterator} class, as well as the following:

\begin{methoddesc}[TreeIterator]{is_open}{}
Returns \code{TRUE} is the current node is open.  Calls the
\method{albatross_alias()} method of the current node and returns
\code{TRUE} if the returned alias exists in the \member{_open_aliases}
dictionary member.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{is_selected}{}
Returns \code{TRUE} if the current node is selected.  Calls the
\method{albatross_alias()} method of the current node and returns
\code{TRUE} if the returned alias exists in the \member{_selected_aliases}
dictionary member.
\end{methoddesc}

Some methods are designed to be called from application code, not from
templates.

\begin{methoddesc}[TreeIterator]{close_all}{}
Closes all tree nodes by reinitialising the \member{_open_aliases} to
the empty dictionary.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{deselect_all}{}
Deselects all tree nodes by reinitialising the
\member{_selected_aliases} to the empty dictionary.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{get_selected_aliases}{}
Returns a sorted list of aliases for all nodes that are selected
(ie. in the \member{_selected_aliases} member).
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{set_selected_aliases}{aliases}
Builds a new \member{_selected_aliases} member from the sequence of
aliases passed in the \var{aliases} argument.
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{get_open_aliases}{}
Returns a sorted list of aliases for all nodes that are open
(ie. in the \member{_open_aliases} member).
\end{methoddesc}

\begin{methoddesc}[TreeIterator]{set_open_aliases}{aliases}
Builds a new \member{_open_aliases} member from the sequence of
aliases passed in the \var{aliases} argument.
\end{methoddesc}

\class{LazyTreeIterator} instances add the follow private methods and
members:

\begin{memberdescni}[LazyTreeIterator]{_key}
This member caches the value returned by the \method{albatross_alias()}
method for the current node.  This key is then used to look up the
\member{_open_aliases} and \member{_selected_aliases} members.
\end{memberdescni}

\begin{memberdescni}[LazyTreeIterator]{_open_aliases}
A dictionary that contains the aliases for all tree nodes that are
currently open.  The contents of this dictionary is maintained via the
\method{set_backdoor()} method.
\end{memberdescni}

\begin{memberdescni}[LazyTreeIterator]{_selected_aliases}
A dictionary that contains the aliases for all tree nodes that are
currently selected.  The contents of this dictionary is maintained via
the \method{set_backdoor()} method.
\end{memberdescni}

\begin{methoddesc}[LazyTreeIterator]{__getstate__}{}
Used to save the iterator in the session.  This restricts the Python
pickler to saving only the \member{_lazy}, \member{_open_aliases} and
\member{_selected_aliases} members.
\end{methoddesc}

\begin{methoddesc}[LazyTreeIterator]{__setstate__}{tup}
Restores an iterator from the Python pickler.
\end{methoddesc}

\begin{methoddesc}[LazyTreeIterator]{set_value}{node}
Sets the \member{_value} to the \var{node} argument.  When operating
in lazy mode the \method{albatross_alias()} method is called for
\var{node} and the result is cached in \member{_key}.
\end{methoddesc}

\begin{methoddesc}[LazyTreeIterator]{node_is_open}{ctx, node}
Called internally whenever the toolkit needs to determine the open
state of a tree node.  It returns whether or not the node in the
\var{node} argument is open.  This always returns \code{0} for leaf
nodes as they do not have children.  

When in lazy mode the open state of \var{node} is retrieved from
\member{_open_aliases}.  If the node state is open then the method
checks the value of the node \member{children_loaded} member.  If
\member{children_loaded} is \code{FALSE} then the node
\method{load_children()} is called to load the children of \var{node}.
\end{methoddesc}

\begin{methoddesc}[LazyTreeIterator]{set_backdoor}{op, key, value}
The \texttt{<al-input>} and \texttt{<al-a>} tags provide
\texttt{treefold} and \texttt{treeselect} attributes that generate
names using a special backdoor format.  When the browser request is
processed, the \method{set_value()} method of the
\class{NamespaceMixin} directs tree backdoor input fields to this
method.  Refer to the documentation in section \ref{mixin-namespace}.

When the \var{op} argument is \code{"treeselect"} the
\member{_selected_aliases} is updated for the node identified by the
\var{key} argument.  If \var{value} is \code{FALSE} the key is removed
else it is added.

When the \var{op} argument is \code{"treefold"} and \var{value}
argument is \code{TRUE} then the open state of the node identified by
the \var{key} argument is toggled.
\end{methoddesc}

\begin{methoddesc}[LazyTreeIterator]{get_backdoor}{op, key}
When generating backdoor fields for the \texttt{<al-input>} and
\texttt{<al-a>} tags the toolkit calls this method to determine the
value that will assigned to that field.

When \var{op} is \code{"treeselect"} the method returns the current
selected state of the node identified by \var{key}.

When \var{op} is \code{"treefold"} the method returns \code{1}.
\end{methoddesc}

\subsubsection{EllipsisTreeIterator Objects\label{tag-tree-ellipsistreeiter}}

\class{EllipsisTreeIterator} objects are created by using the
\texttt{ellipsis} attribute on an \texttt{<al-tree>} tag. Ellipsis
trees are a variant of lazy trees where nodes at shallower levels are
progressively collapsed into ellipses as the user opens deeper nodes.  
The user can reopen the collapsed nodes by selecting an ellipsis.

They support all the methods of the \class{LazyTreeIterator}
(\ref{tag-tree-lazytreeiter}), as well as the following methods:

\begin{methoddesc}[EllipsisTreeIterator]{node_type}{}
Returns \code{0} for a regular node, or \code{1} for nodes that have
been collapsed into an ellipsis. This is actually implemented on the
\class{LazyTreeIterator}, but will always return \code{0} there.
\end{methoddesc}

\class{EllipsisTreeIterator} objects also have the following private
methods and members:

\begin{memberdescni}[EllipsisTreeIterator]{_noellipsis_alias}
Records the last ellipsis to be selected by the user, and is used to
suppress the generate of an ellipsis at that location next time the tree
is rendered.
\end{memberdescni}

\begin{methoddesc}[EllipsisTreeIterator]{node_use_ellipsis}{ctx, node}
Returns \code{TRUE} if it is acceptable to render the specified
\texttt{node} as an ellipsis. If the node's alias matches
\member{_noellipsis_alias}, \code{FALSE} is return, otherwise \code{TRUE}
is returned if any of the node's children are open.
\end{methoddesc}

The behaviour of the \method{set_backdoor} and \method{get_backdoor}
methods has been extended to recognise a \texttt{treeellipsis} op. This
is used to process browser requests to open an ellipsis (it sets the
\member{_noellipsis_alias} member.

\section{Macro Processing\label{tag-macroproc}}

Tags in this section provide a simple macro processing environment for
template files.

The main purpose of Albatross macros is to provide a mechanism to
divide your HTML into presentation structure and presentation
appearance.  By defining appearance presentation tricks inside macros
you can make global changes to your web application appearance by
changing one macro.

The \texttt{<al-macro>} (\ref{tag-macro}) and \texttt{<al-usearg>}
(\ref{tag-usearg}) tags are used to define macros, while
\texttt{<al-expand>} (\ref{tag-expand}) and \texttt{<al-setarg>}
(\ref{tag-setarg}) are used to invoke and expand previously defined
macros.

The \class{ResourceMixin} (\ref{mixin-resource}) and
\class{ExecuteMixin} (\ref{mixin-execute}) classes provide the
Albatross macro definition and execution facilities respectively.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-macro>

\subsection{\texttt{<al-macro>}\label{tag-macro}}

The \texttt{<al-macro>} tag is used to define a macro.  All enclosed
content becomes part of the macro definition.

Executing the macro registers the macro with the execution context via
the \method{register_macro()} method using the name in the
\texttt{name} (\ref{tag-macro-name}) attribute.

Note that the execution of the macro content is deferred until later
when the macro is expanded via the \texttt{<al-expand>}
(\ref{tag-expand}) tag.  This means that executing a macro definition
produces no output.  Output is produced only when the macro is
expanded.

\verbatiminput{doctest/tags-macro1}

The deferred execution also means that you can include content that
only works within the context of the \texttt{<al-expand>} tag.

\verbatiminput{doctest/tags-macro2}

In the above example the content of the macro makes reference to a
\var{oops} that is not defined in the execution context when the
macro was defined.

Inside a macro definition you can use as yet undefined macros.

\verbatiminput{doctest/tags-macro4}

Care must by taken to ensure that you do not make circular macro
references else you will cause a stack overflow.

\subsubsection{\texttt{name="..."} attribute\label{tag-macro-name}}

The \texttt{name} attribute is used to uniquely identify the macro in
the application.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-usearg>

\subsection{\texttt{<al-usearg>}\label{tag-usearg}}

The \texttt{<al-usearg>} tag is used inside a macro definition to
define the location where content enclosed by the \texttt{<al-expand>}
(\ref{tag-expand}) tag should be placed when the macro is expanded.

All content enclosed by the \texttt{<al-expand>} tag is passed to the
macro as the unnamed argument.  The unnamed argument is retrieved in
the macro definition by using an \texttt{<al-usearg>} tag without
specifying a \texttt{name} (\ref{tag-usearg-name}) attribute.  When a
macro expects only one argument it is best to use this mechanism.

\verbatiminput{doctest/tags-macro3}

\subsubsection{\texttt{name="..."} attribute\label{tag-usearg-name}}

Macros can be defined to accept multiple arguments.  The \texttt{name}
attribute is used to retrieve named arguments.  When invoking a macro
that accepts named arguments the \texttt{<al-setarg>}
(\ref{tag-setarg}) tag and \texttt{name} attribute are used to define
the content for each named argument.

\verbatiminput{doctest/tags-macro7}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-expand>

\subsection{\texttt{<al-expand>}\label{tag-expand}}

The \texttt{<al-expand>} tag is used to expand a previously defined
macro.

You can pass macro expansions as arguments to other macros.

\verbatiminput{doctest/tags-macro5}

All arguments to macros are executed each time they are used in the
macro definition.  This means that you need to be aware of side
effects when using arguments more than once inside a macro.

\verbatiminput{doctest/tags-macro6}

\subsubsection{\texttt{name="..."} attribute\label{tag-expand-name}}

The \texttt{name} attribute contains the name of the macro that will
be expanded.  Macros are defined and names using the
\texttt{<al-macro>} (\ref{tag-macro}) tag.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% <al-setarg>

\subsection{\texttt{<al-setarg>}\label{tag-setarg}}

The \texttt{<al-setarg>} tag is used pass content to a macro.  All
content enclosed by the tag will be passed as an argument to the macro
named by the parent \texttt{<al-expand>} (\ref{tag-expand}) tag.

The \texttt{<al-setarg>} tag is normally used to pass content to
macros that define named arguments, but can also be used to enclose
the unnamed argument.

\verbatiminput{doctest/tags-macro8}

\subsubsection{\texttt{name="..."} attribute\label{tag-setarg-name}}

The \texttt{name} attribute is used to identify the name macro
argument that will receive the enclosed content.
