spyce
         
home     documentation     download     Spyce logo


Documentation - Tags

Prev: 3.8.12 - Writing Modules Up: 3 - Runtime Next: 3.9.1 - Core

3.9. 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.

  • <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.
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.

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.


Prev: 3.8.12 - Writing Modules Up: 3 - Runtime Next: 3.9.1 - Core

Sub-sections:


Spyce logo
Python Server Pages
version 2.1.3
Spyce Powered SourceForge Logo