Documentation - Tags
3.9.4. Writing Tag Libraries
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.
apply specifically to tag library definition:
Active tags may specify handlers
as in normal Spyce code; this may be done inline
with class chunks, or as a reference
to a separate .py module. This allows building reusable components easily!
Again, the chatbox demo demonstrates this.
[[.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:
[[.begin name=bold buffers=True]]
- 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.