Modified: websites/production/tapestry/content/component-rendering.html
==============================================================================
--- websites/production/tapestry/content/component-rendering.html (original)
+++ websites/production/tapestry/content/component-rendering.html Tue Sep 26
19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,86 +67,7 @@
</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><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"
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 met
hods 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="htt
p://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="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 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-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><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;
+ <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;
import org.apache.tapestry5.annotations.Parameter;
import org.apache.tapestry5.annotations.AfterRender;
@@ -210,11 +121,11 @@ public class Count
return true;
}
}
-</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;
+</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;
import org.apache.tapestry5.annotations.Parameter;
@@ -264,9 +175,7 @@ public class Count
return true;
}
}
-</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
+</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
{
@Parameter
private String value;
@@ -282,11 +191,8 @@ public class Count
};
}
}
-</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-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 class met
hods 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>implem
entation</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-WithinaSingleClass">Wit
hin 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="config
uration.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><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>
+</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>
</div>
<div class="clearer"></div>
Modified:
websites/production/tapestry/content/documentation-improvement-tasks.html
==============================================================================
--- websites/production/tapestry/content/documentation-improvement-tasks.html
(original)
+++ websites/production/tapestry/content/documentation-improvement-tasks.html
Tue Sep 26 19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -79,55 +69,34 @@
<div id="content">
<div id="ConfluenceContent"><p>This is an informal list of
suggested improvements to the Tapestry 5 site documentation – things to
work on soon. Most of these have come from users on the Tapestry Users mailing
list.</p>
-<div class="navmenu" style="float:right; background:#eee; margin:3px;
padding:3px">
-<div class="error"><span class="error">Error formatting macro: contentbylabel:
com.atlassian.confluence.api.service.exceptions.BadRequestException: Could not
parse cql : null</span> </div></div>
-
-<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>These are merely suggestions from Tapestry users. Some might be bad ideas.
Consider carefully which of these ought to be done and how, and start a
discussion on the dev mailing list about any change that could be
controversial.</p></div></div>
-
-<div style="background-color: #f9f9f9; border: 1px solid #c0c0c0; width:
40em;">
- <h2></h2>
- <h6>15% of the tasks completed</h6>
- <table border="0" style="border-collapse: collapse; width:
100%;"><tbody><tr><td colspan="1" rowspan="1" style="border-top: 1px solid
#cbcbcb; width: 10%;"><input disabled></td><td colspan="1" rowspan="1"
style="border-top: 1px solid #cbcbcb; width: 70%">Need more cross-linking
between the wiki pages, especially between FAQ pages, User Guide pages, Cheat
Sheet pages and Cookbook pages that cover the same topic.</td><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 20%; text-align:
right;">
- High
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%"><a href="component-cheat-sheet.html" title="Component Cheat
Sheet">Component Cheat Sheet</a> should have, for each of the listed
annotations, a link to the corresponding API page.</td><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 20%; text-align:
right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">Some pages don't link to all of their child pages</td><td
colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb; width: 20%;
text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">Move some of the best MoinMoin wiki content into
Confluence?</td><td colspan="1" rowspan="1" style="border-top: 1px solid
#cbcbcb; width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">Need an article on clustering & high availability, then link to
it from the clustering sections of <a href="persistent-page-data.html"
title="Persistent Page Data">Persistent Page Data</a>, <a
href="ioc-serialization.html" title="IoC - serialization">IoC -
serialization</a>, <a href="persistent-state.html" title="Persistent
State">Persistent State</a>, <a href="https.html" title="HTTPS">HTTPS</a>, and
other pages that mention clustering</td><td colspan="1" rowspan="1"
style="border-top: 1px solid #cbcbcb; width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">Need a "Support" page that lists support options. This is where
the mailing lists should be mentioned., as well as Howard's trainig,
etc</td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">The links to "Tapestry Home" in the breadcrums on pages like <a
href="tutorial.html" title="Tutorial">Tutorial</a> link to the "Home" page but
should link to the index.html page</td><td colspan="1" rowspan="1"
style="border-top: 1px solid #cbcbcb; width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">Make it more obvious how to contribute to documentation
improvements</td><td colspan="1" rowspan="1" style="border-top: 1px solid
#cbcbcb; width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
checked></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">in the "create your first tapestry project" tutorial, don't make
the user choose an archetype or a tapestry version. Write the instructions for
the latest stable version. It's better to have that be out of date when a new
version comes out (because it still will work) than have the user decide at
this stage. Same for the groupId, artifactId, version and package. It's a test
project the user is creating, those values are not going to matter. Give the
defaults so people can copy and paste the command and have the project created,
built and run.</td><td colspan="1" rowspan="1" style="border-top: 1px solid
#cbcbcb; width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
checked></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">After the test project has been created, give the user some
pointers on where to find things (pages go in src/main/java/com/example/pages,
page templates go in webapp). Although there is a link to the tutorial, if this
first experience is too frustrating, people might not even bother to go
there.</td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">add something to the archetype with commented out code that the
user can uncomment and see something cool happen. It has to be a few lines
only, to be easily understandable, and clearly link components in the template
with their methods in the page class.</td><td colspan="1" rowspan="1"
style="border-top: 1px solid #cbcbcb; width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">the tapestry tutorial starts unnecessarily verbose about topics not
really related to me getting code running and out the door. Strip it to the
essentials. If you want to mention Struts and the Servlet API compared to the
tapestry way, mention them in a separate chapter so they are easy to find /
skip as needed.</td><td colspan="1" rowspan="1" style="border-top: 1px solid
#cbcbcb; width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">there is no table of contents for the tutorial and no indication of
how long it takes to complete</td><td colspan="1" rowspan="1"
style="border-top: 1px solid #cbcbcb; width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">There are too many callouts, warnings and decorations in the
tutorial. It is very distracting visually and that makes it hard to follow.
It's impossible to scan the pages to get a feel for what you've got ahead of
you.</td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">Add a page about testing your Tapestry app (not just testing of
pages)</td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">On the ComponentCheetSheet, add a sentance or two more on each
annotation would be great.</td><td colspan="1" rowspan="1" style="border-top:
1px solid #cbcbcb; width: 20%; text-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
checked></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">The tutorial Setting up your environment should be improved.
Alternatives should be described on how to run T5 apps in the Eclipse or other
IDEs, but not in the text as that would make it too long. I think there should
be links for alternative setups - like how to run the T5 app from a main class
and even start VisualVM for early debugging and optimizing (each alternative
has pros and cons). There is no mention of m2eclipse plugin. Of course one can
use JDK 6 also - only 1.5 is there. There is a sentence: "You should not have
to download this directly". Why are then download links on the download page
and no mention of maven at the same time. It is confusing for newbs.</td><td
colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb; width: 20%; te
xt-align: right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">Add a link to JIRA in the About page</td><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 20%; text-align:
right;">
- Medium
- </td></tr><tr><td colspan="1"
rowspan="1" style="border-top: 1px solid #cbcbcb; width: 10%;"><input
disabled></td><td colspan="1" rowspan="1" style="border-top: 1px solid #cbcbcb;
width: 70%">Resolve the TODO at the bottom of <a href="component-classes.html"
title="Component Classes">Component Classes</a> ("May want a more complex
check; what if user uses prop: in the template and there's a
conflict?")</td><td colspan="1" rowspan="1" style="border-top: 1px solid
#cbcbcb; width: 20%; text-align: right;">
- Medium
- </td></tr></tbody></table>
-</div></div>
+<plain-text-body>{float:right|background=#eee}
+{contentbylabel:title=Related
Articles|showLabels=false|showSpace=false|labels=plans}
+{float}</plain-text-body>
+
+<rich-text-body>
+<p>These are merely suggestions from Tapestry users. Some might be bad ideas.
Consider carefully which of these ought to be done and how, and start a
discussion on the dev mailing list about any change that could be
controversial.</p></rich-text-body>
+
+<plain-text-body>||Completed||Priority||Locked||CreatedDate||CompletedDate||Assignee||Name||
+|F|H|F| | | |Need more cross-linking between the wiki pages,
especially between FAQ pages, User Guide pages, Cheat Sheet pages and Cookbook
pages that cover the same topic.|
+|F|M|F| | | |[Component Cheat Sheet] should have, for each
of the listed annotations, a link to the corresponding API page.|
+|F|M|F| | | |Some pages don't link to all of their child
pages|
+|F|M|F| | | |Move some of the best MoinMoin wiki content
into Confluence?|
+|F|M|F|1290869296693| | |Need an article on clustering & high
availability, then link to it from the clustering sections of [Persistent Page
Data], [IoC - serialization], [Persistent State], [HTTPS], and other pages that
mention clustering|
+|F|M|F|1290869418470| | |Need a "Support" page that lists support
options. This is where the mailing lists should be mentioned., as well as
Howard's trainig, etc|
+|F|M|F|1290872794706| | |The links to "Tapestry Home" in the
breadcrums on pages like [Tutorial] link to the "Home" page but should link to
the index.html page|
+|F|M|F|1290872892940| | |Make it more obvious how to contribute to
documentation improvements|
+|T|M|F|1290873286462|1291053687265|[email protected]|in the "create your
first tapestry project" tutorial, don't make the user choose an archetype or a
tapestry version. Write the instructions for the latest stable version. It's
better to have that be out of date when a new version comes out (because it
still will work) than have the user decide at this stage. Same for the groupId,
artifactId, version and package. It's a test project the user is creating,
those values are not going to matter. Give the defaults so people can copy and
paste the command and have the project created, built and run.|
+|T|M|F|1290873334655|1291036593723|[email protected]|After the test
project has been created, give the user some pointers on where to find things
(pages go in src/main/java/com/example/pages, page templates go in webapp).
Although there is a link to the tutorial, if this first experience is too
frustrating, people might not even bother to go there.|
+|F|M|F|1290873345788| | |add something to the archetype with
commented out code that the user can uncomment and see something cool happen.
It has to be a few lines only, to be easily understandable, and clearly link
components in the template with their methods in the page class.|
+|F|M|F|1290873360243| | |the tapestry tutorial starts unnecessarily
verbose about topics not really related to me getting code running and out the
door. Strip it to the essentials. If you want to mention Struts and the Servlet
API compared to the tapestry way, mention them in a separate chapter so they
are easy to find / skip as needed.|
+|F|M|F|1290873372769| | |there is no table of contents for the
tutorial and no indication of how long it takes to complete|
+|F|M|F|1290873390989| | |There are too many callouts, warnings and
decorations in the tutorial. It is very distracting visually and that makes it
hard to follow. It's impossible to scan the pages to get a feel for what you've
got ahead of you.|
+|F|M|F|1290873483266| | |Add a page about testing your Tapestry app
(not just testing of pages)|
+|F|M|F|1290873573643| | |On the ComponentCheetSheet, add a sentance
or two more on each annotation would be great.|
+|T|M|F|1290873630472|1418608629709|bobharner|The tutorial Setting up your
environment should be improved. Alternatives should be described on how to run
T5 apps in the Eclipse or other IDEs, but not in the text as that would make it
too long. I think there should be links for alternative setups - like how to
run the T5 app from a main class and even start VisualVM for early debugging
and optimizing (each alternative has pros and cons). There is no mention of
m2eclipse plugin. Of course one can use JDK 6 also - only 1.5 is there. There
is a sentence: "You should not have to download this directly". Why are then
download links on the download page and no mention of maven at the same time.
It is confusing for newbs.|
+|F|M|F|1290873682697| | |Add a link to JIRA in the About page|
+|F|M|F|1290954416064| | |Resolve the TODO at the bottom of [Component
Classes] ("May want a more complex check; what if user uses prop: in the
template and there's a conflict?")|
+</plain-text-body></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/dom.html
==============================================================================
--- websites/production/tapestry/content/dom.html (original)
+++ websites/production/tapestry/content/dom.html Tue Sep 26 19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,14 +67,13 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><h1
id="DOM-DocumentObjectModel">Document Object Model</h1><p>Tapestry 5 takes a
very different approach to markup generation than most other frameworks.
Components render out a Document Object Model (DOM). This is a tree of nodes
representing elements, attributes and text within a document.</p><p>Once all
rendering is complete, the DOM tree is streamed to the client.</p><p>The <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupWriter.html";>MarkupWriter</a>
interface allows the majority of component code to treat the generation of
output as a stream. In reality, MarkupWriter is more like a cursor into the DOM
tree, and the DOM may ultimately be operated upon in a random access manner
(rather than the serial (or buffered) approach used in Tapestry 4).</p><div
class="navmenu" style="float:right; width:30%; background:white; margin:3px;
padding:3px">
-<div class="confluence-information-macro
confluence-information-macro-information"><p class="title">A Note For Tapestry
4 Users</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
-<p>In Tapestry 4, markup generation was based on generating a character
stream. At the lowest level, the fact that the output was in a markup format
such as HTML, XHTML or WML was not known. Higher levels, such as the
IMarkupWriter interface (and its implementations) provide the concept of markup
generation: elements, attributes, start tags and end tags. This technique
breaks down when two elements are peers, and not in a parent/child
relationship. For example, the rendering of a FieldLabel component is affected
by its companion TextField component. Handling these cases in Tapestry 4
required a number of kludges and special cases.</p></div></div></div><h1
id="DOM-DOMClasses">DOM Classes</h1><p>The implementation of this DOM is part
of Tapestry, despite the fact that several third-party alternatives exist. This
represents a desire to limit dependencies for the framework, but also the
Tapestry DOM is streamlined for initial creation, and a limited amount of
subsequent modification. Mo
st DOM implementations are more sophisticated than needed for Tapestry, with
greater support for querying (often using XPath) and manipulation.</p><p>Once
the Document object is created, you don't directly create new DOM objects;
instead, each DOM object includes methods that create new sub-objects. This
primarily applies to the Element class, which can be a container of text,
comments and other elements.</p><h2 id="DOM-Document">Document</h2><p>The <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Document.html";>Document
Object</a> represents the an entire document, which is to say, an entire
response to be sent to the client.</p><p>Documents will have a single root
element. The newRootElement() method is used to create the root element for the
document.</p><p>The Document class also has methods for setting and getting the
DTD, adding comments and text, and finding an element based on a path of
element names.</p><h2 id="DOM-Element"
>Element</h2><p>An <a class="external-link"
>href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Element.html";>Element
> Object</a> represents an element of the document. Elements may have
>attributes, and they may themselves contain other elements, as well as text
>and comments.</p><p>The Element class has methods for searching, traversing
>and manipulating the DOM after it is built.</p><h1
>id="DOM-DOMManipulation/Rewriting">DOM Manipulation/Rewriting</h1><p>A
>powerful feature of Tapestry 5 is the ability to manipulate the structure and
>ordering of the DOM after it has been rendered. For example, this can be used
>to alter the output of a component that may otherwise be outside of your
>control.</p><p>DOM manipulation is surprisingly fast, too.</p><p>Methods on
>Node (and Element, which is a subclass of Node) allow an existing node to be
>moved relative to an Element. Nodes may be moved before or after the Element,
>or may be moved inside an Element at the top (the firs
t child) or the bottom (the last child).</p><p>Element's
<code>attribute</code> method adds a new attribute name/value pair to the
Element. If an existing attribute with the specified name already exists, then
then the new value is ignored. This has implications when different pieces of
code try to add attributes to an Element ... the first to add an attribute will
"win". Conversely, the <code>forceAttributes</code> method can be used to
update or remove an attribute.</p><p>In addition, the children of an Element
may be removed or a Node (and all of its children) removed
entirely.</p><p>Finally, an Element may "pop": the Element is removed and
replaced with its children.</p><h1
id="DOM-MarkupWriter">MarkupWriter</h1><p>The <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupWriter.html";>MarkupWriter
interface</a> allows the structure of the document to be built while
maintaining a streaming metaphor.</p><h2 id="DOM-element()andend()m
ethods">element() and end() methods</h2><p>Calls to element() create a new
element within the tree, and may provide attributes for the new element as
well. Calls to write(), writeln() and writef() write text nodes within the
current element. <em>Every call to element() should be matched with a call to
end()</em>, which is used to move the current node up one level.</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;"> writer.element("img", "src", "icon.png", "width", 20,
"height", 20, alt, "*");
+ <div id="ConfluenceContent"><h1
id="DOM-DocumentObjectModel">Document Object Model</h1><p>Tapestry 5 takes a
very different approach to markup generation than most other frameworks.
Components render out a Document Object Model (DOM). This is a tree of nodes
representing elements, attributes and text within a document.</p><p>Once all
rendering is complete, the DOM tree is streamed to the client.</p><p>The <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupWriter.html";>MarkupWriter</a>
interface allows the majority of component code to treat the generation of
output as a stream. In reality, MarkupWriter is more like a cursor into the DOM
tree, and the DOM may ultimately be operated upon in a random access manner
(rather than the serial (or buffered) approach used in Tapestry
4).</p><plain-text-body>{float:right|width=30%}
+{info:title=A Note For Tapestry 4 Users}
+In Tapestry 4, markup generation was based on generating a character stream.
At the lowest level, the fact that the output was in a markup format such as
HTML, XHTML or WML was not known. Higher levels, such as the IMarkupWriter
interface (and its implementations) provide the concept of markup generation:
elements, attributes, start tags and end tags. This technique breaks down when
two elements are peers, and not in a parent/child relationship. For example,
the rendering of a FieldLabel component is affected by its companion TextField
component. Handling these cases in Tapestry 4 required a number of kludges and
special cases.
+{info}
+{float}</plain-text-body><h1 id="DOM-DOMClasses">DOM Classes</h1><p>The
implementation of this DOM is part of Tapestry, despite the fact that several
third-party alternatives exist. This represents a desire to limit dependencies
for the framework, but also the Tapestry DOM is streamlined for initial
creation, and a limited amount of subsequent modification. Most DOM
implementations are more sophisticated than needed for Tapestry, with greater
support for querying (often using XPath) and manipulation.</p><p>Once the
Document object is created, you don't directly create new DOM objects; instead,
each DOM object includes methods that create new sub-objects. This primarily
applies to the Element class, which can be a container of text, comments and
other elements.</p><h2 id="DOM-Document">Document</h2><p>The <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Document.html";>Document
Object</a> represents the an entire document, which is to
say, an entire response to be sent to the client.</p><p>Documents will have a
single root element. The newRootElement() method is used to create the root
element for the document.</p><p>The Document class also has methods for setting
and getting the DTD, adding comments and text, and finding an element based on
a path of element names.</p><h2 id="DOM-Element">Element</h2><p>An <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Element.html";>Element
Object</a> represents an element of the document. Elements may have
attributes, and they may themselves contain other elements, as well as text and
comments.</p><p>The Element class has methods for searching, traversing and
manipulating the DOM after it is built.</p><h1
id="DOM-DOMManipulation/Rewriting">DOM Manipulation/Rewriting</h1><p>A powerful
feature of Tapestry 5 is the ability to manipulate the structure and ordering
of the DOM after it has been rendered. For example, this can be u
sed to alter the output of a component that may otherwise be outside of your
control.</p><p>DOM manipulation is surprisingly fast, too.</p><p>Methods on
Node (and Element, which is a subclass of Node) allow an existing node to be
moved relative to an Element. Nodes may be moved before or after the Element,
or may be moved inside an Element at the top (the first child) or the bottom
(the last child).</p><p>Element's <code>attribute</code> method adds a new
attribute name/value pair to the Element. If an existing attribute with the
specified name already exists, then then the new value is ignored. This has
implications when different pieces of code try to add attributes to an Element
... the first to add an attribute will "win". Conversely, the
<code>forceAttributes</code> method can be used to update or remove an
attribute.</p><p>In addition, the children of an Element may be removed or a
Node (and all of its children) removed entirely.</p><p>Finally, an Element may
"pop": the Elemen
t is removed and replaced with its children.</p><h1
id="DOM-MarkupWriter">MarkupWriter</h1><p>The <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupWriter.html";>MarkupWriter
interface</a> allows the structure of the document to be built while
maintaining a streaming metaphor.</p><h2
id="DOM-element()andend()methods">element() and end() methods</h2><p>Calls to
element() create a new element within the tree, and may provide attributes for
the new element as well. Calls to write(), writeln() and writef() write text
nodes within the current element. <em>Every call to element() should be matched
with a call to end()</em>, which is used to move the current node up one
level.</p><parameter ac:name="">java</parameter><plain-text-body>
writer.element("img", "src", "icon.png", "width", 20, "height", 20, alt, "*");
writer.end();
-</pre>
-</div></div><p>Note that end() must be called here, even though the
<img> element is empty (has no body). If the call to end() is omitted,
then later elements created by calls to element() will be nested
<em>inside</em> the <img> element, which is not desired.</p><p>Again,
<strong>every call to element() must be matched with a call to
end()</strong>:</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;"> writer.element("select", "name", "choice");
+</plain-text-body><p>Note that end() must be called here, even though the
<img> element is empty (has no body). If the call to end() is omitted,
then later elements created by calls to element() will be nested
<em>inside</em> the <img> element, which is not desired.</p><p>Again,
<strong>every call to element() must be matched with a call to
end()</strong>:</p><parameter ac:name="">java</parameter><plain-text-body>
writer.element("select", "name", "choice");
for (String name : optionsNames)
{
@@ -94,12 +83,9 @@
}
writer.end();
-</pre>
-</div></div><h2 id="DOM-attributes()">attributes()</h2><p>Adds additional
name/value pairs to the current element.</p><p>When a value is null, no
attribute is added.</p><p>When a new name conflicts with an existing name, the
new value is ignored. This gives precedence to the first value specified for an
attribute over any subsequent value.</p><h2 id="DOM-write()">write()</h2><p>The
write() method writes text inside the current element. It scans the provided
text for XML control characters ('<', '>', and '&') and converts them
to their XML entity equivalents ('<', '>', and '&'). The result is
correct, safe, HTML/XML output even when the content (which may come from a
template, or from an external source such as a database) contains such
problematic characters.</p><h2 id="DOM-writef()">writef()</h2><p>The writef()
method formats an number of arguments. It uses a java.util.Formatter. It is a
convenience for formatting that ultimately invokes write().</p><h2 id="DOM-
writeRaw()">writeRaw()</h2><p>The writeRaw() method writes unfiltered text
into the DOM. When the DOM is rendered to markup, the provided string is
written to the output stream exactly as-is. Care should be taken, as this can
easily result invalid markup, or even markup that is not well formed.</p><h2
id="DOM-comment()">comment()</h2><p>Adds an XML comment. The comment delimiters
will be supplied by Tapestry:</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;"> writer.comment("Start of JS Menu code");
+</plain-text-body><h2 id="DOM-attributes()">attributes()</h2><p>Adds
additional name/value pairs to the current element.</p><p>When a value is null,
no attribute is added.</p><p>When a new name conflicts with an existing name,
the new value is ignored. This gives precedence to the first value specified
for an attribute over any subsequent value.</p><h2
id="DOM-write()">write()</h2><p>The write() method writes text inside the
current element. It scans the provided text for XML control characters ('<',
'>', and '&') and converts them to their XML entity equivalents ('<',
'>', and '&'). The result is correct, safe, HTML/XML output even when
the content (which may come from a template, or from an external source such as
a database) contains such problematic characters.</p><h2
id="DOM-writef()">writef()</h2><p>The writef() method formats an number of
arguments. It uses a java.util.Formatter. It is a convenience for formatting
that ultimately invokes write().</p><h2 id
="DOM-writeRaw()">writeRaw()</h2><p>The writeRaw() method writes unfiltered
text into the DOM. When the DOM is rendered to markup, the provided string is
written to the output stream exactly as-is. Care should be taken, as this can
easily result invalid markup, or even markup that is not well formed.</p><h2
id="DOM-comment()">comment()</h2><p>Adds an XML comment. The comment delimiters
will be supplied by Tapestry:</p><parameter
ac:name="">java</parameter><plain-text-body> writer.comment("Start of JS Menu
code");
-</pre>
-</div></div></div>
+</plain-text-body></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/enum-parameter-recipe.html
==============================================================================
--- websites/production/tapestry/content/enum-parameter-recipe.html (original)
+++ websites/production/tapestry/content/enum-parameter-recipe.html Tue Sep 26
19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,8 +67,8 @@
</div>
<div id="content">
- <div id="ConfluenceContent">
-<p></p>
+ <div
id="ConfluenceContent"><plain-text-body>{scrollbar}</plain-text-body>
+<p><parameter ac:name="hidden">true</parameter><rich-text-body><p>Using an
Enum as a component parameter using coercion</p></rich-text-body></p>
<h1 id="EnumParameterRecipe-EnumComponentParameter">Enum Component
Parameter</h1>
@@ -88,8 +78,7 @@
<p>Let's start with the enum type itself:</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width:
1px;"><b>BlankOption.java</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
+<parameter ac:name="title">BlankOption.java</parameter><plain-text-body>
public enum BlankOption
{
/**
@@ -107,13 +96,11 @@ public enum BlankOption
*/
AUTO;
}
-</pre>
-</div></div>
+</plain-text-body>
<p>Next, we define the parameter:</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Select.java
(partial)</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
+<parameter ac:name="title">Select.java (partial)</parameter><plain-text-body>
/**
* Controls whether an additional blank option is provided. The blank
option precedes all other options and is never
@@ -122,15 +109,13 @@ public enum BlankOption
*/
@Parameter(value = "auto", defaultPrefix = BindingConstants.LITERAL)
private BlankOption blankOption;
-</pre>
-</div></div>
+</plain-text-body>
<p>Note the use of literal as the default prefix; this allows us to use the
name of the option in our template, e.g. <code><t:select blankoption="never"
.../></code>. Without the default prefix setting, "never" would be
interpreted as a property expression (and you'd see an error when you loaded
the page).</p>
<p>The final piece of the puzzle is to inform Tapestry how to convert from a
string, such as "never", to a BlankOption value.</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>TapestryModule.java
(partial)</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
+<parameter ac:name="title">TapestryModule.java
(partial)</parameter><plain-text-body>
public static void
contributeTypeCoercer(Configuration<CoercionTuple> configuration)
{
. . .
@@ -144,8 +129,7 @@ public enum BlankOption
{
configuration.add(CoercionTuple.create(String.class, enumType,
StringToEnumCoercion.create(enumType)));
}
-</pre>
-</div></div>
+</plain-text-body>
<p>The TypeCoercer service is ultimately responsible for converting the string
to a BlankOption, but we have to tell it how, by contributing an appropriate
CoercionTuple. The CoercionTuple identifies the source and target types (String
and BlankOption), and an object to perform the coercion (an instance of
StringToEnumCoercion, via the <code>create()</code> static method).</p></div>
</div>
