com.tridion.tcdl

Class TagDispatcher

java.lang.Object

com.tridion.tcdl.TagDispatcher

All Implemented Interfaces:

TCDLParserEventListener

public final class TagDispatcher
extends Object
implements TCDLParserEventListener

Actual tag engine. Triggered by events from the TCDL parser this class will create, call and configure TagHandlers to let them process the TCDL based content.

Tags are associated with a (chain of) TagHandlers OR tags can be parameters to methods of parent TagHandlers. So for example if you have nested tags in a tag:

myNestedValue nested-1 nested-2 nested-3 nested-4

Suppose the tag "parent" is handled by a class:

class ParentTagHandler implements TagHandler { public void setNested(MyNestedObject object) { :: value .. }

public void setAttribute1(String value) { :: attribute1="value1" ... } ... }

The tag "nested" is mapped onto the method "setNested" (by name). The single parameter of this method indicates which object will be created (MyNestedObject) (using the default constructor or via a factory method defined on the class if it exists by the name createMyNestedObject).

class MyNestedObject { implements nothing specific to TCDL

public void addNested(MyNestedObject obj) { :: taglib:nested/taglib:nested/... list.add(obj); }

public void setRequiredAttr2(String value) { :: attr2="val2" ... }

public void setElementData(String tagBody) { :: >myNestedValue< ... } ... }

The element data of the "nested" tag, is set onto the MyNestedObject via a setElementData(string) method if it is present in the object. This process is recursive, e.g. another level of tags can be nested in the "nested" tags processed in the same way. To support multiple elements of the same name a method addNested can be used instead of setNested. This mechanism allows you to easily represent complex arguments for tags as POJOs.

A similar process occurs for attributes of tags: The attribute "attribute1" of the parent tag will be set via a method setAttribute1(String x) if the class ParentTagHandler has such a method. Similarly, the "attr2" attribute will be set on MyNestedObject if it defines a method called setAttr2(String val) or setRequiredAttr2(String val). Attributes are set immediately before doStartTag is called

Note that if a class defines methods in the form "setRequiredXXXX(..)", the engine checks that the attribute XXXX exists otherwise an error is thrown.

Note that when using nested tags as parameters the rules apply: - A parent must define a method either named set$TAGNAME(..) or add$TAGNAME(..) - The $TAGNAME may not have a registered TagHandler too. This will result in an error - Nested tags must be in the same namespace as their parents - The set$TAGNAME(..) or add$TAGNAME(..) is only called at the time the parent tag ends, just before doEndTag is called, so when these methods are called, the objects are fully initialized

Constructor Summary

Constructors

Constructor and Description
TagDispatcher(TransformContext context, OutputDocument target, TagHandlerRegistry registry) Constructs this TagDispatcher so it is ready for use as a TCDLParserEventListener with the TCDLParser It is not re-usable, e.g.

Method Summary

Modifier and Type	Method and Description
boolean	afterBody(Tag tag) Called by the TCDLParser if body of a Tag require reevaluation.
protected void	appendRenderedContentOf(TagDispatcher aDispatcher) Appends data to the current body.
int	calculateNameSpaces(Pattern pattern)
void	elementData(String data, boolean directlyAfterTag) Entry point called by TCDL parser for character data present between or before/after tcdl tags.
void	endDocument() Entry point called by TCDL parser right after finishing parsing the TCDL enabled content.
boolean	endTag(Tag tag) Entry point called by the TCDL Parser.
protected TagHandlerBase	getEnclosingTagHandler() Returns the TagHandler for the enclosing Tag of the currently active Tag in the processing Stack.
protected TagHandlerRegistry	getRegistry() Gets the cached TagHandlerRegistry.
protected boolean	isSkippingMode() Exposes if the parsing mechanism is currently skipping tags.
void	startDocument() Entry point called by the TCDL Parser just before it starts parsing
boolean	startTag(Tag tag) Entry point called by the TCDL Parser.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TagDispatcher

public TagDispatcher(TransformContext context,
                     OutputDocument target,
                     TagHandlerRegistry registry)

Constructs this TagDispatcher so it is ready for use as a TCDLParserEventListener with the TCDLParser It is not re-usable, e.g. after one run in the TCDLParser it should be discarded.

Parameters:

context - An initialized TransformContext that will be used throughout the entire process.

target - The output document that will used throughout the entire process.

registry - Registry that will be used to look up TagHandlers

Method Detail

startDocument

public void startDocument()
                   throws TCDLTransformerException

Entry point called by the TCDL Parser just before it starts parsing

Prepare for processing by clearing the tagStack and pushing a default TagHandler onto it, that acts as the Root TagHandler surrounding the entire TCDL content.

Specified by:

startDocument in interface TCDLParserEventListener

Throws:

TCDLTransformerException - if the processing cannot continue for some reason.

TCDLTransformerException

startTag

public boolean startTag(Tag tag)
                 throws TCDLTransformerException

Entry point called by the TCDL Parser. Handles the start of a new tag

Specified by:

startTag in interface TCDLParserEventListener

Parameters:

tag - Fully initialized tag as it is encountered by the parser

Returns:

false if the tag is not processed at all because nothing is configured to handle it.

Throws:

TCDLTransformerException - whenever an error occurs in processing the tag

TCDLTransformerException

endTag

public boolean endTag(Tag tag)
               throws TCDLTransformerException

Entry point called by the TCDL Parser. Handles the ending of a tag

Specified by:

endTag in interface TCDLParserEventListener

Parameters:

tag - Fully initialized tag as it is encountered by the parser. Note that it will not have the attributes of the start tag.

Returns:

false if the tag is not processed at all because nothing is configured to handle it.

Throws:

TCDLTransformerException - whenever an error occurs in processing the tag

TCDLTransformerException

elementData

public void elementData(String data,
                        boolean directlyAfterTag)

Entry point called by TCDL parser for character data present between or before/after tcdl tags.

Specified by:

elementData in interface TCDLParserEventListener

Parameters:

data - the element data between tcdl tags

directlyAfterTag - when true the parser found this data right after a valid tcdl tag. This helps deciding if whitespace should be stripped

endDocument

public void endDocument()
                 throws TCDLTransformerException

Entry point called by TCDL parser right after finishing parsing the TCDL enabled content. A final check if the correct sequence of tags occurred (e.g. no open tags left) and the final body is set on the OutputDocument

Specified by:

endDocument in interface TCDLParserEventListener

Throws:

TCDLTransformerException - if the processing should not continue for some reason.

TCDLTransformerException

getEnclosingTagHandler

protected TagHandlerBase getEnclosingTagHandler()
                                         throws TCDLTransformerException

Returns the TagHandler for the enclosing Tag of the currently active Tag in the processing Stack.

In case of tag that does not contain any tag, it returns default tag handler. For iteration tag, it returns enclosing Tag's handler.

Returns:

TagHandlerBase associated with the enclosing Tag.

Throws:

TCDLTransformerException - If enclosing Tag does not support TagHandler

TCDLTransformerException

calculateNameSpaces

public int calculateNameSpaces(Pattern pattern)

afterBody

public boolean afterBody(Tag tag)
                  throws TCDLTransformerException

Description copied from interface: TCDLParserEventListener

Called by the TCDLParser if body of a Tag require reevaluation. It is specially applicable in the context where a TagHandler supports iteration, that is, it implements IterationTagSupport. If reevaluation is not needed, then just return false.

Specified by:

afterBody in interface TCDLParserEventListener

Throws:

TCDLTransformerException - if the processing should not continue for some reason.

TCDLTransformerException

appendRenderedContentOf

protected void appendRenderedContentOf(TagDispatcher aDispatcher)
                                throws TCDLTransformerException

Appends data to the current body.

Throws:

TCDLTransformerException - Thrown if no current body is available.

TCDLTransformerException

getRegistry

protected TagHandlerRegistry getRegistry()

Gets the cached TagHandlerRegistry.

Returns:

The TagHandlerRegistry cached by this dispatcher

isSkippingMode

protected boolean isSkippingMode()
                          throws TCDLTransformerException

Exposes if the parsing mechanism is currently skipping tags.

Returns:

true if the parsing mechanism is currently skipping tags, false otherwise.

Throws:

TCDLTransformerException - Thrown if the there are no tags left on the stack.

TCDLTransformerException