Under Tapestry, a component template is the a file that contains the markup for that page or a component.
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.
For the most part, these templates are standard HTML/XHTML; Tapestry extensions to ordinary markup are provided in the form of a Tapestry namespace:
<html t:type="layout" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd"> <h1>Hello World</h1> </html>
We'll cover the specific content of templates shortly, but first a few details about connecting a component to its template.
Component templates are stored with the component class file. The files have A component template shares the same name as its corresponding class file, but with a ".tml" extension ending (i.e., Tapestry Markup Language Tapestry Markup Language), and are is stored in the same package as the corresponding component class.
Under a typical Maven directory structure, the Java class and template files for a component might be:
Likewise, the Java class and template files for a page might be:
The template and the compiled class will be packaged together in the WEB-INF/classes folder of the application WAR.
For pages (but not other components), a second location will be searched: in the web application context. The location is based on the logical name of the page, in the previous example, the template would be
MyPage.tml in the root folder of the web application.
Main Article: Localization
Templates are handled 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.
As mentioned above, component templates are well-formed XML documents. This means that if you want to use any Named HTML entities (such as \& \ < > ©& < > ©), you must use an HTML or XHTML doctype in your template (starting in 5.3, this is more-or-less automatic, see notes below). 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.
It should also be noted that even though *X*HTML DTDs are valid XML DTDs, HTML DTDs aren't. This means that HTML doctypes cannot be used by XML parsers. Tapestry works around this limitation internally by using XHTML DTDs to parse templates that use HTML DTDs. This internal mapping is possible because XHTML 1.0 is nothing more than "a reformulation of the three HTML 4 document types as applications of XML 1.0," as per the W3C. Don't worry though – the original HTML 4 doctype will still be emitted to the client!
The following doctypes are the most common (X)HTML doctypes:
<!DOCTYPE html> <!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"> <!DOCTYPE html>
The first one is for HTML5 and only works in is recommended for Tapestry 5.2.5 and later versions. In earlier versionsversions prior to Tapestry 5.2.5, Tapestry didn't support the HTML5 doctype directly (see TAP5-1040), but there's a partial work-around: just add the following to your page class (or your layout class, if you use one) instead of adding the doctype to your template (.tml) files:
Note that expansions escape any HTML reserved characters. Specifically, any less-than (<), greater than (>) and ampersand (&) are replaced with <, > <, > and & amp; respectively. That is usually what you want. However, if your property contains HTML that you want rendered as raw markup, you can use the OutputRaw component instead, like this:
<t:OutputRaw value="someContent"/> where
someContent is a property containing HTML markup.
Caution: if the content comes from an untrusted source (like a public user), be sure to filter it before providing it to OutputRaw. Otherwise you've got a potential cross-site scripting vulnerability.
An embedded component is identified within the template as an element in the t: namespace. Example:
Embedded components may have two Tapestry-specific parameters:
- id: A unique id for the component (within its container).
- mixins: An optional comma separated list of mixins for the the component.
Main Article: Component Parameters
Parameter namespaces are a new feature (introduced in Tapestry 5.1. They ) are a more concise way of passing parameter blocks to components.
You must define a special namespace, usually given with the prefix "p":
<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd" xmlns:p="tapestry:parameter"> . . .
This example passes a block of the template (containing the ActionLink component and some text) to the If component as parameter
else. In the If component's reference page you'll see that
else is parameter of type Block.
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.