com.ibm.mashups.livetext
Interface ServiceModel

public ServiceModel

The livetext (formally known as semantic tag) service API. The implementation class of this API provides the livetext parsing services so that tags on a page can be recognized and processed according to the tagservice.entries.cfg configuration file. An instance of this API implementation class should be created after a page is fully loaded. Once the instance is created, the init method should be called so that the tags will be parsed. Each tag processor will be invoked to process the tags in order of the tags defined in the tagservices.entries.cfg file. There should be no more than 1 instance of this class on each page. The implementation of this API should subscribe to one of the following two event topics.

"/com/ibm/mashups/livetext/livetextchanged"

"/com/ibm/mashups/livetext/livetextcontentchanged"

Once an event is published to that topic, the implementation of this API should start using the given DOM node and processing all the decendant DOM nodes of that given node. That given node itself will not be processed. Event livetextchanged will cause the passed node and all its children to be parsed. Event livetextcontentchanged will cause only the passed node children to be parsed.

If a component wishes for a piece of markup fragment being processed, that component should publish an event to that topic, that event should also come with the DOM node which holds that piece of the markup fragment, callback functions and a flag to indicate how to proceed when an exception is thrown. The DOM node, flag and the callback functions are referred to event data below.

The event data must be an array of objects in the following format.

[domNode, continueAfterException, preProcessCallbackFunc, postProcessCallbackFunc]

The first object in the event data array is the root node of the HTML markup fragment. If that object is not a valid DOM node, then no action will be taken. The second object in the array is a flag to indicate if the parsing should continue when an exception is caught. The third and the last object in the array are two callback functions. The preProcessCallbackFunc will be invoked before the parsing process starts, the postProcessCallbackFunc will be invoked after the parsing process finished. If none callback function is provided by the array, then no function will be invoked. The default value for continueAfterException flag is false.

If the node needs to be processed and the both pre and post process callback exist, then the call should look like this.

dojo.publish("/com/ibm/mashups/livetext/livetextchanged",
[aDOMNode, false, callbackFunc1, callbackFunc2]);

If all the nodes on the page need to be processed, and no callback functions are needed, then the call should look like this.

dojo.publish("/com/ibm/mashups/livetext/livetextchanged",
[document, true]);

If the node in the event data is not a valid node, then the event will be ignored. Before a given DOM node being processed, The preProcesCallbackFunc will be called. After the given DOM node has been processed, the postProcessCallbackFunc will be called. If preProcessCallbackFunc or postProcessCallbackFunc is not null, then the callback function is guaranteed to be invoked regardless the status of the tag parsing process. The given DOM node is considered as the root node of given HTML fragment. All its decendent child DOM nodes will be parsed. To make the process effecient, components should avoid passing the entire Document as the given DOM node unless it is the very first time.

Tag service configuration.

This section describes the specific implementation of the IBM Lotus Mashups livetext services implementation. The tag matching method is not defined, it is up to the tag service implementation to define their own match method and tag processing invoke sequence.

Tags can be nested, this tag service can be configured to process nested tags or leave the nested tags to the container to process.

This service is configurable by providing a configuration file. The configuration file should be located at the same location where the tag service API implementation class is. The configuration file is simply a JSON type of code. It defines tags that this service can process. The following is an example of this file.

[
{ "match":"*.iWidgetSkin[skin]","processEnclosedTags":true,'waitOnPreTag':true,
"module":"tagservices", "path":"../../tagservices", "baseClass":"tagservices.skins"},
{ "match":"*.iw-iWidget","processEnclosedTags":false,'waitOnPreTag':false,
"module":"tagservices", "path":"../../tagservices", "baseClass":"tagservices.widgets"}
]

Each entry in this file presents a type of tags that this service can process. The order of these entries in the configuration file is important because the service will process the tags in this order.

Each entry should have the following element.

"match": The CSS3 format for tag attribute match value. The value of this element determines if a tag should be processed by the services. This can now be a comma seperated values. In case comma seperated values are specified, nodes matching each of them will be merged
"processEnclosedTags": The value of true or false to determine if the service should process the nested tag. The default value is false.
"waitOnPreTag": The value of true or false to determine if the service should process this entry defined tags before the process of the previous entry defined tags have been completed. The default value is true.
"module": The implementation JavaScript module. This is required.
"path": The path to the JavaScript implementation of the tag processor. This should be a URI to the JavaScript resource. This is required.
"baseClass": The class which implement the tag processor API.
"id" a unique id to identify the entry. This is useful in case we have same baseClass as different handlers. id will be used to find nodes are for which matching criteria.Can be null
Livetext service also provide a way for other components to dynamically add or remove a configuration entry. The addition or removal of the entries will not be persisted. It will only affect the current session.
If an entry needs to be added, then a component should publish to this topic with an entry.
"/com/ibm/mashups/livetext/configentryadded"

If an entry needs to be removed, then a component should publish to this topic with an entry.
"/com/ibm/mashups/livetext/configentryremoved"

Field Summary

String

SERVICE_NAME The service name to be used to fetch the service from the ServiceManager

Method Summary

void	init(Object initArgs) Initiate the tag service.
void	onTagChanged(DOMNode domNode, boolean continueAfterException, com.ibm.mashups.livetext.CallbackModel.preProcessCallbackFunc preProcessCallbackFunc, com.ibm.mashups.livetext.CallbackModel.postProcessCallbackFunc postProcessCallbackFunc) Tag changed event handler.
void	onUnchangeTag(DOMNode node, Boolean continueAfterException, unknown preUnProcessCallback, unknown postUnProcessCallback, unknown unchangeCompleteCallback) The event handler when a tag and/or its content should be removed.
void	onTagContentChanged(DOMNode domNode, boolean continueAfterException, com.ibm.mashups.livetext.CallbackModel.preProcessCallbackFunc preProcessCallbackFunc, com.ibm.mashups.livetext.CallbackModel.postProcessCallbackFunc postProcessCallbackFunc) Tag content changed event handler.
void	onAddConfigEntry(ConfigEntry entry, boolean bFront) The method allows component dynamically add a new configuration entry so that the service can start process the tags presented by the entry.
void	onRemoveConfigEntry(ConfigEntry entry) This method allows components dynamically remove a configuration entry so that the service will not process that type of tags which are presented by the configuration entry.

Field Detail

SERVICE_NAME

String SERVICE_NAME

The service name to be used to fetch the service from the ServiceManager

Method Detail

init

void init(Object initArgs)

Initiate the tag service. This should be only called once after a page is completely loaded. Normally it should be added to the document onload method. This method should initialize the tag service which includes load the tag configuration and start parsing tags for the entire page.

Parameters:

initArgs - Optional JSON object that defines initialization properties for the live text service. May be null. Currently supports these properties on the JSON object:
{
node: The DOM node whose decendent nodes will be parsed and processed. Applies only to the initial parse. May be null.
continueAfterException: The flag to indicate if the service should continue the parsing and processing after an exception is caught. Applies only to the initial parse. May be null.
preProcessCallbackFunc: The callback function being called before nodes are processed for a particular tag. Applies only to the initial parse. May be null.
postProcessCallbackFunc: The callback function being called after nodes are processed for a particular tag. Applies only to the initial parse. May be null.
}

onTagChanged

void onTagChanged(DOMNode domNode,
                  boolean continueAfterException,
                  com.ibm.mashups.livetext.CallbackModel.preProcessCallbackFunc preProcessCallbackFunc,
                  com.ibm.mashups.livetext.CallbackModel.postProcessCallbackFunc postProcessCallbackFunc)

Tag changed event handler. This handler will parse the passed in tag and all its children to be parsed.

Parameters:

domNode - The DOM node whose decendent nodes to be parsed and processed. May be null.

continueAfterException - The flag to indicate if the service should continue the parsing and processing after an exception is caught. If this parameter is missing, the default is false. May be null.

preProcessCallbackFunc - The callback function being called before a node being processed. May be null.

postProcessCallbackFunc - The callback function being called after the a node being processed. May be null.

onUnchangeTag

void onUnchangeTag(DOMNode node,
                   Boolean continueAfterException,
                   unknown preUnProcessCallback,
                   unknown postUnProcessCallback,
                   unknown unchangeCompleteCallback)

The event handler when a tag and/or its content should be removed.

Parameters:

node - the root node which will be parsed.

continueAfterException - a flag indicate if the process should continue when error occurrs.

preProcessCallback - the callback function which will be called before nodes being processed.

postProcessCallback - the callback function which will be called after nodes being processed.

postUnProcessCallbcak - the callback function which will be called after the content is unchanged.

onTagContentChanged

void onTagContentChanged(DOMNode domNode,
                         boolean continueAfterException,
                         com.ibm.mashups.livetext.CallbackModel.preProcessCallbackFunc preProcessCallbackFunc,
                         com.ibm.mashups.livetext.CallbackModel.postProcessCallbackFunc postProcessCallbackFunc)

Tag content changed event handler. This handle will parsed all the passed in tag content to be parsed.

Parameters:

domNode - The DOM node whose decendent nodes to be parsed and processed. May be null.

continueAfterException - The flag to indicate if the service should continue the parsing and processing after an exception is caught. If this parameter is missing, the default is false. May be null.

preProcessCallbackFunc - The callback function being called before a node being processed. May be null.

postProcessCallbackFunc - The callback function being called after the a node being processed. May be null.

onAddConfigEntry

void onAddConfigEntry(ConfigEntry entry,
                      boolean bFront)

The method allows component dynamically add a new configuration entry so that the service can start process the tags presented by the entry.

Parameters:

entry - The entry that should be added to the configuration. Must not be null.

bFront - The flag to indicate if the entry should be added to the front of the configuration array or not. true for front, false for end. Default is false for end.

onRemoveConfigEntry

void onRemoveConfigEntry(ConfigEntry entry)

This method allows components dynamically remove a configuration entry so that the service will not process that type of tags which are presented by the configuration entry.

Parameters:

entry - The entry that should be removed from the configuration. Must not be null.