home     documentation     download

Creating your own active tags is quite easy and this section explains how. You may want to create your own active tags for a number of reasons. More advanced uses of tags include database querying, separation of business logic, or component rendering. On the other hand, you might consider creating simpler task-specific tag libraries. For example, if you do not wish to rely on style-sheets you could easily define your own custom tags to perform the formatting in a consistent manner at the server. Another convenient use for tags is to automatically fill forms with session data. These are only a few of the uses for tags. As you will see, writing a Spyce active tag is far simpler than writing a JSP tag.

(The chatbox demo gives an example of an active tag.)

Tag libraries must be placed in a separate file from request-handling Spyce pages. The following directives apply specifically to tag library definition:

• [[.tagcollection ]] :
  Indicates that the current file will be an Active Tag library. Must be at the start of the file.
• [[.begin name=string [buffers=True|False] [singleton=True|False] [kwattrs=string] ]] :
  Begin defining a tag named name. Optional attributes:
  • buffers: if true, Spyce will evaluate the code between the begin and end tags and pass it to the tag as the variable _content. For instance, the following simplistic tag makes its contents bold:

    examples/tagbold.spi

    [[.begin name=bold buffers=True]] <b>[[=_contents]]</b> [[.end]]

  • singleton: if true, Spyce will not allow paired use of the tag (<tag></tag>) and only allow singleton use (<tag />). If false, the reverse is true.
  • kwattrs: the name of the dict in which to place attributes not specified with [[.attr]] directives. If not given, Spyce will raise an error if unexpected attributes are seen.
• [[.attr name=string [default=string] ]] :
  Specify that the current tag being defined expects an attribute named name. If a default string is given, the attribute is optional. (Dynamic attributes may be accepted with the kwattrs option in the begin directive.) (If the default string is prefixed with '=', it will be evaluated as python code at runtime.)
• [[.export var=string [as=string] ]] :
  Specifies that the variable from the tag context named var will be exported back to the calling page. The optional as attribute may be used to give the variable a different name in the calling context.
• [[.end ]] :
  Ends definition of the current tag.

(Be careful if you take the class chunk approach with handlers, since all class chunks that get used in a given page are pulled into the same namespace. By convention, tag handlers defined in reusable tags are prefixed with the tag name, e.g., chatbox_addline.)

Active tags should not contain f:form active tags; this needs to be done by the .spy page for the Spyce compiler to link up Active Handlers correctly.

One limitation of using the Active Tag directives described here is that tags within a single collection may not call each other. Usually, you can work around this by defining common code inside a .py module and importing that. If this is not an option, you can create Active Tags manually. This is described in the next section.