4.3 Custom Tags

Custom tags are defined using the Custom Tags API, which is explained in the Developers manual. HTML designers can use custom tags just like any other HTML tag, resulting in a simple, easy to maintain template that doesn't require any knowledge of Python. Attributes of custom tags are interpreted as string arguments to the constructor of a class that defines the behavior of tag. If the attribute value begins with an equals symbol ("="), then the value will be interpreted instead as a python expression. The meaning of attributes is dependent on the custom tag class developed, so this varies from tag to tag within any given application.

That said, there is one attribute that is common to all custom tags, the id attribute. This is also a string that can be used to reference the object created by the tag from the Python code module. This is explained in detail in the Custom Tags API section of the Developers manual. If an id attribute is present, then the object is retrieved from an object cache if an object of the same id has been previously defined. If one hasn't been defined, then a new object will be used.

In this way an HTML designer can complete a template without having any supporting Python code module, and the template will be parsed, compiled and executed properly. The designer will be able to see instant results from his design without any knowledge of Python or what kind of code the programmer will write. Once a Python code module has been written by the programmer, the tag will be replaced by the object defined in the module, resulting in the correct output for the application.

``Anonymous'' custom tags can be used; that is, a custom tag without an id attribute. In this case the resulting object will not be accessible from the Python code module, but this can be a useful tool for designing HTML pages that use a common look and feel that is determined programmatically.

Custom Tag objects have the following methods that can be used programmatically in the Python code module:

add( thing)
Adds an arbitrary object thing to the things contained by the tag. Equivilant to nesting a custom tag that creates thing inside the current custom tag in the template file.

addString( text)
Adds text to the contents of the tag. Equivilant to typing bare HTML inside the current custom tag in the template file.

There is a of restriction when using PSE template tags within the constructs of Custom Tags. If you include any statements that will produce output using pse.write, print or sys.stdout.write or something similar (except for <?= ... ?> tags), then that output will appear before the tag output. An examination of the parsed servlet code will confirm this behavior. Also note that question mark "?" notation in Custom Tag attribute values is ignored, and the entire value is passed to the Custom Tag.