home     documentation     download

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.

• <spy:parent src="parent.spi"/>
  Wraps the current page in the parent template found at parent.spi in the same directory.
• <spy:for items="=range(5)">
    <spy:print value="=foo"/>
  </spy:for>
  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 Spyce compiler.

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 below:
  • <name .../> : The tag should be used as a singleton.
  • <name ... > ... </name> : The tag should be used as an open-close pair.
  • [ 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.

Sub-sections:

• 3.9.1 - Core
• 3.9.2 - Form
• 3.9.3 - Active Handlers
• 3.9.4 - Writing Tag Libraries
• 3.9.5 - Writing Tag Libraries the hard way