.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. % Copyright 2001 by Object Craft P/L, Melbourne, Australia.
.. % LICENCE - see LICENCE file distributed with this software for details.
.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. _tag-ref:
*******************
Templates Reference
*******************
Albatross provides a templating system that applications use to generate HTML.
Albatross templates are loosely based on XML, but are a little more forgiving.
The primary features are:
* All standard Albatross tags use an ``al-`` prefix, with the ``alx-`` prefix
available applications and extensions to implement their own tags.
* For Albatross tags that enclose content you can use the XML empty tag syntax
to indicate that there is no content.
* All Albatross tag and attribute names are transformed to lowercase.
* Attributes may appear over multiple lines, and attribute values can be broken
over multiple lines.
* Attribute values can be enclosed with either single or double quotes.
* The enclosing quote character can be used within the attribute string if it
is escaped by a backslash (``\``).
* 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.
For example the following two constructs are identical. :
.. code-block:: albatross
.. code-block:: albatross
The Albatross templating system includes enhanced versions of many HTML tags,
as well as tags that control the flow of execution of the template. These are
described in detail in subsequent sections. The templating system also allows
any other HTML tag to be prefixed with ``al-`` to gain access to the attribute
evaluation system.
Attributes of Albatross tags can be processed in a number of ways:
* Some attributes control the behaviour of the enhanced and flow control tags.
* Appending ``expr`` to any attribute name causes the value of the attribute
to be evaluated and the results of the evaluation substituted for the
attribute value. For example:
.. code-block:: albatross
would produce
.. code-block:: html
* Appending ``bool`` to any attribute name causes the attribute to be being
evaluated in a boolean context. If the result is ``True``, a boolean
HTML attribute is emitted, and if the result is ``False``, no attribute
is emitted. For example:
.. code-block:: albatross
If ``abc.isdisabled()`` evaluates as ``True``, then the ``disabled`` attribute
is emitted:
.. code-block:: html
But if ``abc.isdisabled()`` evaluates as ``False``, then the ``disabled``
attribute is suppressed entirely:
.. code-block:: html
* Any other attributes are passed through unchanged.
The following example demonstrates all of these to change the styling
of alternate rows in a table:
.. literalinclude:: doctest/tags-anytag-tr
:language: pycon
.. _tag-escaping:
Escaping generated content
==========================
Whenever template execution results in evaluated data being written, any
characters that have special meaning in HTML are escaped to protect against
cross-site scripting attacks [#]_:
==== ======
From To
==== ======
& &
< <
> >
" "
' '
==== ======
For example:
.. literalinclude:: doctest/tags-escape
:language: pycon
You may occasionally have valid reasons to want to write content without
escaping. In these cases you can use ``htmlsafe()`` to signal that the content
has already been rendered safe for HTML use:
.. literalinclude:: doctest/tags-escape-safe
:language: pycon
``htmlsafe()`` is a simple sub-class of the `str()` type, used to signal that
escaping is not necessary; it has no methods of it's own, and performing
operations such as string concatenation on it will result in a regular `str()`.
An alternative mechanism is to use the ``noescape`` attribute:
.. literalinclude:: doctest/tags-escape-noescape
:language: pycon
One potential pitfall to ``noescape`` is that the flag is separated from the
code that generated the data and the security implications are not immediately
apparent to anyone editing the code.
.. [#] `XSS or Cross-site scripting on Wikipedia `_
.. _tag-fakeapp:
Fake Application Harness
========================
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.
.. literalinclude:: fakeapp.py
:language: python
.. _tag-enhhtml:
Enhanced HTML Tags
==================
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.
.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. %
.. _tag-form:
````
-------------
Albatross browser request merging depends upon the functionality provided by the
```` 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 ``