Documentation - Tags
The previous chapter discussed the Spyce module facility, the standard Spyce
modules and how users can create their own modules to extend Spyce. Spyce
functionality can also be extended via active tags, which are defined in tag
libraries. This chapter describes what Spyce active tags are, and how they are
used. We then describe each of the standard active tag libraries and, finally,
how to define new tags libraries.
It is important, from the outset, to define what an active tag actually does.
A few illustrative examples may help. The examples below all use tags that are
defined in the core tag library,
that has been installed under the spy prefix, as is the default.
Common mistake: Don't use [[= ]] to send values to active tag attributes:
[[= ]] sends its result directly to the output stream. And since those tokens
are parsed with higher precedence than the tag markup, Spyce won't recognize
your tag at all and will print it verbatim to the client.
Instead, prefix an expression with =, as in "=range(5)" above, and Spyce will
eval it before sending it to the tag.
- <spy:parent src="parent.spi"/>
Wraps the current page in the parent template found at parent.spi in the
- <spy:for items="=range(5)">
As expected, these tags will print the value of foo, set to
bar above, 5 times.
Note that the same output could have been achieved in many different ways, and
entirely without active tags. The manner in which you choose to organize your
script or application, and when you choose active tags over other
alternatives, is a matter of personal preference. Notice also that active tags
entirely control their output and what they do with their attributes and the
result of processing their bodies (in fact, whether the body of the tag is
even processed). Tags can even supply additional syntax constraints on their
attributes that will be enforced at compile-time. Most commonly a tag could
require that certain attributes exist, and possibly that it be used only as a
single or only as a paired (open and close) tag. Unlike early versions of
HTML, active tags must be strictly balanced, and this will be enforced by the
Below, each individual standard Spyce tag library is documented, followed by a
description of how one would write a new
active tag library. The following general information will be useful for
reading that material.
- Active tags are installed using the [[.taglib]]
directive, under some prefix.
Tag libraries may also be be loaded globally in the config module; by default
the core and form libraries are preloaded.
Active tags are of the format <pre:name ... >, where pre is the
prefix under which the tag library was installed, and name is defined
by the tag library. In the following tag library documentation, the prefix
is omitted from the syntax.
- The following notation is used in the documentation of the tag libraries
- <name .../> : The tag should be used as a singleton.
- <name ... > ... </name> : The tag should be used as an
- [ x (default)] : The attribute is optional. Attributes not enclosed in
brackets are required.
- foo|bar : indicates that an attribute may be one of two
constant strings. The underlined value is the default.
- string : an arbitrary string constant, never evaluated as Python
- exprstring : may be a string constant, and may be of the form
'=expr', where expr is
a Python expression that will be evaluated in the tag context.
- expr: a Python expression. (Currently only the "data" parameters
of some form and core tags use this rather than exprstring.)
- exports foo, *bar Exports to the parent context
the variable foo and the variable
with the name given by the expression bar. Normally, implementation
details of tags will not affect the parent context, so you do not have
to worry about your variables being clobbered. Tags may, however,
export specific parts of their own context to the parent.
See, for example,
the let and for tags in the core taglib.
Note: exporting of variables whose name
cannot be determined at compile time is deprecated, and will be removed in Spyce 2.2.