Introduction
Ringside supplies a number of FBML tags, as well as our own set of Social Domain-Specific-Language tags, prefixed with an "rs:" namespace. This document describes how you can write your own tags which are automatically detected and processed within a deployed environment.
Naming the Tag
A tag class named xyMyTagHandler or xyMyTag will translate into a tag named <xy:my-tag>. The namespace must be lower-case. Alternatively, you can override the default behavior by providing the following functions in your handler class:
- getName(): returns the tag name (string)
- getNamespace(): returns the tag namespace (string)
Note: One tag handler per file, and the file name must match the class name.
HTML Element Naming
In the event you would like to override an HTML element, i.e. <a>, <br />, etc., you should do one of the following:
- Do not prefix your class with a lower-case namespace. If you are overriding the <a> tag, your class name should be "AHandler".
- Override getNamespace() in your tag handler class and return NULL.
Defining the Tag Type
Some tags contain other tags (block level, i.e. <table>), some stand by themselves (inline, i.e. <a href...>...</a>). Some tags don't have a body (empty tags, i.e. <br />). By default, we assume all tags are 'inline' and not empty. You can override this default behavior by implementing the following methods in your tag handler class:
- getType(): returns the type of tag, possible values are:
- 'block' - this tag contains other tags
- 'inline' - this tag has no tag child elements (default)
- 'both' - when all else fails...
- isEmpty(): returns true or false (default), indicates whether the tag has no body (such as <hr />)
Writing the Tag
A tag is supported by a tag handler class. When the Ringside Social Application Server encounters a tag in an application, it will lookup the handler class for that tag and call the appropriate methods on that tag at the appropriate times in order to render it.
The appropriate methods have the following signatures:
function doStartTag( $application, $parentHandler, $args );
function doBody($application, $parentHandler, $args, $body );
function doEndTag( $application, parentHandler, $args );
The parameters passed into the tag handler are as follows:
- $application: RingsideSocialDslContext - this can be used to obtain a reference to a client which can be used to get information from the API container, such as the current user or the application ID, for example.
- $parentHandler: A parent tag handler, if one exists.
- $args: An array of the name/value pairs that were specified as attributes and values in the tag (as used on the page that is being rendered)
- $body: The text that is enclosed in the body of the tag.
Note that at this time, there is not an interface defined that tag handlers must implement. Also note that a tag handler does not need to implement the doBody() function if it will not have a body; if this is the case, the parser will never attempt to call doBody().
When implementing tag handlers, there are certain values that can be returned from the doStartTag() function that direct the parser, as follows:
- true - call each child then call my doEndTag
- false - don't process me
- tag names (string) - a comma separated list of tags
- array of tag names - ONLY process these tags
- 'body' - says collect the body text and call the doBody handler with the text passed in
- 'mixed' - tag body contains plain text intermixed with inline tags
- 'print' - print the begin tag, then walk the children, then print end tag
- 'redirect' - redirect to the url in the tag attributes
Deploying the Tag
In order to have a Ringside deployment detect your new tag, you have to copy the tag handler class to a directory named 'ringside/social/dsl/handlers/fbml' in your include_path. Your new tag should be automatically loaded when the page that contains your tag is requested.
Performance, Caching
Performance gains can be had by caching the results of scanning for tags. Caching is turned off by default. To turn it on, set $cacheTags to true in your LocalSettings.php file.
Also, on every request, a regular expression search is performed on the rendered text to check for new, unloaded tags. To turn this off, set $scanTags to false in LocalSettings.php
