org.apache.tapestry.parse
Class TemplateParser

java.lang.Object
  org.apache.tapestry.parse.TemplateParser

All Implemented Interfaces:

ITemplateParser

public class TemplateParser
extends Object
implements ITemplateParser

Parses Tapestry templates, breaking them into a series of tokens. Although often referred to as an "HTML template", there is no real requirement that the template be HTML. This parser can handle any reasonable SGML derived markup (including XML), but specifically works around the ambiguities of HTML reasonably.

Deployed as the tapestry.parse.TemplateParser service, using the threaded model.

Dynamic markup in Tapestry attempts to be invisible. Components are arbitrary tags containing a jwcid attribute. Such components must be well balanced (have a matching close tag, or end the tag with "/>".

Generally, the id specified in the template is matched against an component defined in the specification. However, implicit components are also possible. The jwcid attribute uses the syntax "@Type" for implicit components. Type is the component type, and may include a library id prefix. Such a component is anonymous (but is given a unique id).

(The unique ids assigned start with a dollar sign, which is normally no allowed for component ids ... this helps to make them stand out and assures that they do not conflict with user-defined component ids. These ids tend to propagate into URLs and become HTML element names and even JavaScript variable names ... the dollar sign is acceptible in these contexts as well).

Implicit component may also be given a name using the syntax " componentId:@Type". Such a component should not be defined in the specification, but may still be accessed via IComponent.getComponent(String).

Both defined and implicit components may have additional attributes defined, simply by including them in the template. They set formal or informal parameters of the component to static strings. IComponentSpecification.getAllowInformalParameters(), if false, will cause such attributes to be simply ignored. For defined components, conflicting values defined in the template are ignored.

Attributes in component tags will become formal and informal parameters of the corresponding component. Most attributes will be

The parser removes the body of some tags (when the corresponding component doesn't allow a body, and allows portions of the template to be completely removed.

The parser does a pretty thorough lexical analysis of the template, and reports a great number of errors, including improper nesting of tags.

The parser supports invisible localization: The parser recognizes HTML of the form: <span key="value"> ... </span> and converts them into a TokenType.LOCALIZATION token. You may also specifify a raw attribute ... if the value is true, then the localized value is sent to the client without filtering, which is appropriate if the value has any markup that should not be escaped.

Author:

Howard Lewis Ship, Geoff Longman

Field Summary

static String	IMPLICIT_ID_PATTERN Pattern used to recognize implicit components (whose type is defined in the template).
static String	LOCALIZATION_KEY_ATTRIBUTE_NAME The attribute, checked for in <span> tags, that signfies that the span is being used as an invisible localization.
static String	PROPERTY_NAME_PATTERN
static String	RAW_ATTRIBUTE_NAME Used with LOCALIZATION_KEY_ATTRIBUTE_NAME to indicate a string that should be rendered "raw" (without escaping HTML).
static String	SIMPLE_ID_PATTERN Pattern used to recognize ordinary components (defined in the specification).

Constructor Summary

TemplateParser()

Method Summary

protected void	afterParse() Perform default cleanup after parsing completes.
protected void	attributeBeginEvent(String attributeName, int startLine, int cursorPosition) Notify that the beginning of an attribute value has been detected.
protected void	attributeEndEvent(int cursorPosition) Notify that the end of the current attribute value has been detected.
protected void	beforeParse(char[] templateData, ITemplateParserDelegate delegate, org.apache.hivemind.Resource resourceLocation) perform default initialization of the parser.
protected String	findValueCaselessly(String key, Map map) Searches a Map for given key, caselessly.
protected org.apache.hivemind.Location	getCurrentLocation() Gets the current location within the file.
protected List	getTokens() Give subclasses access to the parse results.
protected void	parse()
TemplateToken[]	parse(char[] templateData, ITemplateParserDelegate delegate, org.apache.hivemind.Resource resourceLocation) Parses the template data into an array of TemplateTokens.
void	setFactory(TemplateTokenFactory factory)
protected void	tagBeginEvent(int startLine, int cursorPosition) Notify that the beginning of a tag has been detected.
protected void	tagEndEvent(int cursorPosition) Notify that the end of the current tag has been detected.
protected void	templateParseProblem(org.apache.hivemind.ApplicationRuntimeException exception, int line, int cursor) Used by the parser to report tapestry runtime specific problems in the parse.
protected void	templateParseProblem(String message, org.apache.hivemind.Location location, int line, int cursor) Used by the parser to report problems in the parse.

Methods inherited from class java.lang.Object

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

Field Detail

LOCALIZATION_KEY_ATTRIBUTE_NAME

public static final String LOCALIZATION_KEY_ATTRIBUTE_NAME

The attribute, checked for in <span> tags, that signfies that the span is being used as an invisible localization.

Since:

2.0.4

See Also:

Constant Field Values

RAW_ATTRIBUTE_NAME

public static final String RAW_ATTRIBUTE_NAME

Used with LOCALIZATION_KEY_ATTRIBUTE_NAME to indicate a string that should be rendered "raw" (without escaping HTML). If not specified, defaults to "false". The value must equal "true" (caselessly).

Since:

2.3

See Also:

Constant Field Values

PROPERTY_NAME_PATTERN

public static final String PROPERTY_NAME_PATTERN

See Also:

Constant Field Values

SIMPLE_ID_PATTERN

public static final String SIMPLE_ID_PATTERN

Pattern used to recognize ordinary components (defined in the specification).

Since:

3.0

See Also:

Constant Field Values

IMPLICIT_ID_PATTERN

public static final String IMPLICIT_ID_PATTERN

Pattern used to recognize implicit components (whose type is defined in the template). Subgroup 1 is the id (which may be null) and subgroup 2 is the type (which may be qualified with a library prefix). Subgroup 4 is the library id, Subgroup 5 is the simple component type, which may (as of 4.0) have slashes to delinate folders containing the component.

Since:

3.0

See Also:

Constant Field Values

Constructor Detail

TemplateParser

public TemplateParser()

Method Detail

parse

public TemplateToken[] parse(char[] templateData,
                             ITemplateParserDelegate delegate,
                             org.apache.hivemind.Resource resourceLocation)
                      throws TemplateParseException

Parses the template data into an array of TemplateTokens.

The parser is decidedly not threadsafe, so care should be taken that only a single thread accesses it.

Specified by:

parse in interface ITemplateParser

Parameters:

templateData - the HTML template to parse. Some tokens will hold a reference to this array.

delegate - object that "knows" about defined components

resourceLocation - a description of where the template originated from, used with error messages.

Throws:

TemplateParseException

beforeParse

protected void beforeParse(char[] templateData,
                           ITemplateParserDelegate delegate,
                           org.apache.hivemind.Resource resourceLocation)

perform default initialization of the parser.

afterParse

protected void afterParse()

Perform default cleanup after parsing completes.

templateParseProblem

protected void templateParseProblem(String message,
                                    org.apache.hivemind.Location location,
                                    int line,
                                    int cursor)
                             throws TemplateParseException

Used by the parser to report problems in the parse. Parsing must stop when a problem is reported.

The default implementation simply throws an exception that contains the message and location parameters.

Subclasses may override but must ensure they throw the required exception.

Parameters:

message -

location -

line - ignored by the default impl

cursor - ignored by the default impl

Throws:

TemplateParseException - always thrown in order to terminate the parse.

templateParseProblem

protected void templateParseProblem(org.apache.hivemind.ApplicationRuntimeException exception,
                                    int line,
                                    int cursor)

Used by the parser to report tapestry runtime specific problems in the parse. Parsing must stop when a problem is reported.

The default implementation simply rethrows the exception.

Subclasses may override but must ensure they rethrow the exception.

Parameters:

exception -

line - ignored by the default impl

cursor - ignored by the default impl

Throws:

org.apache.hivemind.ApplicationRuntimeException - always rethrown in order to terminate the parse.

getTokens

protected List getTokens()

Give subclasses access to the parse results.

parse

protected void parse()
              throws TemplateParseException

Throws:

TemplateParseException

tagBeginEvent

protected void tagBeginEvent(int startLine,
                             int cursorPosition)

Notify that the beginning of a tag has been detected.

Default implementation does nothing.

tagEndEvent

protected void tagEndEvent(int cursorPosition)

Notify that the end of the current tag has been detected.

Default implementation does nothing.

attributeBeginEvent

protected void attributeBeginEvent(String attributeName,
                                   int startLine,
                                   int cursorPosition)

Notify that the beginning of an attribute value has been detected.

Default implementation does nothing.

attributeEndEvent

protected void attributeEndEvent(int cursorPosition)

Notify that the end of the current attribute value has been detected.

Default implementation does nothing.

findValueCaselessly

protected String findValueCaselessly(String key,
                                     Map map)

Searches a Map for given key, caselessly. The Map is expected to consist of Strings for keys and values. Returns the value for the first key found that matches (caselessly) the input key. Returns null if no value found.

getCurrentLocation

protected org.apache.hivemind.Location getCurrentLocation()

Gets the current location within the file. This allows the location to be created only as needed, and multiple objects on the same line can share the same Location instance.

Since:

3.0

setFactory

public void setFactory(TemplateTokenFactory factory)