The taglib module is loaded implicitly and supports the active tags
functionality at runtime. It is expected that the casual user will not have
much use for this module, and will only call its functions indirectly by
importing tag libraries and using active tags. Primarily, this is because the
methods interoperate very tightly and require a very strict calling sequence,
which is generated by the Spyce compiler for each active tag it encounters.
Nevertheless, for completeness, the taglib module provides the following
methods:
context: This field is a dictionary that serves as the context in
which tags operate. Tags can store variables and evaluate expressions within
this context. The tag context contains references to all the loaded modules.
Thus, it is valid to refer to something like request.query() in a tag expression. However, it is not
valid to change any module variable references. While this will not cause
any harm, the user should expect that these new values can be reset by the
runtime at any time.
load( libname, [libfrom], [libas] ): Loads a tag library
class named libname from a file called libfrom in the search
path, and installed it under the tag prefix libas. The default for
libfrom is libname.py. The default for
libas is libname. Once installed, a library
name is its unique tag prefix.
unload( libname ): Unload a tag library that is installed
under the libname prefix. This is usually performed only at the end
of a request.
tagPush( libname, tagname, pair ): Push a new tag object for
a libname:tagname tag onto the tag stack. The pair
parameter is a flag indicating whether this is a singleton or a paired tag.
tagPop(): Pop the current tag from the tag stack.
getTag(): Return the current tag object.
outPush(): Begin capturing the current output stream. This
is usually called by the tagBegin method.
outPopCond(): End capturing the current output stream, and
return the captured contents. It will only "pop" once, even if called
multiple times for the same tag. This method is usually called by either the
tagEnd(), tagCatch, or tagPop() methods.
tagBegin( attrs ): This method sets the tag output and
variable environment, and then calls the tag's begin() method with
the given attrs tag attribute dictionary. This method returns a flag,
and the tag body must be processed if and only if this flag is true.
tagBody(): This method sets the tag output and variable
environment, and then calls the tag's body() method with the captured
output of the body processing. If this method returns true, then the
processing of the body must be repeated.
tagEnd(): This method sets the tag output and variable
environment, and then calls the tag's end() method. This method must
be called if the tagBegin() method completes successfully in order to
preserve tag semantics.
tagCatch(): This method should be called if any of the
tagBegin, tagBody or tagEnd methods raise an exception. It calls the tag's
catch() method with the current exception.
As stated previously, it is expected that the user will not call these methods
directly, but rather simply use the active tag functionality that this module
supports. Spyce comes with various standard tag libraries. The following example shows a
few simple ones in use: