Modified: websites/production/tapestry/content/component-rendering.html
==============================================================================
--- websites/production/tapestry/content/component-rendering.html (original)
+++ websites/production/tapestry/content/component-rendering.html Sat Feb 3
16:21:22 2018
@@ -27,6 +27,16 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css'
rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet'
type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushPlain.js'
type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,7 +77,86 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Rendering of
components</strong> in Tapestry 5 is based on a <em>state machine</em> and a
<em>queue</em> (instead of the tail recursion used in Tapestry 4). This breaks
the rendering process up into tiny pieces that can easily be implemented or
overridden. Don't worry, in practice, writing components requires a
breathtakingly small amount of code.</p><parameter
ac:name="style">float:right</parameter><parameter ac:name="title">Related
Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label in
("request-processing","rendering") and space =
currentSpace()</parameter></rich-text-body><h2
id="ComponentRendering-RenderingPhases">Rendering Phases</h2><p>The rendering
of each component is divided into a number of phases, illustra
ted below.</p><p><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image"
src="component-rendering.data/tapestry_render_phases.png"></span><br
clear="none"> Each of the orange phases (SetupRender, BeginRender,
BeforeRenderBody, etc.) corresponds to an annotation you may place on one or
more methods of your class. The annotation directs Tapestry to invoke your
method as part of that phase.</p><p>Methods marked with these annotations are
called <strong>render phase methods</strong>.</p><p>Your methods may be void,
or return a boolean value. Returning a value can force phases to be skipped, or
even be re-visited. In the diagram, solid lines show the normal processing
path. Dashed lines are alternate flows that are triggered when your render
phase methods return false instead of true (or void).</p><p>Render phase
methods may take no parameters, or may take a parameter of type <a
href="dom.html">MarkupWriter</a>. The methods can have any visibility you like
... typically, package private is used, as this visibility makes it possible
to unit test your code (from within the same Java package) without making the
methods part of the component's <em>public</em> API.</p><p>All Render phase
methods are <em>optional</em>; a default behavior is associated with each
phase.</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th
colspan="1" rowspan="1" class="confluenceTh"><p>Annotation</p></th><th
colspan="1" rowspan="1" class="confluenceTh"><p>Method Name</p></th><th
colspan="1" rowspan="1" class="confluenceTh"><p>When
Called</p></th></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SetupRender.html";>@SetupRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>setupRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>When initial setup actions, if
any, are needed
</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender";>@BeginRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>beginRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>When Tapestry is ready for the
component's start tag, if any, to be rendered</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderTemplate";>@BeforeRenderTemplate</a></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p>beforeRenderTemplate()</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Before Tapestry renders the component's
template, if any</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/
apidocs/org/apache/tapestry5/annotations/BeforeRenderBody">@BeforeRenderBody</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>beforeRenderBody()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Before Tapestry renders the
body of the component, if any</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderBody";>@AfterRenderBody</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>afterRenderBody()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>After Tapestry renders the body
of the component, if any, but before the rest of the component's template is
rendered</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderTemplate";>@AfterRenderTemplate</a></p></td><td
colspan="1" r
owspan="1" class="confluenceTd"><p>afterRenderTemplate()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>After Tapestry finishes
rendering the component's template, if any</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRender";>@AfterRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>afterRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>After Tapestry has finished
rendering both the template and body of the component</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><strong><a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/CleanupRender";>@CleanupRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>cleanupRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>When fina
l cleanup actions, if any, are
needed</p></td></tr></tbody></table></div><p>The large number of phases
reflects the need for precise control of components from <a
href="component-mixins.html">component mixins</a>. Several of the phases exist
almost exclusively for mixins.</p><p>Generally, your code will use the
SetupRender, BeginRender, AfterRender and CleanupRender phases ... often just
one or two of those.</p><h2 id="ComponentRendering-AnExample">An
Example</h2><p>Here's the source for a looping component that counts up or down
between two values, renders its body a number of times, and stores the current
index value in a parameter:</p><parameter
ac:name="">java</parameter><plain-text-body>package org.example.app.components;
+ <div id="ConfluenceContent"><p><strong>Rendering of
components</strong> in Tapestry 5 is based on a <em>state machine</em> and a
<em>queue</em> (instead of the tail recursion used in Tapestry 4). This breaks
the rendering process up into tiny pieces that can easily be implemented or
overridden. Don't worry, in practice, writing components requires a
breathtakingly small amount of code.</p><div class="aui-label"
style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="content-type-and-markup.html">Content Type
and Markup</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="page-navigation.html">Page Navigation</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="page-life-cycle.html">Page Life Cycle</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="component-rendering.html">Component
Rendering</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="component-events.html">Component Events</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="component-events-faq.html">Component Events
FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="request-processing.html">Request
Processing</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<h2 id="ComponentRendering-RenderingPhases">Rendering Phases</h2><p>The
rendering of each component is divided into a number of phases, illustrated
below.</p><p><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image confluence-external-resource"
src="https://cwiki-test.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2";
data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2";></span><br
clear="none"> Each of the orange phases (SetupRender, BeginRender,
BeforeRenderBody, etc.) corresponds to an annotation you may place on one or
more methods of your class. The annotation directs Tapestry to invoke your
method as part of that phase.</p><p>Methods marked with these annotations are
called <strong>render phase methods</strong>.</p><p>Your methods may be void,
or r
eturn a boolean value. Returning a value can force phases to be skipped, or
even be re-visited. In the diagram, solid lines show the normal processing
path. Dashed lines are alternate flows that are triggered when your render
phase methods return false instead of true (or void).</p><p>Render phase
methods may take no parameters, or may take a parameter of type <a
href="component-rendering.html">MarkupWriter</a>. The methods can have any
visibility you like ... typically, package private is used, as this visibility
makes it possible to unit test your code (from within the same Java package)
without making the methods part of the component's <em>public</em>
API.</p><p>All Render phase methods are <em>optional</em>; a default behavior
is associated with each phase.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Annotation</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Method Name</p></th><th colspan
="1" rowspan="1" class="confluenceTh"><p>When Called</p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><strong><a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SetupRender.html";>@SetupRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>setupRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>When initial setup actions, if
any, are needed</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender";>@BeginRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>beginRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>When Tapestry is ready for the
component's start tag, if any, to be rendered</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><a class="external-link" href
="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderTemplate";>@BeforeRenderTemplate</a></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p>beforeRenderTemplate()</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Before Tapestry renders the component's
template, if any</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderBody";>@BeforeRenderBody</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>beforeRenderBody()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Before Tapestry renders the
body of the component, if any</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderBody";>@AfterRenderBody</a></p></td><td
colspan="1" rowspan="1" class=
"confluenceTd"><p>afterRenderBody()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>After Tapestry renders the body of the component, if
any, but before the rest of the component's template is
rendered</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderTemplate";>@AfterRenderTemplate</a></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p>afterRenderTemplate()</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>After Tapestry finishes rendering the
component's template, if any</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRender";>@AfterRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>afterRender()</p></td><td
colspan="1" rowspan="1" class="confluence
Td"><p>After Tapestry has finished rendering both the template and body of the
component</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/CleanupRender";>@CleanupRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>cleanupRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>When final cleanup actions, if
any, are needed</p></td></tr></tbody></table></div><p>The large number of
phases reflects the need for precise control of components from <a
href="component-rendering.html">component mixins</a>. Several of the phases
exist almost exclusively for mixins.</p><p>Generally, your code will use the
SetupRender, BeginRender, AfterRender and CleanupRender phases ... often just
one or two of those.</p><h2 id="ComponentRendering-AnExample">An
Example</h2><p>Here's the source for a looping component that counts up or
down between two values, renders its body a number of times, and stores the
current index value in a parameter:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package org.example.app.components;
import org.apache.tapestry5.annotations.Parameter;
import org.apache.tapestry5.annotations.AfterRender;
@@ -121,11 +210,11 @@ public class Count
return true;
}
}
-</plain-text-body><p>Returning false from next() causes Tapestry to re-run the
BeginRender phase, and from there, re-render the component's body (this
component does not have a template). Returning true transitions to the
CleanupRender phase.</p><p>Notice how Tapestry adapts to your methods, as
marked with the annotations. It also adapts in terms of parameters; the two
annotated methods here did not perform any output, so they did not need a
MarkupWriter.</p><p>What's really mind blowing is that the template and body of
a component will often contain ... more components! That means that many
different components will be in different phases of their own state
machine.</p><h2 id="ComponentRendering-RenderPhasesinDetail">Render Phases in
Detail</h2><p><plain-text-body>{float:right|background=#eee|width=50%}
-{note}
-The SetupRender phase, like all render phases, occurs once for each rendering
of the component. If the component is inside a looping component
([Loop|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Loop.html],
[Grid|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Grid.html],
etc.), then the SetupRender method will be called once for _each_ iteration of
the loop.
-{note}
-{float}</plain-text-body></p><h3
id="ComponentRendering-SetupRender">SetupRender</h3><p>The SetupRender phase
(see @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SetupRender.html";>SetupRender</a>)
is where you can perform any one-time per-render setup for your component.
This is a good place to read component parameters and use them to set temporary
instance variables.</p><h3
id="ComponentRendering-BeginRender">BeginRender</h3><p>The BeginRender phase
(see @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender.html";>BeginRender</a>)
occurs at the start of the rendering of the component. For components that
render a tag, the start tag should be rendered here (the close tag should be
rendered inside the AfterRender phase). The component can also prevent the
template and/or body from being rendered by returning false.</p><p>Components
may or may not have a tem
plate. If a component has a template, and the template includes a <body>
element, then the BeforeRenderBody phase will be triggered (giving the
component the option of rendering its body or not).</p><p>If a component does
not have a <body> element in its template, then the BeforeRenderBody
phase is not triggered.</p><p>If a component does not have a template, but does
have a body, the BeforeRenderBody phase is still triggered.</p><p>If no methods
are annotated with BeginRender, then no special output occurs during this
phase, but the template (if present) or body (if no template is present, but
the component has a body) will be rendered.</p><h3
id="ComponentRendering-BeforeRenderTemplate">BeforeRenderTemplate</h3><p>The
BeforeRenderTemplate phase (see @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderTemplate.html";>BeforeRenderTemplate</a>)
exists to allow a component to decorate its template (creatin
g markup around the template generated markup), or to allow a component to
skip its template.</p><h3
id="ComponentRendering-BeforeRenderBody">BeforeRenderBody</h3><p>The
BeforeRenderBody phase (see @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderBody.html";>BeforeRenderBody</a>)
is associated with a component's body (the portion of its container's template
that the component occupies). The BeforeRenderBody phase allows the component
the ability to skip the body, while still rendering the rest of the component's
template (if any).</p><p>If no methods are annotated with BeforeRenderBody,
then the body will be rendered by default. Again, this occurs when the
<body> element of the component's template is reached, or automatically
if the component has no template (but the component does have a body).</p><h3
id="ComponentRendering-AfterRenderBody">AfterRenderBody</h3><p>The
AfterRenderBody phase (see @<a class=
"external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderBody.html";>AfterRenderBody</a>)
is executed after the body is rendered; this only occurs for components with a
body.</p><h3 id="ComponentRendering-AfterRender">AfterRender</h3><p>The
AfterRender phase (see @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRender.html";>AfterRender</a>)
complements BeginRender, and is often used to render the close tag that
matches the start tag rendered in the BeginRender phase. In any case, the
AfterRender phase can continue on to CleanupRender, or revert back to
BeginRender (as in our Count component example, above).</p><p>If no methods are
annotated with AfterRender, then no special output occurs, and the
CleanupRender phase is triggered.</p><h3
id="ComponentRendering-CleanupRender">CleanupRender</h3><p>The CleanupRender
phase (see @<a class="external-link" href="http://tapest
ry.apache.org/current/apidocs/org/apache/tapestry5/annotations/CleanupRender.html">CleanupRender</a>)
is the counterpart to SetupRender, allowing final cleanup to occur.</p><h2
id="ComponentRendering-UsingMethodNamesinsteadofAnnotations">Using Method Names
instead of Annotations</h2><p>If you prefer to avoid using annotations on your
methods, you may do so by providing specific names for your methods. The
required method name is the annotation name, with the first character
decapitalized: setupRender(), beginRender(), etc. As with annotated render
phase methods, Tapestry is flexible about visibility, return type and
parameters.</p><p>Using this mechanism, the earlier example can be rewritten
as:</p><parameter ac:name="">java</parameter><plain-text-body>package
org.example.app.components;
+</pre>
+</div></div><p>Returning false from next() causes Tapestry to re-run the
BeginRender phase, and from there, re-render the component's body (this
component does not have a template). Returning true transitions to the
CleanupRender phase.</p><p>Notice how Tapestry adapts to your methods, as
marked with the annotations. It also adapts in terms of parameters; the two
annotated methods here did not perform any output, so they did not need a
MarkupWriter.</p><p>What's really mind blowing is that the template and body of
a component will often contain ... more components! That means that many
different components will be in different phases of their own state
machine.</p><h2 id="ComponentRendering-RenderPhasesinDetail">Render Phases in
Detail</h2><p></p><div class="navmenu" style="float:right; width:50%;
background:#eee; margin:3px; padding:3px">
+<div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
+<p>The SetupRender phase, like all render phases, occurs once for each
rendering of the component. If the component is inside a looping component (<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Loop.html";>Loop</a>,
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Grid.html";>Grid</a>,
etc.), then the SetupRender method will be called once for <em>each</em>
iteration of the loop.</p></div></div></div><h3
id="ComponentRendering-SetupRender">SetupRender</h3><p>The SetupRender phase
(see @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SetupRender.html";>SetupRender</a>)
is where you can perform any one-time per-render setup for your component.
This is a good place to read component parameters and use them to set temporary
instance variables.</p><h3 id="ComponentRendering-BeginRender">BeginRender</
h3><p>The BeginRender phase (see @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender.html";>BeginRender</a>)
occurs at the start of the rendering of the component. For components that
render a tag, the start tag should be rendered here (the close tag should be
rendered inside the AfterRender phase). The component can also prevent the
template and/or body from being rendered by returning false.</p><p>Components
may or may not have a template. If a component has a template, and the template
includes a <body> element, then the BeforeRenderBody phase will be
triggered (giving the component the option of rendering its body or
not).</p><p>If a component does not have a <body> element in its
template, then the BeforeRenderBody phase is not triggered.</p><p>If a
component does not have a template, but does have a body, the BeforeRenderBody
phase is still triggered.</p><p>If no methods are annotated with BeginRen
der, then no special output occurs during this phase, but the template (if
present) or body (if no template is present, but the component has a body) will
be rendered.</p><h3
id="ComponentRendering-BeforeRenderTemplate">BeforeRenderTemplate</h3><p>The
BeforeRenderTemplate phase (see @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderTemplate.html";>BeforeRenderTemplate</a>)
exists to allow a component to decorate its template (creating markup around
the template generated markup), or to allow a component to skip its
template.</p><h3
id="ComponentRendering-BeforeRenderBody">BeforeRenderBody</h3><p>The
BeforeRenderBody phase (see @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderBody.html";>BeforeRenderBody</a>)
is associated with a component's body (the portion of its container's template
that the component occupies). The BeforeRenderBody phase al
lows the component the ability to skip the body, while still rendering the
rest of the component's template (if any).</p><p>If no methods are annotated
with BeforeRenderBody, then the body will be rendered by default. Again, this
occurs when the <body> element of the component's template is reached, or
automatically if the component has no template (but the component does have a
body).</p><h3
id="ComponentRendering-AfterRenderBody">AfterRenderBody</h3><p>The
AfterRenderBody phase (see @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderBody.html";>AfterRenderBody</a>)
is executed after the body is rendered; this only occurs for components with a
body.</p><h3 id="ComponentRendering-AfterRender">AfterRender</h3><p>The
AfterRender phase (see @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRender.html";>AfterRender</a>)
complements BeginRender, and is
often used to render the close tag that matches the start tag rendered in the
BeginRender phase. In any case, the AfterRender phase can continue on to
CleanupRender, or revert back to BeginRender (as in our Count component
example, above).</p><p>If no methods are annotated with AfterRender, then no
special output occurs, and the CleanupRender phase is triggered.</p><h3
id="ComponentRendering-CleanupRender">CleanupRender</h3><p>The CleanupRender
phase (see @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/CleanupRender.html";>CleanupRender</a>)
is the counterpart to SetupRender, allowing final cleanup to occur.</p><h2
id="ComponentRendering-UsingMethodNamesinsteadofAnnotations">Using Method Names
instead of Annotations</h2><p>If you prefer to avoid using annotations on your
methods, you may do so by providing specific names for your methods. The
required method name is the annotation name, with the first character
decapitaliz
ed: setupRender(), beginRender(), etc. As with annotated render phase methods,
Tapestry is flexible about visibility, return type and parameters.</p><p>Using
this mechanism, the earlier example can be rewritten as:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package org.example.app.components;
import org.apache.tapestry5.annotations.Parameter;
@@ -175,7 +264,9 @@ public class Count
return true;
}
}
-</plain-text-body><p>This style is a trade off: on the gain side, the code is
<em>even</em> simpler and shorter, and the method names will, by design, be
more consistent from one class to the next. The down side is that the names are
very generic, and may in some cases, be less descriptive than using annotated
methods (<code>initializeValue()</code> and <code>next()</code> are, to some
eyes, more descriptive).</p><p>You can, of course, mix and match, using
specifically named render phase methods in some cases, and annotated render
phase methods in other cases.</p><h2
id="ComponentRendering-RenderingComponents">Rendering Components</h2><p>Instead
of returning true or false, a render phase method may return a component. The
component may have been injected via the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation, or may have been passed to the owning component as a
parameter.</p><p>In
any case, returning a component will queue that component to be rendered
<strong>before</strong> the active component continues rendering.</p><p>The
component to render may even be from a completely different page of the
application.</p><p>Recursive rendering of components is not allowed.</p><p>This
technique allows the rendering of Tapestry pages to be <em>highly</em>
dynamic.</p><p>Returning a component instance does <strong>not</strong> short
circuit method invocation (as described below), the way returning a boolean
would. It is possible that multiple methods may return components (this is not
advised – insanity may ensue).</p><h2
id="ComponentRendering-AdditionalReturnTypes">Additional Return
Types</h2><p>Render phase methods may also return <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html";>Blocks</a>,
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Renderable.html";>R
enderables</a> or <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/runtime/RenderCommand.html";>RenderCommands</a>.</p><p>The
following component returns a Renderable in the BeginRender phase and skips
the BeforeRenderTemplate phase:</p><parameter
ac:name="lang">java</parameter><plain-text-body>public class
OutputValueComponent
+</pre>
+</div></div><p>This style is a trade off: on the gain side, the code is
<em>even</em> simpler and shorter, and the method names will, by design, be
more consistent from one class to the next. The down side is that the names are
very generic, and may in some cases, be less descriptive than using annotated
methods (<code>initializeValue()</code> and <code>next()</code> are, to some
eyes, more descriptive).</p><p>You can, of course, mix and match, using
specifically named render phase methods in some cases, and annotated render
phase methods in other cases.</p><h2
id="ComponentRendering-RenderingComponents">Rendering Components</h2><p>Instead
of returning true or false, a render phase method may return a component. The
component may have been injected via the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation, or may have been passed to the owning component as a
parameter.</p><p>In any ca
se, returning a component will queue that component to be rendered
<strong>before</strong> the active component continues rendering.</p><p>The
component to render may even be from a completely different page of the
application.</p><p>Recursive rendering of components is not allowed.</p><p>This
technique allows the rendering of Tapestry pages to be <em>highly</em>
dynamic.</p><p>Returning a component instance does <strong>not</strong> short
circuit method invocation (as described below), the way returning a boolean
would. It is possible that multiple methods may return components (this is not
advised – insanity may ensue).</p><h2
id="ComponentRendering-AdditionalReturnTypes">Additional Return
Types</h2><p>Render phase methods may also return <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html";>Blocks</a>,
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Renderable.html";>Rendera
bles</a> or <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/runtime/RenderCommand.html";>RenderCommands</a>.</p><p>The
following component returns a Renderable in the BeginRender phase and skips
the BeforeRenderTemplate phase:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class OutputValueComponent
{
@Parameter
private String value;
@@ -191,8 +282,11 @@ public class Count
};
}
}
-</plain-text-body><h2 id="ComponentRendering-ShortCircuiting">Short
Circuiting</h2><p>If a method returns a true or false value, this will short
circuit processing. Other methods within the phase that would ordinarily be
invoked will not be invoked.</p><p>Most render phase methods should return
void, to avoid unintentionally short circuiting other methods for the same
phase.</p><h2 id="ComponentRendering-MethodConflictsandOrdering">Method
Conflicts and Ordering</h2><p>It is possible to have multiple methods that are
annotated with the same render phase annotation. This may include methods in
the same class, or a mix of method defined in a class and inherited from other
classes.</p><h3 id="ComponentRendering-MixinsBeforeComponent">Mixins Before
Component</h3><p>When a component has <a
href="component-mixins.html">mixins</a>, then the mixins' render phase methods
execute <em>before</em> the component's render phase methods. If a mixin
extends from a base class, the mixin's parent cla
ss methods execute before the mixin subclass' render phase
methods.</p><p>Exception: Mixins whose class is annotated with @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/MixinAfter.html";>MixinAfter</a>
are ordered <em>after</em> the component, not before.</p><p>The order in which
the mixins of a given class (@MixinAfter or mixins before) execute is
determined by the ordering constraints specified for the mixins. If no
constraints are provided, the order is undefined. See <a
href="component-mixins.html">Component Mixins</a> for more details.</p><h3
id="ComponentRendering-ParentsbeforeChild">Parents before Child</h3><p>Ordering
is always parent-first. Methods defined in the parent class are always invoked
before methods defined in the child class.</p><p>When a sub-class overrides an
render phase method of a base class, the method is only invoked once, along
with any other base class methods. The subclass can change the <em>
implementation</em> of the base class method via an override, but can't change
the <em>timing</em> of when that method is invoked. See <a
class="external-link"
href="https://issues.apache.org/jira/browse/TAPESTRY-2311";>TAPESTRY-2311</a>.</p><h3
id="ComponentRendering-ReverseOrderingforAfterXXXandCleanupRender">Reverse
Ordering for AfterXXX and CleanupRender</h3><p>The After_XXX_ phases exists to
balance the Begin_XXX_ and Before_XXX_ phases. Often elements will be started
inside an earlier phase and then the elements will be ended (closed) inside the
corresponding After_XXX_ phase (with the body and template of the component
rendering between).</p><p>In order to ensure that operations occur in the
correct, and natural order, the render phase methods for these two stages are
invoked in <em>reverse order</em>:</p><ul><li>Subclass methods</li><li>Parent
class methods</li><li>Mixin subclass methods</li><li>Mixin parent class
methods</li></ul><h3 id="ComponentRendering-WithinaSingleClas
s">Within a Single Class</h3><p>Currently, rendering methods having the same
annotation within a single class are executed in alphabetical order by method
name. Methods with the same name are ordered by number of parameters. Even so,
annotating multiple methods with the same rendering phase is not a great idea.
Instead, just define one method, and have it call the other methods in the
order you desire.</p><h2 id="ComponentRendering-RenderingComments">Rendering
Comments</h2><p>Starting with version 5.3, Tapestry can optionally emit
rendering comments for all requests; these are comments such as <!--BEGIN
Index:loop (context:Index.tml, line 15)--> that can assist you in debugging
markup output on the client-side. This will significantly increase the size of
the rendered markup, but can be very helpful with complex layouts to determine
which component was responsible for which portion of the rendered
page.</p><p>Rendering comments are only available when not running in <a href="
configuration.html">production mode</a>.</p><p>To turn on rendering comments
for all requests, set the <a
href="configuration.html">tapestry.component-render-tracing-enabled</a>
configuration symbol to "true".</p><p>To turn on rendering comments only for a
particular request, add the query parameter <code>t:component-trace=true</code>
to the URL:</p><plain-text-body>
http://www.example.com/myapp/mypage?t:component-trace=true
-</plain-text-body></div>
+</pre>
+</div></div><h2 id="ComponentRendering-ShortCircuiting">Short
Circuiting</h2><p>If a method returns a true or false value, this will short
circuit processing. Other methods within the phase that would ordinarily be
invoked will not be invoked.</p><p>Most render phase methods should return
void, to avoid unintentionally short circuiting other methods for the same
phase.</p><h2 id="ComponentRendering-MethodConflictsandOrdering">Method
Conflicts and Ordering</h2><p>It is possible to have multiple methods that are
annotated with the same render phase annotation. This may include methods in
the same class, or a mix of method defined in a class and inherited from other
classes.</p><h3 id="ComponentRendering-MixinsBeforeComponent">Mixins Before
Component</h3><p>When a component has <a
href="component-rendering.html">mixins</a>, then the mixins' render phase
methods execute <em>before</em> the component's render phase methods. If a
mixin extends from a base class, the mixin's parent class
methods execute before the mixin subclass' render phase
methods.</p><p>Exception: Mixins whose class is annotated with @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/MixinAfter.html";>MixinAfter</a>
are ordered <em>after</em> the component, not before.</p><p>The order in which
the mixins of a given class (@MixinAfter or mixins before) execute is
determined by the ordering constraints specified for the mixins. If no
constraints are provided, the order is undefined. See <a
href="component-rendering.html">Component Rendering</a> for more
details.</p><h3 id="ComponentRendering-ParentsbeforeChild">Parents before
Child</h3><p>Ordering is always parent-first. Methods defined in the parent
class are always invoked before methods defined in the child class.</p><p>When
a sub-class overrides an render phase method of a base class, the method is
only invoked once, along with any other base class methods. The subclass can
change the <
em>implementation</em> of the base class method via an override, but can't
change the <em>timing</em> of when that method is invoked. See <a
class="external-link"
href="https://issues.apache.org/jira/browse/TAPESTRY-2311";>TAPESTRY-2311</a>.</p><h3
id="ComponentRendering-ReverseOrderingforAfterXXXandCleanupRender">Reverse
Ordering for AfterXXX and CleanupRender</h3><p>The After_XXX_ phases exists to
balance the Begin_XXX_ and Before_XXX_ phases. Often elements will be started
inside an earlier phase and then the elements will be ended (closed) inside the
corresponding After_XXX_ phase (with the body and template of the component
rendering between).</p><p>In order to ensure that operations occur in the
correct, and natural order, the render phase methods for these two stages are
invoked in <em>reverse order</em>:</p><ul><li>Subclass methods</li><li>Parent
class methods</li><li>Mixin subclass methods</li><li>Mixin parent class
methods</li></ul><h3 id="ComponentRendering-WithinaSingleC
lass">Within a Single Class</h3><p>Currently, rendering methods having the
same annotation within a single class are executed in alphabetical order by
method name. Methods with the same name are ordered by number of parameters.
Even so, annotating multiple methods with the same rendering phase is not a
great idea. Instead, just define one method, and have it call the other methods
in the order you desire.</p><h2
id="ComponentRendering-RenderingComments">Rendering Comments</h2><p>Starting
with version 5.3, Tapestry can optionally emit rendering comments for all
requests; these are comments such as <!--BEGIN Index:loop
(context:Index.tml, line 15)--> that can assist you in debugging markup
output on the client-side. This will significantly increase the size of the
rendered markup, but can be very helpful with complex layouts to determine
which component was responsible for which portion of the rendered
page.</p><p>Rendering comments are only available when not running in <a hre
f="component-rendering.html">production mode</a>.</p><p>To turn on rendering
comments for all requests, set the <a
href="component-rendering.html">tapestry.component-render-tracing-enabled</a>
configuration symbol to "true".</p><p>To turn on rendering comments only for a
particular request, add the query parameter <code>t:component-trace=true</code>
to the URL:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
http://www.example.com/myapp/mypage?t:component-trace=true
+</pre>
+</div></div></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/component-templates.html
==============================================================================
--- websites/production/tapestry/content/component-templates.html (original)
+++ websites/production/tapestry/content/component-templates.html Sat Feb 3
16:21:22 2018
@@ -100,7 +100,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a href="component-reference.html">Component
Reference</a>
+ <a href="templating-and-markup-faq.html">Templating
and Markup FAQ</a>
</div>
@@ -109,7 +109,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a href="component-libraries.html">Component
Libraries</a>
+ <a href="component-classes.html">Component Classes</a>
</div>
@@ -118,7 +118,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a href="templating-and-markup-faq.html">Templating
and Markup FAQ</a>
+ <a href="component-reference.html">Component
Reference</a>
</div>
@@ -127,7 +127,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a href="component-classes.html">Component Classes</a>
+ <a href="component-libraries.html">Component
Libraries</a>
</div>
@@ -176,8 +176,8 @@
<h1>Bonjour from HelloWorld component.</h1>
</html>
</pre>
-</div></div><div class="sectionMacro"><div
class="sectionMacroRow"> </div></div><p>We'll cover the specific content
of templates shortly, but first a few details about connecting a component to
its template.</p><h2 id="ComponentTemplates-TemplateLocation">Template
Location</h2><p>A component template shares the same name as its corresponding
class file, but with a ".tml" ending (i.e., <strong>T</strong>apestry
<strong>M</strong>arkup <strong>L</strong>anguage), and is stored in the same
package as the corresponding component class.</p><p>Under a typical Maven
directory structure, the Java class and template files for a <em>component</em>
might be:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Java class:</strong></p></td><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>src/main/java/org/example/myapp/components/MyComponent.java</code></p></td></tr><tr><td
colspan="1" rowspan="1" class="c
onfluenceTd"><p><strong>Template:</strong></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>src/main/resources/org/example/myapp/components/MyComponent.tml</code></p></td></tr></tbody></table></div><p>Likewise,
the Java class and template files for a <em>page</em> might be:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Java class:</strong></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>src/main/java/org/example/myapp/pages/MyPage.java</code></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Template:</strong></p></td><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>src/main/resources/org/example/myapp/pages/MyPage.tml</code></p></td></tr></tbody></table></div><p>The
template and the compiled class will be packaged together in the
WEB-INF/classes folder of the application WAR.</p><p>For <em>pages</em> (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 <code>MyPage.tml</code> in the root folder of the web
application.</p><p>A template on the classpath takes precedence over a file in
the web application context.</p><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-error confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Allowing pages to store their
template in the web context is a feature that may go away at some point. It was
included as a way for HTML designers to edit template directly and live preview
the template directly, without executing the Tapestry application. This comes
with a large number of limitations and leads to a false sense of security that
a template that previews correctly will render properly (this is not always the
case).</p>
</div></div><h2 id="ComponentTemplates-TemplateLocalization">Template
Localization</h2><p>Main Article: <a
href="localization.html">Localization</a></p><p>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 <code>MyPage_de.tml</code> and French users
will see content generated from <code>MyPage_fr.tml</code>. When no specific
localization is available, the default location (<code>MyPage.tml</code>) is
used.</p><div class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>It is necessary to <a
href="configuration.html">enable support for a locale</a> before Tapestry will
attempt to localize to that locale. This requires configuration in your
application modul
e; if you are using the Tapestry Quickstart archetype, only locale "en" will
be enabled by default.</p></div></div><p><span class="confluence-anchor-link"
id="ComponentTemplates-doctypes"></span></p><h2
id="ComponentTemplates-TemplateDoctypes">Template Doctypes</h2><p>As mentioned
above, component templates are well-formed XML documents. This means that if
you want to use any <a class="external-link"
href="http://www.w3.org/TR/html401/sgml/entities.html"; rel="nofollow">Named
HTML entities</a> (such as &amp; &lt; &gt; &copy;), you must
use an <a class="external-link"
href="http://www.w3.org/QA/2002/04/valid-dtd-list.html"; rel="nofollow">HTML or
XHTML doctype</a> in your template <em>(starting in 5.3, this is more-or-less
automatic, see notes below)</em>. 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 tem
plate contains a doctype declaration, only the first doctype encountered by
the template parser will be passed on to the client.</p><p>It should also be
noted that even though <strong>X</strong>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," <a class="external-link"
href="http://www.w3.org/TR/xhtml1/#xhtml"; rel="nofollow">as per the W3C</a>.
Don't worry though – the original HTML 4 doctype will still be emitted to
the client!</p><p>The following are the most common (X)HTML doctypes:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><!DOCTYPE html>
+</div></div><div class="sectionMacro"><div
class="sectionMacroRow"> </div></div><p>We'll cover the specific content
of templates shortly, but first a few details about connecting a component to
its template.</p><h2 id="ComponentTemplates-TemplateLocation">Template
Location</h2><p>A component template shares the same name as its corresponding
class file, but with a ".tml" ending (i.e., <strong>T</strong>apestry
<strong>M</strong>arkup <strong>L</strong>anguage), and is stored in the same
package as the corresponding component class.</p><p>Under a typical Maven
directory structure, the Java class and template files for a <em>component</em>
might be:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Java class:</strong></p></td><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>src/main/java/org/example/myapp/components/MyComponent.java</code></p></td></tr><tr><td
colspan="1" rowspan="1" class="c
onfluenceTd"><p><strong>Template:</strong></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>src/main/resources/org/example/myapp/components/MyComponent.tml</code></p></td></tr></tbody></table></div><p>Likewise,
the Java class and template files for a <em>page</em> might be:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Java class:</strong></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>src/main/java/org/example/myapp/pages/MyPage.java</code></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Template:</strong></p></td><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>src/main/resources/org/example/myapp/pages/MyPage.tml</code></p></td></tr></tbody></table></div><p>The
template and the compiled class will be packaged together in the
WEB-INF/classes folder of the application WAR.</p><p>For <em>pages</em> (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 <code>MyPage.tml</code> in the root folder of the web
application.</p><p>A template on the classpath takes precedence over a file in
the web application context.</p><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-error confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Allowing pages to store their
template in the web context is a feature that may go away at some point. It was
included as a way for HTML designers to edit template directly and live preview
the template directly, without executing the Tapestry application. This comes
with a large number of limitations and leads to a false sense of security that
a template that previews correctly will render properly (this is not always the
case).</p>
</div></div><h2 id="ComponentTemplates-TemplateLocalization">Template
Localization</h2><p>Main Article: <a href="component-templates.html">Component
Templates</a></p><p>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
<code>MyPage_de.tml</code> and French users will see content generated from
<code>MyPage_fr.tml</code>. When no specific localization is available, the
default location (<code>MyPage.tml</code>) is used.</p><div
class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>It is necessary to <a
href="component-templates.html">enable support for a locale</a> before Tapestry
will attempt to localize to that locale. This requires configuration in yo
ur application module (usually AppModule.java); if you are using the Tapestry
Quickstart archetype, only locale "en" will be enabled by
default.</p></div></div><p><span class="confluence-anchor-link"
id="ComponentTemplates-doctypes"></span></p><h2
id="ComponentTemplates-TemplateDoctypes">Template Doctypes</h2><p>As mentioned
above, component templates are well-formed XML documents. This means that if
you want to use any <a class="external-link"
href="http://www.w3.org/TR/html401/sgml/entities.html"; rel="nofollow">Named
HTML entities</a> (such as &amp; &lt; &gt; &copy;), you must
use an <a class="external-link"
href="http://www.w3.org/QA/2002/04/valid-dtd-list.html"; rel="nofollow">HTML or
XHTML doctype</a> in your template <em>(starting in 5.3, this is more-or-less
automatic, see notes below)</em>. 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 c
omponents, 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.</p><p>It should also be noted that even though
<strong>X</strong>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," <a class="external-link" href="http://www.w3.org/TR/xhtml1/#xhtml";
rel="nofollow">as per the W3C</a>. Don't worry though – the original HTML
4 doctype will still be emitted to the client!</p><p>The following are the most
common (X)HTML doctypes:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><!DOCTYPE html>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
@@ -211,7 +211,7 @@
</body>
</html>
</pre>
-</div></div><p>This defines the namespace using the standard prefix, "t:". The
examples on this page all assume the use of the standard prefix.</p><p>For
backwards compatibility, you may continue to use the old namespace URIs: <a
class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd";>http://tapestry.apache.org/schema/tapestry_5_0_0.xsd</a>
or <a class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd";>http://tapestry.apache.org/schema/tapestry_5_1_0.xsd</a> or
 <a class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_3.xsd";>http://tapestry.apache.org/schema/tapestry_5_3.xsd</a></p><pre> </pre><p> However,
the following elements added, as part of Tapestry 5.1, will not work with the
5_0_0.xsd:</p><ul><li>The <t:remove>
Element</li><li><t:content></li><li><t:extension-point></li><li><t:extend></li><li><t:replace></li></ul><p>The
5_3.xsd fixes some minor bugs in t
he 5_1_0.xsd, but is functionally equivalent; 5_3.xsd and 5_4.xsd are
identical.</p><h2 id="ComponentTemplates-TapestryElements">Tapestry
Elements</h2><p>Tapestry elements are elements defined using the Tapestry
namespace prefix (usually "t:").</p><p>All other elements in your templates
should be in the default namespace, with no prefix (with the possible exception
of any Library Namespaces (described <a
href="component-templates.html">below</a>).</p><p>There are a certain number of
Tapestry elements, listed below, that act as template directives; beyond that,
any element in the Tapestry namespace will be a Tapestry component.</p><h3
id="ComponentTemplates-The<t:body>Element">The <t:body>
Element</h3><p>In many cases, a component is designed to have its template
integrate with, or "wrap around", the containing component.</p><p>The
<t:body> element is used to identify where, within a component's
template, its body (from the container's template) is to be rendered.<
/p><p>Components have control over if, and even how often, their body is
rendered.</p><p>The following example is a <a
href="layout-component.html">Layout component</a>, which adds basic HTML
elements <em>around</em> the page-specific content:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This defines the namespace using the standard prefix, "t:". The
examples on this page all assume the use of the standard prefix.</p><p>For
backwards compatibility, you may continue to use the old namespace URIs: <a
class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd";>http://tapestry.apache.org/schema/tapestry_5_0_0.xsd</a>
or <a class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd";>http://tapestry.apache.org/schema/tapestry_5_1_0.xsd</a> or
 <a class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_3.xsd";>http://tapestry.apache.org/schema/tapestry_5_3.xsd</a></p><pre> </pre><p> However,
the following elements added, as part of Tapestry 5.1, will not work with the
5_0_0.xsd:</p><ul><li>The <t:remove>
Element</li><li><t:content></li><li><t:extension-point></li><li><t:extend></li><li><t:replace></li></ul><p>The
5_3.xsd fixes some minor bugs in t
he 5_1_0.xsd, but is functionally equivalent; 5_3.xsd and 5_4.xsd are
identical.</p><h2 id="ComponentTemplates-TapestryElements">Tapestry
Elements</h2><p>Tapestry elements are elements defined using the Tapestry
namespace prefix (usually "t:").</p><p>All other elements in your templates
should be in the default namespace, with no prefix (with the possible exception
of any Library Namespaces (described <a
href="component-templates.html">below</a>).</p><p>There are a certain number of
Tapestry elements, listed below, that act as template directives; beyond that,
any element in the Tapestry namespace will be a Tapestry component.</p><h3
id="ComponentTemplates-The<t:body>Element">The <t:body>
Element</h3><p>In many cases, a component is designed to have its template
integrate with, or "wrap around", the containing component.</p><p>The
<t:body> element is used to identify where, within a component's
template, its body (from the container's template) is to be rendered.<
/p><p>Components have control over if, and even how often, their body is
rendered.</p><p>The following example is a <a
href="component-templates.html">Layout component</a>, which adds basic HTML
elements <em>around</em> the page-specific content:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><html
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<head>
<title>My Tapestry Application</title>
@@ -244,17 +244,17 @@
<td>${value}</td>
</t:container>
</pre>
-</div></div><p>This component only makes sense when used inside a <tr>
element of its container's template.</p><p>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.</p><p></p><h3
id="ComponentTemplates-The<t:block>Element">The <t:block>
Element</h3><p>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.</p><p>A block
may be anonymous, or it may have an id (specified with the id attribute). Only
blocks with an id may be <a href="injection.html">injected</a> into the
component.</p><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-error conflu
ence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>A <t:block> must be in the
Tapestry namespace, but the id attribute should not be. This is different from
components in the template, where the t:id attribute that defines the component
id <em>must</em> be in the Tapestry namespace.</p></div></div><p>Ids must be
valid Java identifiers: start with a letter, and contain only letters, numbers
and underscores.</p><h3
id="ComponentTemplates-The<t:parameter>Element">The <t:parameter>
Element</h3><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>This element was deprecated
starting in Tapestry 5.1 and <em>removed</em> in 5.3. Use <em><a
href="component-templates.html">parameter namespaces</a></em> (below)
instead.</p></div></div><p>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.</p><h3
id="ComponentTemplates-The<t:content>Element">The <t:content>
Element</h3><p><t:content> marks a portion of the template as the actual
template <em>content</em>; 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.</p><p><t:content> elements may
not nest.</p><p>Support for the <t:content> element was adding in
Tapestry release 5.1. You must use the <a class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd";>http://tapestry.apache.org/schema/tapestry_5_1_0.xsd</a>
or <a class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_3.xsd";>ht
tp://tapestry.apache.org/schema/tapestry_5_3.xsd</a> namespace URI for content
to be recognized (otherwise you will see an error about a missing "content"
component).</p><h3
id="ComponentTemplates-<t:remove>"><t:remove></h3><p>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).</p><p>Support for the
<t:remove> element was added in Tapestry release 5.1. You must use the <a
class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd";>http://tapestry.apache.org/schema/tapestry_5_1_0.xsd</a>
or <a
class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_3.xsd";>http://tapestry.apache.org/schema/tapestry_5_3.xsd</a>
namespace URI for remove to be recognized (otherwise you will see an error
about a missing "remove" component).</p><p><span class="confluence-anchor-link"
id="ComponentTemplates-Expansions"></span></p><h2
id="ComponentTemplates-Expansions">Expansions</h2><p>Another option when
rendering output is the use of <em>expansions</em>. Expansions are special
strings that may be embedded in template bodies, and borrow some syntax from
the <a class="external-link" href="http://ant.apache.org";>Ant</a> build
tool.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div></div><p>This component only makes sense when used inside a <tr>
element of its container's template.</p><p>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.</p><p></p><h3
id="ComponentTemplates-The<t:block>Element">The <t:block>
Element</h3><p>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.</p><p>A block
may be anonymous, or it may have an id (specified with the id attribute). Only
blocks with an id may be <a href="component-templates.html">injected</a> into
the component.</p><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-er
ror confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>A <t:block> must be in the
Tapestry namespace, but the id attribute should not be. This is different from
components in the template, where the t:id attribute that defines the component
id <em>must</em> be in the Tapestry namespace.</p></div></div><p>Ids must be
valid Java identifiers: start with a letter, and contain only letters, numbers
and underscores.</p><h3
id="ComponentTemplates-The<t:parameter>Element">The <t:parameter>
Element</h3><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>This element was deprecated
starting in Tapestry 5.1 and <em>removed</em> in 5.3. Use <em><a
href="component-templates.html">parameter namespaces</a></em> (below)
instead.</p></div></div><p>A <parameter> el
ement 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.</p><h3
id="ComponentTemplates-The<t:content>Element">The <t:content>
Element</h3><p><t:content> marks a portion of the template as the actual
template <em>content</em>; 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.</p><p><t:content> elements may
not nest.</p><p>Support for the <t:content> element was adding in
Tapestry release 5.1. You must use the <a class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd";>http://tapestry.apache.org/schema/tapestry_5_1_0.xsd</a>
or <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5
_3.xsd">http://tapestry.apache.org/schema/tapestry_5_3.xsd</a> namespace URI
for content to be recognized (otherwise you will see an error about a missing
"content" component).</p><h3
id="ComponentTemplates-<t:remove>"><t:remove></h3><p>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).</p><p>Support for the
<t:remove> element was added in Tapestry release 5.1. You must use the <a
class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd";>http://tapestry.apache.org/schema/tapestry_5_1_0.xsd<
/a> or <a class="external-link"
href="http://tapestry.apache.org/schema/tapestry_5_3.xsd";>http://tapestry.apache.org/schema/tapestry_5_3.xsd</a>
namespace URI for remove to be recognized (otherwise you will see an error
about a missing "remove" component).</p><p><span class="confluence-anchor-link"
id="ComponentTemplates-Expansions"></span></p><h2
id="ComponentTemplates-Expansions">Expansions</h2><p>Another option when
rendering output is the use of <em>expansions</em>. Expansions are special
strings that may be embedded in template bodies, and borrow some syntax from
the <a class="external-link" href="http://ant.apache.org";>Ant</a> build
tool.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> Welcome, ${userId}!
</pre>
</div></div><p>Here, <code>${userId</code>} is the expansion. In this example,
the userId property of the component is extracted, converted to a string, and
streamed into the output.</p><p>Expansions are allowed inside text, and inside
attributes of ordinary elements, and component elements. For example:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <img
src="${request.contextPath}/images/catalog/product_${productId}.png"/>
</pre>
-</div></div><p>In this hypothetical example, the component class is providing
a request property and a productId property, and these are being used inside
the template to assemble the src attribute of the <img> element. This is
component-like behavior without actual components.</p><p>Under the covers,
expansions are the same as <a href="component-parameters.html">parameter
bindings</a>. The default binding prefix for expansions is "prop:" (that is,
the name of a property or a <a href="property-expressions.html">property
expression</a>), but other binding prefixes are useful, especially "message:"
(to access a localized message from the component's message catalog).</p><div
class="confluence-information-macro confluence-information-macro-warning"><span
class="aui-icon aui-icon-small aui-iconfont-error
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Do not use expansions in component
parameters if the parameter's default or explicit
binding prefix is "prop:" or "var:". Expansions convert the value to an
immutable string, resulting in a runtime exception if the component tries to
update the value. Even for read-only parameters, expansions are not as
desirable, since they always convert to a string, and from there to the
parameter's declared type.</p></div></div><div
class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Tapestry 4 users will note that
expansions are a concise, easy replacement for the Insert component, and for
the <span key="..."> directive.</p></div></div><p>Note that expansions
escape any HTML reserved characters. Specifically, any less-than (<),
greater than (>) and ampersand (&) are replaced with &lt;, &gt;
and &amp; respectively. That is usually what you want. However, if your
property contains H
TML that you want rendered as raw markup, you can use the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/OutputRaw.html";>OutputRaw</a>
component instead, like this: <code><t:OutputRaw
value="someContent"/></code> where <code>someContent</code> is a property
containing HTML markup.</p><p><em>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.</em></p><h2 id="ComponentTemplates-EmbeddedComponents">Embedded
Components</h2><p>An embedded component is identified within the template as an
element in the t: namespace. Example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>In this hypothetical example, the component class is providing
a request property and a productId property, and these are being used inside
the template to assemble the src attribute of the <img> element. This is
component-like behavior without actual components.</p><p>Under the covers,
expansions are the same as <a href="component-templates.html">parameter
bindings</a>. The default binding prefix for expansions is "prop:" (that is,
the name of a property or a <a href="component-templates.html">property
expression</a>), but other binding prefixes are useful, especially "message:"
(to access a localized message from the component's message catalog).</p><div
class="confluence-information-macro confluence-information-macro-warning"><span
class="aui-icon aui-icon-small aui-iconfont-error
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Do not use expansions in component
parameters if the parameter's default or explicit bi
nding prefix is "prop:" or "var:". Expansions convert the value to an
immutable string, resulting in a runtime exception if the component tries to
update the value. Even for read-only parameters, expansions are not as
desirable, since they always convert to a string, and from there to the
parameter's declared type.</p></div></div><div
class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Tapestry 4 users will note that
expansions are a concise, easy replacement for the Insert component, and for
the <span key="..."> directive.</p></div></div><p>Note that expansions
escape any HTML reserved characters. Specifically, any less-than (<),
greater than (>) and ampersand (&) are replaced with &lt;, &gt;
and &amp; respectively. That is usually what you want. However, if your
property contains HTM
L that you want rendered as raw markup, you can use the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/OutputRaw.html";>OutputRaw</a>
component instead, like this: <code><t:OutputRaw
value="someContent"/></code> where <code>someContent</code> is a property
containing HTML markup.</p><p><em>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.</em></p><h2 id="ComponentTemplates-EmbeddedComponents">Embedded
Components</h2><p>An embedded component is identified within the template as an
element in the t: namespace. Example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> You have ${cartItems.size()} items in your cart.
<t:actionlink t:id="clear">Remove All</t:actionlink>.
</pre>
-</div></div><p>The element name, "actionlink" is used to select the type of
component, ActionLink.</p><div class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>As elsewhere, Tapestry is
insensitive to case when mapping from a component type to a component
class.</p></div></div><p>Embedded components may have two Tapestry-specific <a
href="component-parameters.html">parameters</a>:</p><ul><li>id: A unique id for
the component (within its container).</li><li>mixins: An optional comma
separated list of mixins for the the component.</li></ul><p>These attributes
are specified inside the t: namespace (i.e.,
<code>t:id="clear"</code>).</p><p>If the id attribute is omitted, Tapestry will
assign a unique id for the element.</p><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-ico
n aui-icon-small aui-iconfont-warning
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Non-trivial components should
always be assigned a specific id, rather than letting Tapestry do it. You'll
end up with shorter, more readable URLs and code that's easier to debug,
because it will be more obvious how the request URL maps to your pages and
components. This is even more strongly encouraged for form control components,
where the component id will usually be the same as the query parameter that
stores the value provided by the end user.</p></div></div><p>Ids must be valid
Java identifiers: start with a letter, and contain only letters, numbers and
underscores.</p><p>Any other attributes are used to <a
href="component-parameters.html">bind parameters of the component</a>. 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 liter
als (i.e., the "literal:" binding prefix).</p><p>Use of the t: prefix is
optional for all other attributes. Some users implement a build process where
the Tapestry template files are validated ... in that case, any
Tapestry-specific attributes, not defined by the underlying DTD or schema,
should be in the Tapestry namespace, to avoid validation errors.</p><p>The open
and close tags of a Tapestry component element define the <strong>body</strong>
of the component. It is quite common for additional components to be
<strong>enclosed</strong> in the body of another component:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>The element name, "actionlink" is used to select the type of
component, ActionLink.</p><div class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>As elsewhere, Tapestry is
insensitive to case when mapping from a component type to a component
class.</p></div></div><p>Embedded components may have two Tapestry-specific <a
href="component-templates.html">parameters</a>:</p><ul><li>id: A unique id for
the component (within its container).</li><li>mixins: An optional comma
separated list of mixins for the the component.</li></ul><p>These attributes
are specified inside the t: namespace (i.e.,
<code>t:id="clear"</code>).</p><p>If the id attribute is omitted, Tapestry will
assign a unique id for the element.</p><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon
aui-icon-small aui-iconfont-warning
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Non-trivial components should
always be assigned a specific id, rather than letting Tapestry do it. You'll
end up with shorter, more readable URLs and code that's easier to debug,
because it will be more obvious how the request URL maps to your pages and
components. This is even more strongly encouraged for form control components,
where the component id will usually be the same as the query parameter that
stores the value provided by the end user.</p></div></div><p>Ids must be valid
Java identifiers: start with a letter, and contain only letters, numbers and
underscores.</p><p>Any other attributes are used to <a
href="component-templates.html">bind parameters of the component</a>. 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 literal
s (i.e., the "literal:" binding prefix).</p><p>Use of the t: prefix is
optional for all other attributes. Some users implement a build process where
the Tapestry template files are validated ... in that case, any
Tapestry-specific attributes, not defined by the underlying DTD or schema,
should be in the Tapestry namespace, to avoid validation errors.</p><p>The open
and close tags of a Tapestry component element define the <strong>body</strong>
of the component. It is quite common for additional components to be
<strong>enclosed</strong> in the body of another component:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:form>
<t:errors/>
<t:label for="userId"/>
@@ -295,7 +295,7 @@
</tr>
</tabel>
</pre>
-</div></div><p>Here, the loop component "merges into" the <tr> element.
It will render out a <tr> for each <code>item</code> in the
<code>items</code> list, with each <tr> including three <td>
elements. It will also write a dynamic "class" attribute into each
<tr>.</p><p><span class="confluence-anchor-link"
id="ComponentTemplates-parameter-namespaces"></span></p><h2
id="ComponentTemplates-ParameterNamespaces">Parameter Namespaces</h2><p>Main
Article: <a href="component-parameters.html">Component
Parameters</a></p><p>Parameter namespaces (introduced in Tapestry 5.1) are a
concise way of passing parameter blocks to components.</p><p>You must define a
special namespace, usually with the prefix "p":</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Here, the loop component "merges into" the <tr> element.
It will render out a <tr> for each <code>item</code> in the
<code>items</code> list, with each <tr> including three <td>
elements. It will also write a dynamic "class" attribute into each
<tr>.</p><p><span class="confluence-anchor-link"
id="ComponentTemplates-parameter-namespaces"></span></p><h2
id="ComponentTemplates-ParameterNamespaces">Parameter Namespaces</h2><p>Main
Article: <a href="component-templates.html">Component
Templates</a></p><p>Parameter namespaces (introduced in Tapestry 5.1) are a
concise way of passing parameter blocks to components.</p><p>You must define a
special namespace, usually with the prefix "p":</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><html
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd";
xmlns:p="tapestry:parameter">
. . .
</pre>
![https://cwiki-test.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2"](https://cwiki-test.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2"){kind=link}