Component Templates
| Wiki Markup |
|---|
{float:right}
{info:title=Related Articles}
* [Templating and Markup FAQ|Templating and Markup]
* [Component Classes]
{info}
{float} |
Under Tapestry, component templates are files a component template is a file associated with a page or component classes class that contain contains the markup for the component, along with any embedded components.the component.
Component In a change from Tapestry 4, under Tapestry 5, component templates are well formed XML documents. That means that every open tag must have a matching close tag, every attribute must be quoted, and so forth.
...
We'll cover the specific content of templates shortly, first a few details about connecting a component to its template.
Template Location
Component templates are stored with the component class file. The files have a ".tml" extension (i.e., _T_apestry _M_arkup _L_anguage), and are stored in the same package as corresponding component class.
...
| Note |
|---|
Tapestry actually creates multiple names for the name page: address/Create and address/CreateAddress are both synonymous. You can user either in Java code that refers to a page by name, or as the page parameter of a PageLink. |
Template Localization
Main Article: Localization
Templates are Templates are localized in much the same way as individual files of a component's message catalog: the effective locale is inserted into the name of the file. Thus a German users will see the content generated from MyPage_de.tml and French users will see content generated from MyPage_fr.tml. When no specific localization is available, the default location (MyPage.tml) is used.
| Warning |
|---|
It is necessary to enable support for a locale before Tapestry will attempt to localize to that locale. This requires configuration in your application module; if you are using the Tapestry quickstart Quickstart archetype, only locale "en" will be enabled by default. |
Template Inheritance
If a component does not have a template, but extends from a component class that does have a template, then the parent class' template will be used by the child component.
...
by default. |
Template Doctypes
As mentioned above, component templates are well-formed XML documents. This means that if you want to use any HTML entities (such as \& \ < > or ©), you must use an HTML or XHTML doctype in your template. If you choose to use (X)HTML doctypes in your templates, they will be passed on to the client in the resultant (X)HTML. Note that if your pages are composed of multiple components, each with a template, and each template contains a doctype declaration, only the first doctype encountered by the template parser will be passed on to the client.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
Tapestry Namespace
Component templates should include the Tapestry namespace, defining it in the root element of the template.
...
- <t:remove>
- <t:content>
- <t:extension-point>
- <t:extend>
- <t:replace>
Tapestry Elements
Tapestry elements are elements defined using the Tapestry namespace prefix.
...
There are a certain number of Tapestry elements that act as template directives; beyond that, any element in the Tapestry namespace will be a Tapestry component.
<t:body>
In many cases, a component is designed to integrate its template with its container's template.
...
| Note |
|---|
Tapestry 4 users will recognize the <t:body> element as a replacement for the RenderBody component. |
<t:container>
A <t:container> element contains markup without being considered part of the template. This is useful for components that render several top level tags, for example, a component that renders several columns within a table row:
...
Without the <t:container> element, there would be no way to create a valid XML document as the template, because XML documents must always have a single root element.
<t:block>
A <t:block> is a container of a portion of the component template. A block does not normally render; any component or contents you put inside a block will not ordinarily be rendered. However, by injecting the block you have precise control over when and if the content renders.
A block may be anonymous, or it may have an id (specified with the id attribute). Non-anonymous blocks may be be injected into the component.
...
Ids must be valid Java identifiers: start with a letter, and contain only letters, numbers and underscores.
<t:parameter>
A <parameter> element is a special kind of block. It is placed inside the body of an embedded component. The block defined by the <parameter> is passed to the component. <parameter> includes a mandatory name attribute to identify which parameter of the component to bind.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<t:if test="loggedIn">
Hello, ${userName}!
<t:parameter name="else">
Click <a t:type="actionlink" t:id="login">here</a> to log in.
</t:parameter>
</t:if>
|
| Warning |
|---|
The |
<t:content>
Marks a portion of the template as the actual template content; any markup outside the <t:content> element is ignored. This is useful for eliminating portions of the template that exist to support WYSIWYG preview of the template.
...
Support for the <t:content> element was adding in Tapestry release 5.1. You must use the http://tapestry.apache.org/schema/tapestry_5_1_0.xsd namespace URI for content to be recognized (otherwise you will see an error about a missing "content" component).
<t:remove>
Marks a portion of the template for removal; it is as if the remove element and everything inside it simply was not part of the template. This is used as a kind of server-side only comment (normal HTML/XML comments are included in a page render response), or to temporarily eliminate a portion of the template. As far as Tapestry is concerned, the contents of the <remove> element do not exist (including validating consistency between components defined or injected in the Java class and the template).
Support for the <t:remove> element was adding in Tapestry release 5.1. You must use the http://tapestry.apache.org/schema/tapestry_5_1_0.xsd namespace URI for remove to be recognized (otherwise you will see an error about a missing "remove" component).
Expansions
Another option when rendering output is the use of expansions. Expansions are special strings that may be embedded in template bodies, and borrow some syntax from the Ant build tool.
...
Under the covers, expansions are the same as parameter bindings. The default binding prefix for expansions is "prop:" (that is, the name of a property or a a property expression), but other binding prefixes are useful, especially "message:" (to access a localized message from the component's message catalog).
| Note |
|---|
Tapestry 4 users will note that expansions are a concise, easy replacement for the Insert component, and for the <span key="..."> directive. |
Component Elements
An embedded component is identified within the template as an element in the t: namespace. Example:
...
Any other attributes are used to to bind parameters of the component. These may be formal parameters or informal parameters. Formal parameters will have a default binding prefix (usually "prop:"). Informal parameters will be assumed to be literals (i.e., the "literal:" binding prefix).
...
| Note |
|---|
When using a component library, the library will map its components to a virtual subfolder of the application. The same naming mechanism works whether its is a real sub-folder or a component library sub-folder. |
Library Namespaces
If you are using many components from a common Tapestry component library, you can use a special namespace to simplify references to those components.
...
In other words, the virtual folder, ajax, defined in the namespace URI takes the place of the path prefixes ajax. seen in the first element, or ajax/ seen in the second. As far as Tapestry is concerned, they are all equivalent.
Invisible Instrumentation
A favorite feature of Tapestry 4 is was invisible instrumentation, the ability to mark ordinary HTML elements as components. Invisible instrumentation leads to more concise templates that are also more readable.
...
Here, the loop component "merges into" the <tr> element. It will render out a <tr> for each item object in the items list. It will write a dynamic class attribute into each <tr>.
Parameter Namespace
Parameter namespaces are a new feature introduced in Tapestry 5.1. They are a more concise way of passing parameter blocks to components.
...
Name-spaced parameter elements are not allowed to have any attributes. The element name itself is used to identify the parameter of the component to bind.
Whitespace in Templates
Tapestry strips out unnecessary whitespace from templates as they are parsed. Inside any block of text, repeated whitespace is reduced to a single space character. Blocks of text that are entirely whitespace, such a line break and whitespace between two tags, is eliminated entirely.
...
You can even put further xml:space attributes inside nested elements to fine-tune the control over what whitespace is preserved and what is compressed.
Template Inheritance
If a component does not have a template, but extends from a component class that does have a template, then the parent class' template will be used by the child component.
This allows a component to extend from a base class but not have to duplicate the base class' template.
Tapestry 5.1 adds a significant new feature: template inheritance with extension points. Previously, a component which extended another component had to inherit the parent component's entire template, or copy-and-paste the template.
...
| Warning |
|---|
Overuse of this feature is not recommended: in general use of composition, rather than inheritance, will be easier to understand and maintain. There are certain specific cases where overrides will allow a for much wider and easier reuse of a component, but the component needs to be carefully designed to support this kind of inheritance properly. |
<t:extension-point>
Marks a point in a template that may be replaced. A unique id (case insensitive) is used in the template and its sub-templates to link extension points to possible overrides.
| Code Block | ||||
|---|---|---|---|---|
| ||||
<t:extension-point id="title">
<h1>${defaultTitle}</h1>
</t:extension-point>
|
<t:extend>
Root element of a child template that extends from its parent template. The <t:extend> attribute may only appear as the root element and may only contain <t:replace> elements.
<t:replace>
Replaces an extension point from a parent template. <t:replace> may only appear as the immediate child of a root <t:extend> element.
...