Example of User Defined Tag Libraries
To clarify how the Tag Library functionality works we will break this section up into 3 parts :
To start, we will examine an RVML document containing extensions, we will then look at how to declare an external tag library to the KineticFusion application, and finally, a short overview on how to write your own tag library. This process is fully documented in the installation documentation (as ever, though, if you have any questions, you know where to find us).
Part 1. Using External Tag Libraries in RVML
Part 2. Adding Library Support to KineticFusion
Part 3. Creating an External Tag Library
Using External Tag Libraries in RVML
A example RVML document for adding SWC components to a small movie is shown below:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<Movie version='7' width='600' height='550' rate='23' backgroundColor='white' compressed='Yes'
xmlns='http://www.kineticfusion.org/RVML/1.0'
xmlns:c='http://www.kineticfusion.org/components'>
<Components><!-- Add the following SWC components to the output movie -->
<Component id="Button" />
<Component id="ComboBox" />
<Component id="TextInput" />
</Components>
<Timeline>
<Frame>
<c:Button x="100" y="100" id="myButton" enabled="true" toggle="false" label="Hello">
<c:Event name="click"> if ( this.label == "Hello") this.label="Bye"; else this.label="Hello"; </c:Event>
</c:Button>
<c:ComboBox x="100" y="200" id="myCombo" enabled="true" data="1,2,3,4,5" labels="Value1, Value2, Value3, Value4, Value5">
<c:Event name="change">_level0.myTextField.text=this.selectedItem.data;</c:Event>
</c:ComboBox>
<c:TextInput x="100" y="300" id="myTextField" enabled="true"/>
<c:Button x="100" y="400" id="myClearButton" enabled="true" toggle="false" label="Clear">
<c:Event name="click"> _level0.myTextField.text=""; _level0.myCombo.selectedIndex = 0; </c:Event>
</c:Button> </Frame>
</Timeline>
</Movie>
The first step is to declare the namespaces that will be used for our external tag libraries. In this case the namespace for the example component handler is highlighted in red above as : http://www.kineticfusion.org/components. All subsequent references to elements in this namespace can be abbreviated with the 'c' prefix. In our configuration file, which we will see shortly, we will associate our example Component Handler with this namespace. Therefore all XML elements in this namespace are processed directly by our new handler.
The example component handler uses the element name to locate the component that is to be placed on the stage. It will parse all the properties of the component and extract those properties specified as element attributes. It will finally accept Event child elements for a component ensuring that the specified event is defined for the component.
So what does the resulting SWF look like? Have a look (it's about 56K) ....
Adding Library Support to KineticFusion
All available external tag libraries are made available to the KineticFusion application by declaring them in the Tag Libraries configuration file. By default, this resides in the installation 'config' folder and an example file looks like this:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<TagLibraries>
<!-- A simple tag that supports a Log element that logs any text attribute when it's encountered.
While this is a simple handler it can be used to verify Attribute Expression values.-->
<TagLibrary namespace="http://www.kineticfusion.org/logging"
factoryClass="org.kinesis.xml.handlers.logging.LogFactory"
classLocation="$INSTALL_PATH/lib/ExampleHandlers.jar" />
<!-- Samples handler for SWC components that converts attributes to ActionScript
and supports named event handlers. It supports all SWC components and will iterate
though each component's parameter set building up an initialisation ActionScript block. All element
names are dynamic and correspond to component names.-->
<TagLibrary namespace="http://www.kineticfusion.org/components"
factoryClass="org.kinesis.xml.handlers.components.ComponentFactory"
classLocation="$INSTALL_PATH/lib/ExampleHandlers.jar" />
</TagLibraries>
This file is read by KineticFusion on startup. Each external tag library is declared in this file with a <TagLibrary> element. This element takes three attributes:
- The namespace attribute is the namespace used with the element inside the RVML document
- The factoryClass attribute is the class that provides ElementHandlers to process elements in the namespace
- The classLocation is the directory or Jar file containing the factory class.
Creating An External Tag Library
External Tag Libraries are currently written in Java. KineticFusion uses SAX technology to process all input RVML. The details on how KineticFusion implements RVML processing are covered in the installation documentation. To implement an external tag library, the developer must first write a class that inherits from the com.kinesis.xml.libraries.TagHandlerFactoryType interface and must have a default constructor. The interface contains a single method:
/**
* Factory class for creating new Tag Handlers
*/
public interface TagHandlerFactoryType {
/**
* Return a new SAX handler for the specified element in the given context.
* The factory can add any returned handler to the parent handler to add
* persistent handling for this element in the specified context.
*
* @param context
* The current context. This provides the contextual information
* on the movie including the current hierarchy of Sax element
* handlers
* @param namespaceURI
* THe namespace URI of the element
* @param localName
* The local name of the element
* @return The handler for the element or null if there is no valid handler
*/
public KFSaxElementHandlerType getSaxHandler(RVMLSaxContextType context,
String namespaceURI,
String localName);
}
The factory class is responsible for finding a Handler object (of type KFSaxElementHandlerType) that will process the given element and the Handler object will then be passed the specified element details to process. Consult the installation documentation for further details on implementation.
And finally, how long should does it take to implement a tag library? The Tag Library for the above example was written in about a day. If you move slowly, absorbing the KineticFusion API and learning how the existing RVML handlers work you should be able to be productive very quickly. The RVML handlers can also be extended simply using this mechanism.