spyce
home
license
community
download
examples
resources
wishlist
contrib (@sf)
documentation
intro
lang
runtime
modules
tags
install
exits
sourceforge
statistics
freshmeat

Documentation - Tags
[[ Spyce ]]
Python Server Pages
by Rimon Barr

Prev: 4.17 - Writing Modules Up: Table of Contents Next: 5.1 - Core

5. 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 follows:

  [[.taglib name=core as=spy ]]

  • <spy:print val="=2+2"/>
    Rather than emitting itself as plain text, this tag will output 4.
  • <spy:let var="foo" val="bar"/>
    This tag will assign the constant string value bar to a variable named foo in the tag context, which will then be available to other tags that follow later in the document.
  • <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. 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.
  • Tags store variables and evaluated expression within a separate tag context. This tag context dictionary is available via taglib.context (i.e. the context field of the taglib module). 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 at any time.
  • 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 ] : 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
    • expression : 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.


Prev: 4.17 - Writing Modules Up: Table of Contents Next: 5.1 - Core

Sub-sections:


© 2002-08 Rimon Barr
email: rimon@acm.org
Spyce Powered SourceForge Logo [[ Spyce ]]
Python Server Pages
version 1.3.13