org.apache.tapestry.parse
Class TemplateParser

java.lang.Object
  |
  +--org.apache.tapestry.parse.TemplateParser

public class TemplateParser
extends Object

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.

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.

Version:
$Id: TemplateParser.java,v 1.11 2003/06/01 05:05:11 hlship Exp $
Author:
Howard Lewis Ship

Field Summary
static String IMPLICIT_ID_PATTERN
          Pattern used to recognize implicit components (whose type is defined in the template).
static String JWCID_ATTRIBUTE_NAME
          Attribute used to identify components.
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 LOCALIZATION_KEY_PREFIX
          Attribute value prefix indicating that the attribute is a localization key.
static String OGNL_EXPRESSION_PREFIX
          Attribute value prefix indicating that the attribute is an OGNL expression.
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  ILocation getCurrentLocation()
          Gets the current location within the file.
 TemplateToken[] parse(char[] templateData, ITemplateParserDelegate delegate, IResourceLocation resourceLocation)
          Parses the template data into an array of TemplateTokens.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

OGNL_EXPRESSION_PREFIX

public static final String OGNL_EXPRESSION_PREFIX
Attribute value prefix indicating that the attribute is an OGNL expression.

Since:
3.0
See Also:
Constant Field Values

LOCALIZATION_KEY_PREFIX

public static final String LOCALIZATION_KEY_PREFIX
Attribute value prefix indicating that the attribute is a localization key.

Since:
3.0
See Also:
Constant Field Values

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

JWCID_ATTRIBUTE_NAME

public static final String JWCID_ATTRIBUTE_NAME
Attribute used to identify components.

Since:
2.3
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.

Since:
3.0
See Also:
Constant Field Values
Constructor Detail

TemplateParser

public TemplateParser()
Method Detail

parse

public TemplateToken[] parse(char[] templateData,
                             ITemplateParserDelegate delegate,
                             IResourceLocation 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.

Parameters:
templateData - the HTML template to parse. Some tokens will hold a reference to this array.
delegate - object that "knows" about defined components
TemplateParseException

getCurrentLocation

protected ILocation 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