Author: buildbot
Date: Sat Feb 17 12:21:22 2018
New Revision: 1025502
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/built-in-mixins.html
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/component-mixins.html
websites/production/tapestry/content/component-parameters.html
websites/production/tapestry/content/component-reference.html
websites/production/tapestry/content/enum-parameter-recipe.html
websites/production/tapestry/content/layout-component.html
websites/production/tapestry/content/localization.html
websites/production/tapestry/content/page-navigation.html
websites/production/tapestry/content/parameter-type-coercion.html
Modified: websites/production/tapestry/content/built-in-mixins.html
==============================================================================
--- websites/production/tapestry/content/built-in-mixins.html (original)
+++ websites/production/tapestry/content/built-in-mixins.html Sat Feb 17
12:21:22 2018
@@ -67,7 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>Tapestry includes the following
mixins out-of-the-box.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Autocomplete.html";>Autocomplete</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>modifies a text field to
provide for auto-completion of text using values retrieved from the server as
the user types. <a href="ajax-and-zones.html">See
instructions</a>.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><a class="external-link"
href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/mixins/Confirm.html";>Confirm</a></td><td
colspan="1" rowspan="1" class="confluenceTd">attached to a Form or link
component, runs a modal-dialog to force the user to confirm the behavior. New
for Tapestry 5.4.</td></tr><tr><td col
span="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/DiscardBody.html";>DiscardBody</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>discards a component's body.
Returns false from the BeforeRenderBody phase, which prevents the rendering of
the body.</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/corelib/mixins/FormFieldFocus.html";>FormFieldFocus</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>instruments the outer Form on
which component the focus should be activated. Replaced by OverrideFieldFocus
starting in Tapestry 5.4.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><a class="external-link"
href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/mixins/FormGroup.html";>FormGroup</a></td><td
cols
pan="1" rowspan="1" class="confluenceTd">attaches to a field to render an
enclosing <div> element and label for proper Bootstrap markup of text
fields, selects, and textareas</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/corelib/mixins/NotEmpty.html";>NotEmpty</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>attaches to any component that
renders an element. At the end of the render, if the element is empty, then a
non-breaking space (&nbsp;) is injected into the
element.</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/corelib/mixins/OverrideFieldFocus.html";>OverrideFieldFocus</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>when attached to a form field,
causes that field to gain focus. Starting in Tapestry 5.4, thi
s supersedes FormFieldFocus.</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/corelib/mixins/RenderClientId.html";>RenderClientId</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>forces a client element to
render its client id by ensuring that "getClientId" is
called.</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/corelib/mixins/RenderDisabled.html";>RenderDisabled</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>renders a "disabled" attribute
if the containing component is disabled</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/corelib/mixins/RenderInformals.html";>RenderInformals</a></p></td><td
colspan="1" r
owspan="1" class="confluenceTd"><p>renders out all informal parameters, at the
end of the BeginRender phase. This mixin can be used with components that
render a single tag inside the BeginRender phase.</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/corelib/mixins/RenderNotification.html";>RenderNotification</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>triggers component event
notifications when the attached component enters its BeginRender and
AfterRender render phases.</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/corelib/mixins/TriggerFragment.html";>TriggerFragment</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>when applied to a Checkbox or
Radio component, links the input field and a FormFragment, making the fie
ld control the client-side visibility of the FormFragment</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/corelib/mixins/ZoneRefresh.html";>ZoneRefresh</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>periodically refreshes a Zone
by triggering an event on the server using ajax
requests.</p></td></tr></tbody></table></div></div>
+ <div id="ConfluenceContent"><p>Tapestry includes the following
mixins out-of-the-box.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Autocomplete.html";>Autocomplete</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>modifies a text field to
provide for auto-completion of text using values retrieved from the server as
the user types. <a href="ajax-and-zones.html">See
instructions</a>.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Confirm.html";>Confirm</a></td><td
colspan="1" rowspan="1" class="confluenceTd">attached to a Form or link
component, runs a modal-dialog to force the user to confirm the behavior. New
for Tapestry 5.4.</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/corelib/mixins/DiscardBody.html";>DiscardBody</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>discards a component's body.
Returns false from the BeforeRenderBody phase, which prevents the rendering of
the body.</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/corelib/mixins/FormFieldFocus.html";>FormFieldFocus</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>instruments the outer Form on
which component the focus should be activated. Replaced by OverrideFieldFocus
starting in Tapestry 5.4.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/FormGroup.html";>FormGroup</a></td>
<td colspan="1" rowspan="1" class="confluenceTd">attaches to a field to render
an enclosing <div> element and label for proper Bootstrap markup of text
fields, selects, and textareas</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/corelib/mixins/NotEmpty.html";>NotEmpty</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>attaches to any component that
renders an element. At the end of the render, if the element is empty, then a
non-breaking space (&nbsp;) is injected into the
element.</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/corelib/mixins/OverrideFieldFocus.html";>OverrideFieldFocus</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>when attached to a form field,
causes that field to gain focus. Starting in Tapestry
5.4, this supersedes FormFieldFocus.</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/corelib/mixins/RenderClientId.html";>RenderClientId</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>forces a client element to
render its client id by ensuring that "getClientId" is
called.</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/corelib/mixins/RenderDisabled.html";>RenderDisabled</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>renders a "disabled" attribute
if the containing component is disabled</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/corelib/mixins/RenderInformals.html";>RenderInformals</a></p></td><td
colsp
an="1" rowspan="1" class="confluenceTd"><p>renders out all informal
parameters, at the end of the BeginRender phase. This mixin can be used with
components that render a single tag inside the BeginRender
phase.</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/corelib/mixins/RenderNotification.html";>RenderNotification</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>triggers component event
notifications when the attached component enters its BeginRender and
AfterRender render phases.</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/corelib/mixins/TriggerFragment.html";>TriggerFragment</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>when applied to a Checkbox or
Radio component, links the input field and a FormFragment, making
the field control the client-side visibility of the
FormFragment</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/corelib/mixins/ZoneRefresh.html";>ZoneRefresh</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>periodically refreshes a Zone
by triggering an event on the server using ajax
requests.</p></td></tr></tbody></table></div></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/component-mixins.html
==============================================================================
--- websites/production/tapestry/content/component-mixins.html (original)
+++ websites/production/tapestry/content/component-mixins.html Sat Feb 17
12:21:22 2018
@@ -101,7 +101,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a href="component-templates.html">Component
Templates</a>
+ <a href="legacy-javascript.html">Legacy JavaScript</a>
</div>
@@ -110,7 +110,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a href="legacy-javascript.html">Legacy JavaScript</a>
+ <a href="component-templates.html">Component
Templates</a>
</div>
@@ -136,7 +136,7 @@
</div>
-<p>You can think of a mixin as a kind of mashup for a component; it combines
the new behavior of the mixin with the existing behavior of the component, and
bundles it all in one place. Mixins may be used to add specialized validation
to user input fields, dynamically modify the HTML output of a component, or to
add Ajax effects and behaviors of all sorts to components.</p><p>Tapestry comes
with several mixins, such as the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Autocomplete.html";>Autocomplete
mixin</a> which adds autocomplete behavior to an ordinary TextField Component.
In addition, you can easily create your own.</p><h2
id="ComponentMixins-MixinClasses">Mixin Classes</h2><p>Mixin classes are stored
in the <code>mixins</code> sub-package of your application, below the
application (or library) root package. This parallels where your component and
page classes are stored.</p><p>Other than that, mixin classes are th
e same as any other component class.</p><h2
id="ComponentMixins-MixinLimitations">Mixin Limitations</h2><p>Currently,
mixins are allowed to do anything a component can do, including having
parameters and render phase methods.</p><p>Mixins may not have a template. They
integrate with the component strictly in terms of invoking render phase
methods.</p><p>Mixins may have persistent fields, but currently, this is not
implemented perfectly (there is a potential for a name clash between a mixin
and the component or another mixin). Use persistent fields with mixins with
care ... or better yet, delegate persistence to the container using
parameters.</p><p>Mixins may not, themselves, have mixins.</p><h2
id="ComponentMixins-UsingMixins">Using Mixins</h2><p>Mixins are used in two
different scenarios: <em>Instance mixins</em> and <em>Implementation
mixins</em>.</p><h3 id="ComponentMixins-InstanceMixins">Instance
Mixins</h3><p>An instance mixin is a mixin applied to a specific
<em>instance</em>
of a component. This can be done in the <a
href="component-mixins.html">component template</a> with the
<code>mixins</code> attribute of the component tag. This is a comma-separated
list of mixin names.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+<p>You can think of a mixin as a kind of mashup for a component; it combines
the new behavior of the mixin with the existing behavior of the component, and
bundles it all in one place. Mixins may be used to add specialized validation
to user input fields, dynamically modify the HTML output of a component, or to
add Ajax effects and behaviors of all sorts to components.</p><p>Tapestry comes
with several mixins, such as the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Autocomplete.html";>Autocomplete
mixin</a> which adds autocomplete behavior to an ordinary TextField Component.
In addition, you can easily create your own.</p><h2
id="ComponentMixins-MixinClasses">Mixin Classes</h2><p>Mixin classes are stored
in the <code>mixins</code> sub-package of your application, below the
application (or library) root package. This parallels where your component and
page classes are stored.</p><p>Other than that, mixin classes are th
e same as any other component class.</p><h2
id="ComponentMixins-MixinLimitations">Mixin Limitations</h2><p>Currently,
mixins are allowed to do anything a component can do, including having
parameters and render phase methods.</p><p>Mixins may not have a template. They
integrate with the component strictly in terms of invoking render phase
methods.</p><p>Mixins may have persistent fields, but currently, this is not
implemented perfectly (there is a potential for a name clash between a mixin
and the component or another mixin). Use persistent fields with mixins with
care ... or better yet, delegate persistence to the container using
parameters.</p><p>Mixins may not, themselves, have mixins.</p><h2
id="ComponentMixins-UsingMixins">Using Mixins</h2><p>Mixins are used in two
different scenarios: <em>Instance mixins</em> and <em>Implementation
mixins</em>.</p><h3 id="ComponentMixins-InstanceMixins">Instance
Mixins</h3><p>An instance mixin is a mixin applied to a specific
<em>instance</em>
of a component. This can be done in the <a
href="component-templates.html">component template</a> with the
<code>mixins</code> attribute of the component tag. This is a comma-separated
list of mixin names.</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:textfield t:id="accountName"
t:mixins="Autocomplete,DefaultFromCookie" />
</pre>
</div></div><p>Alternately, when the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation is used to define the component type, you may specify the mixins in
two ways:</p><ul><li>The @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Mixins.html";>Mixins</a>
annotation allows a list of mixin names to be specified.</li><li>The @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/MixinClasses.html";>MixinClasses</a>
annotation allows a set of mixin classes to be specified
directly.</li></ul><p>The former is often less verbose, and allows core mixins
to be overridden with application-specific mixins. The later format is more
specific and more refactor-safe (renaming a mixin class will rename the entry
in the MixinClasses annotation as well).</p><p>Example:</p><div class="code pane
l pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
@@ -217,7 +217,7 @@ private TextField userId;
...
}
</pre>
-</div></div><p>"MyMixin" can be used on a textfield (principalObject is bound
to "value"), on BeanEditor or BeanDisplay (principalObject is bound to
"object"), or on Grid or Loop (principalObject is bound to "source").</p><h2
id="ComponentMixins-RenderPhaseOrdering">Render Phase Ordering</h2><p>All
mixins for a component execute their render phase methods <em>before</em> the
component's render phase methods for most phases. However, in the later phases
(AfterRender, CleanupRender) the order of executing is
reversed.</p><p>Exception: A 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>
is ordered <em>after</em> the component, not before.</p><p>Withing a given
phase and class (@MixinAfter vs. mixin before), mixin ordering is determined by
the ordering constraints specified in the mixin definitions. The constraint
definitions follow the same conventions as <a
href="component-mixins.html">ordered service configurations</a>. How you
specify the constraints depends on how the mixin is specified.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>As an Implementation
Mixin</b></div><div class="codeContent panelContent pdl">
+</div></div><p>"MyMixin" can be used on a textfield (principalObject is bound
to "value"), on BeanEditor or BeanDisplay (principalObject is bound to
"object"), or on Grid or Loop (principalObject is bound to "source").</p><h2
id="ComponentMixins-RenderPhaseOrdering">Render Phase Ordering</h2><p>All
mixins for a component execute their render phase methods <em>before</em> the
component's render phase methods for most phases. However, in the later phases
(AfterRender, CleanupRender) the order of executing is
reversed.</p><p>Exception: A 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>
is ordered <em>after</em> the component, not before.</p><p>Withing a given
phase and class (@MixinAfter vs. mixin before), mixin ordering is determined by
the ordering constraints specified in the mixin definitions. The constraint
definitions follow the same conventions as <a
href="ordering-by-constraints.html">ordered service configurations</a>. How
you specify the constraints depends on how the mixin is specified.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>As an Implementation
Mixin</b></div><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
@Mixin("Autocomplete",order={"before:DiscardBody","after:RenderDisabled"}
private TextField userId;
</pre>
@@ -235,7 +235,7 @@ private TextField userId;
@MixinClasses(value={Autocomplete.class,DefaultFromCookie.class},
order={"before:discardbody;after:renderdisabled","before:autocomplete")
</pre>
-</div></div><p>The ordering is always specified in terms of the order of the
"forward" rendering process (setupRender, beginRender, etc.). When the
"reverse" rendering phases (afterRender, etc.) occur, the mixin order is
exactly reversed. Mixins which have no associated ordering constraints will be
ordered in a manner which is consistent with the specified constraints for all
other mixins, but is otherwise unspecified.</p><h2
id="ComponentMixins-AvailableMixins">Available Mixins</h2><p>Tapestry includes
the following mixins out-of-the-box.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Autocomplete.html";>Autocomplete</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>modifies a text field to
provide for auto-completion of text using values retrieved from the server as
the user types. <a
href="ajax-and-zones.html">See instructions</a>.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><a class="external-link"
href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/mixins/Confirm.html";>Confirm</a></td><td
colspan="1" rowspan="1" class="confluenceTd">attached to a Form or link
component, runs a modal-dialog to force the user to confirm the behavior. New
for Tapestry 5.4.</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/corelib/mixins/DiscardBody.html";>DiscardBody</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>discards a component's body.
Returns false from the BeforeRenderBody phase, which prevents the rendering of
the body.</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/corelib/mixins/FormF
ieldFocus.html">FormFieldFocus</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>instruments the outer Form on which component the focus
should be activated. Replaced by OverrideFieldFocus starting in Tapestry
5.4.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><a
class="external-link"
href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/mixins/FormGroup.html";>FormGroup</a></td><td
colspan="1" rowspan="1" class="confluenceTd">attaches to a field to render an
enclosing <div> element and label for proper Bootstrap markup of text
fields, selects, and textareas</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/corelib/mixins/NotEmpty.html";>NotEmpty</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>attaches to any component that
renders an element. At the end of the render, if the element is empty, then a
non-breaking space (&nbsp;) is injected into the
element.</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/corelib/mixins/OverrideFieldFocus.html";>OverrideFieldFocus</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>when attached to a form field,
causes that field to gain focus. Starting in Tapestry 5.4, this supersedes
FormFieldFocus.</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/corelib/mixins/RenderClientId.html";>RenderClientId</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>forces a client element to
render its client id by ensuring that "getClientId" is
called.</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/corelib/mixins/RenderDisabled.html">RenderDisabled</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>renders a "disabled" attribute
if the containing component is disabled</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/corelib/mixins/RenderInformals.html";>RenderInformals</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>renders out all informal
parameters, at the end of the BeginRender phase. This mixin can be used with
components that render a single tag inside the BeginRender
phase.</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/corelib/mixins/RenderNotification.html";>RenderNotification</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>triggers component event
notifications when the attached compo
nent enters its BeginRender and AfterRender render
phases.</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/corelib/mixins/TriggerFragment.html";>TriggerFragment</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>when applied to a Checkbox or
Radio component, links the input field and a FormFragment, making the field
control the client-side visibility of the FormFragment</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/corelib/mixins/ZoneRefresh.html";>ZoneRefresh</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>periodically refreshes a Zone
by triggering an event on the server using ajax
requests.</p></td></tr></tbody></table></div><p>In addition, the following
mixins are available from other sources:</p><div class="table-wrap">
<table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/javascript/creatingmixins1";
rel="nofollow">ClickOnce</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>From JumpStart, a mixin to apply to a submit button,
ensuring it can't be double-clicked</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://wiki.apache.org/tapestry/Tapestry5AndJavaScriptExplained";>Confirm</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Adds a JavaScript
<em>confirm</em> prompt to any link</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart7/examples/ajax/onevent";
rel="nofollow">ZoneUpdater</a></td><td colspan="1" rowspan="1"
class="confluenceTd">Updates a zone when a client-side event
occurs</td></tr></tb
ody></table></div><h2 id="ComponentMixins-AdditionalTools">Additional
Tools</h2><p><a class="external-link"
href="http://tapestryxpath.sourceforge.net/"; rel="nofollow">Tapestry-Xpath</a>
is a third-part Tapestry module that allows XPath traversal of the Tapestry
(server-side) DOM, which can be extremely useful in certain mixins.</p></div>
+</div></div><p>The ordering is always specified in terms of the order of the
"forward" rendering process (setupRender, beginRender, etc.). When the
"reverse" rendering phases (afterRender, etc.) occur, the mixin order is
exactly reversed. Mixins which have no associated ordering constraints will be
ordered in a manner which is consistent with the specified constraints for all
other mixins, but is otherwise unspecified.</p><h2
id="ComponentMixins-AvailableMixins">Available Mixins</h2><p>Tapestry includes
the following mixins out-of-the-box.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Autocomplete.html";>Autocomplete</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>modifies a text field to
provide for auto-completion of text using values retrieved from the server as
the user types. <a
href="ajax-and-zones.html">See instructions</a>.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Confirm.html";>Confirm</a></td><td
colspan="1" rowspan="1" class="confluenceTd">attached to a Form or link
component, runs a modal-dialog to force the user to confirm the behavior. New
for Tapestry 5.4.</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/corelib/mixins/DiscardBody.html";>DiscardBody</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>discards a component's body.
Returns false from the BeforeRenderBody phase, which prevents the rendering of
the body.</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/corelib/mixins/F
ormFieldFocus.html">FormFieldFocus</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>instruments the outer Form on which component the focus
should be activated. Replaced by OverrideFieldFocus starting in Tapestry
5.4.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/FormGroup.html";>FormGroup</a></td><td
colspan="1" rowspan="1" class="confluenceTd">attaches to a field to render an
enclosing <div> element and label for proper Bootstrap markup of text
fields, selects, and textareas</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/corelib/mixins/NotEmpty.html";>NotEmpty</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>attaches to any component that
renders an element. At the end of the render, if the element is empty
, then a non-breaking space (&nbsp;) is injected into the
element.</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/corelib/mixins/OverrideFieldFocus.html";>OverrideFieldFocus</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>when attached to a form field,
causes that field to gain focus. Starting in Tapestry 5.4, this supersedes
FormFieldFocus.</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/corelib/mixins/RenderClientId.html";>RenderClientId</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>forces a client element to
render its client id by ensuring that "getClientId" is
called.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a
class="external-link" href="http://tapestry.apache.org/current/apidocs/or
g/apache/tapestry5/corelib/mixins/RenderDisabled.html">RenderDisabled</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>renders a "disabled" attribute
if the containing component is disabled</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/corelib/mixins/RenderInformals.html";>RenderInformals</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>renders out all informal
parameters, at the end of the BeginRender phase. This mixin can be used with
components that render a single tag inside the BeginRender
phase.</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/corelib/mixins/RenderNotification.html";>RenderNotification</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>triggers component event
notifications when the attach
ed component enters its BeginRender and AfterRender render
phases.</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/corelib/mixins/TriggerFragment.html";>TriggerFragment</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>when applied to a Checkbox or
Radio component, links the input field and a FormFragment, making the field
control the client-side visibility of the FormFragment</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/corelib/mixins/ZoneRefresh.html";>ZoneRefresh</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>periodically refreshes a Zone
by triggering an event on the server using ajax
requests.</p></td></tr></tbody></table></div><p>In addition, the following
mixins are available from other sources:</p><div class="tabl
e-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/javascript/creatingmixins1";
rel="nofollow">ClickOnce</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>From JumpStart, a mixin to apply to a submit button,
ensuring it can't be double-clicked</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://wiki.apache.org/tapestry/Tapestry5AndJavaScriptExplained";>Confirm</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Adds a JavaScript
<em>confirm</em> prompt to any link</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart7/examples/ajax/onevent";
rel="nofollow">ZoneUpdater</a></td><td colspan="1" rowspan="1"
class="confluenceTd">Updates a zone when a client-side event occurs</td><
/tr></tbody></table></div><h2 id="ComponentMixins-AdditionalTools">Additional
Tools</h2><p><a class="external-link"
href="http://tapestryxpath.sourceforge.net/"; rel="nofollow">Tapestry-Xpath</a>
is a third-part Tapestry module that allows XPath traversal of the Tapestry
(server-side) DOM, which can be extremely useful in certain mixins.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/component-parameters.html
==============================================================================
--- websites/production/tapestry/content/component-parameters.html (original)
+++ websites/production/tapestry/content/component-parameters.html Sat Feb 17
12:21:22 2018
@@ -174,17 +174,17 @@
<p>In the following example, <code>page</code> is a parameter of the
<code>pagelink</code> component. The page parameter tells the pagelink
component which page to go to when the user clicks on the rendered
hyperlink:</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">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><html
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<t:pagelink page="Index">Go Home</t:pagelink>
</html></pre>
</div></div><p>A component may have any number of parameters. Each parameter
has a specific name, a specific Java type (which may be a primitive value), and
may be <em>optional</em> or <em>required</em>.</p><p>Within a component class,
parameters are declared by using the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Parameter.html";>Parameter</a>
annotation on a private field, as we'll see below.</p><p><span
class="confluence-anchor-link"
id="ComponentParameters-bindingparameters"></span></p><h1
id="ComponentParameters-ParameterBindings">Parameter Bindings</h1><p>In
Tapestry, a parameter is not a slot into which data is pushed: it is a
<em>connection</em> between a field of the component (marked with the
@Parameter annotation) and a property or resource of the component's container.
(Components can be nested, so the container can be either the page or another
component.)</p><div class="navmenu" style="float:right; backgr
ound:white; margin:3px; padding:3px">
<div class="panel" style="border-width: 1px;"><div class="panelHeader"
style="border-bottom-width: 1px;"><b>Contents</b></div><div
class="panelContent">
<style type="text/css">/*<![CDATA[*/
-div.rbtoc1518488413323 {padding: 0px;}
-div.rbtoc1518488413323 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1518488413323 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1518870055354 {padding: 0px;}
+div.rbtoc1518870055354 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1518870055354 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style><div class="toc-macro rbtoc1518488413323">
+/*]]>*/</style><div class="toc-macro rbtoc1518870055354">
<ul class="toc-indentation"><li><a
href="#ComponentParameters-ParameterBindings">Parameter Bindings</a></li><li><a
href="#ComponentParameters-BindingExpressions">Binding
Expressions</a></li><li><a
href="#ComponentParameters-@Parameterannotation">@Parameter
annotation</a></li><li><a
href="#ComponentParameters-Don'tusethe${...}syntax!">Don't use the ${...}
syntax!</a></li><li><a href="#ComponentParameters-InformalParameters">Informal
Parameters</a></li><li><a
href="#ComponentParameters-ParametersAreBi-Directional">Parameters Are
Bi-Directional</a></li><li><a
href="#ComponentParameters-InheritedParameterBindings">Inherited Parameter
Bindings</a></li><li><a
href="#ComponentParameters-ComputedParameterBindingDefaults">Computed Parameter
Binding Defaults</a></li><li><a
href="#ComponentParameters-UnboundParameters">Unbound Parameters</a></li><li><a
href="#ComponentParameters-ParameterTypeCoercion">Parameter Type
Coercion</a></li><li><a href="#ComponentParameters-ParameterNames">
Parameter Names</a></li><li><a
href="#ComponentParameters-DeterminingifBound">Determining if
Bound</a></li><li><a
href="#ComponentParameters-PublishingParameters">Publishing
Parameters</a></li></ul>
</div>
</div></div></div> <p>The connection between a component and a property
(or resource) of its container is called a <em>binding</em>. The binding is
two-way: the component can read the bound property by reading its parameter
field. Likewise, a component that updates its parameter field will update the
bound property.</p><p>This is important in a lot of cases; for example a
TextField component can read <em>and update</em> the property bound to its
value parameter. It reads the value when rendering, but updates the value when
the form is submitted.</p><p>The component listed below is a looping component;
it renders its body a number of times, defined by its <code>start</code> and
<code>end</code> parameters (which set the boundaries of the loop). The
component can update a <code>result</code> parameter bound to a property of its
container; it will automatically count up or down depending on whether
<code>start</code> or <code>end</code> is larger.</p><div class="code panel
pdl" st
yle="border-width: 1px;"><div class="codeContent panelContent pdl">
@@ -240,13 +240,13 @@ public class Count
}
}
</pre>
-</div></div><p>The name of the parameter is the same as field name (except
with leading "_" and "$" characters, if any, removed). Here, the parameter
names are "start", "end" and "result".</p><p>The component above can be
referenced in another component or page <a
href="component-parameters.html">template</a>, and its parameters
<em>bound</em>:</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 t:type="layout"
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+</div></div><p>The name of the parameter is the same as field name (except
with leading "_" and "$" characters, if any, removed). Here, the parameter
names are "start", "end" and "result".</p><p>The component above can be
referenced in another component or page <a
href="component-templates.html">template</a>, and its parameters
<em>bound</em>:</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 t:type="layout"
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<p> Merry Christmas: <t:count end="3"> Ho! </t:count>
</p>
</html>
</pre>
-</div></div><p>The end attribute is used to <em>bind</em> the end parameter of
the Count component. Here, it is being bound to the string value "3", which is
automatically <a href="component-parameters.html">coerced</a> by Tapestry into
the int value, 3.</p><p>Any number of parameters may be bound this
way.</p><p>Component parameters may also be bound using the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation inside the component class. (Where conflicts occur, the parameters
bound using the Component annotation will take precedence over parameter
bindings in the template.)</p><p><span class="confluence-anchor-link"
id="ComponentParameters-binding-expressions"></span></p><h1
id="ComponentParameters-BindingExpressions">Binding Expressions</h1><p>The
value inside the template, "3" in the previous example, is a <em>binding
expression</em>.</p><p>By placing a prefix in front of the value
, you can change how Tapestry interprets the remainder of the expression (the
part after the colon):</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p><strong>Prefix</strong></p></th><th colspan="1"
rowspan="1"
class="confluenceTh"><p><strong>Description</strong></p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>asset:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The relative path to an asset file (which
must exist)</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>block:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The id of a block within the
template</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>component:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The id of another component within the same
template</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>context:</p></td><td colspan="1" row
span="1" class="confluenceTd"><p>Context asset: path from context
root</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>literal:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A literal string</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>nullfieldstrategy:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Used to locate a pre-defined <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/NullFieldStrategy.html";>NullFieldStrategy</a></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>message:</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Retrieves a string from the
component's <a href="component-parameters.html">message
catalog</a></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>prop:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A <a href="component-parameters.html">property
expression</a> to read or update</
p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>symbol:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Used to read one of your <a
href="component-parameters.html">symbols</a></p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>translate:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The name of a configured
translator</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>validate:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A <em>validator specification</em> used to create some
number of field validators</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>var:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Allows a render variable of the component to be read or
updated</p></td></tr></tbody></table></div><p>Most of these binding prefixes
allow parameters to be bound to read-only values; for instance a parameter
bound to "message:some-key" will see the message
for "some-key" from its container's message catalog in the field. If the
component tries to update the parameter (by setting the value of the field), a
runtime exception will be thrown to indicate that the value is
read-only.</p><p>Only prop: and var: binding prefixes are updateable (but you
must <em>not</em> use the ${..} syntax here; see the <a
href="component-parameters.html">warning below</a>).</p><p>Each parameter has a
default prefix, defined by the component, that is used when the prefix is not
provided. The most common are "literal:" and "prop:".</p><p>A <em>special
prefix</em>, "inherit:", is used to support <a
href="component-parameters.html">Inherited Parameter Bindings</a>.</p><h3
id="ComponentParameters-RenderVariables:Bindings">Render Variables:
Bindings</h3><p>Components can have any number of <em>render variables</em>.
Render variables are named values with no specific type (they are ultimately
stored in a Map). Render variables are useful for holding simple value
s, such as loop indices, that need to be passed from one component to
another.</p><p>For example, the following template code:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>The end attribute is used to <em>bind</em> the end parameter of
the Count component. Here, it is being bound to the string value "3", which is
automatically <a href="type-coercion.html">coerced</a> by Tapestry into the
int value, 3.</p><p>Any number of parameters may be bound this
way.</p><p>Component parameters may also be bound using the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation inside the component class. (Where conflicts occur, the parameters
bound using the Component annotation will take precedence over parameter
bindings in the template.)</p><p><span class="confluence-anchor-link"
id="ComponentParameters-binding-expressions"></span></p><h1
id="ComponentParameters-BindingExpressions">Binding Expressions</h1><p>The
value inside the template, "3" in the previous example, is a <em>binding
expression</em>.</p><p>By placing a prefix in front of the value, you c
an change how Tapestry interprets the remainder of the expression (the part
after the colon):</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p><strong>Prefix</strong></p></th><th colspan="1"
rowspan="1"
class="confluenceTh"><p><strong>Description</strong></p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>asset:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The relative path to an asset file (which
must exist)</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>block:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The id of a block within the
template</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>component:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The id of another component within the same
template</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>context:</p></td><td colspan="1" rowspan="1
" class="confluenceTd"><p>Context asset: path from context
root</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>literal:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A literal string</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>nullfieldstrategy:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Used to locate a pre-defined <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/NullFieldStrategy.html";>NullFieldStrategy</a></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>message:</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Retrieves a string from the
component's <a href="localization.html">message
catalog</a></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>prop:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A <a href="property-expressions.html">property
expression</a> to read or update</p></td></tr><tr
><td colspan="1" rowspan="1" class="confluenceTd"><p>symbol:</p></td><td
>colspan="1" rowspan="1" class="confluenceTd"><p>Used to read one of your <a
>href="symbols.html">symbols</a></p></td></tr><tr><td colspan="1" rowspan="1"
>class="confluenceTd"><p>translate:</p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p>The name of a configured
>translator</p></td></tr><tr><td colspan="1" rowspan="1"
>class="confluenceTd"><p>validate:</p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p>A <em>validator specification</em> used to create
>some number of field validators</p></td></tr><tr><td colspan="1" rowspan="1"
>class="confluenceTd"><p>var:</p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p>Allows a render variable of the component to be read
>or updated</p></td></tr></tbody></table></div><p>Most of these binding
>prefixes allow parameters to be bound to read-only values; for instance a
>parameter bound to "message:some-key" will see the message for "some-key"
>from its con
tainer's message catalog in the field. If the component tries to update the
parameter (by setting the value of the field), a runtime exception will be
thrown to indicate that the value is read-only.</p><p>Only prop: and var:
binding prefixes are updateable (but you must <em>not</em> use the ${..} syntax
here; see the <a href="component-parameters.html">warning
below</a>).</p><p>Each parameter has a default prefix, defined by the
component, that is used when the prefix is not provided. The most common are
"literal:" and "prop:".</p><p>A <em>special prefix</em>, "inherit:", is used to
support <a href="component-parameters.html">Inherited Parameter
Bindings</a>.</p><h3 id="ComponentParameters-RenderVariables:Bindings">Render
Variables: Bindings</h3><p>Components can have any number of <em>render
variables</em>. Render variables are named values with no specific type (they
are ultimately stored in a Map). Render variables are useful for holding simple
values, such as loop indices, tha
t need to be passed from one component to another.</p><p>For example, the
following template code:</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;"><ul>
<li t:type="loop" source="1..10" value="index">${index}</li>
</ul>
@@ -271,7 +271,7 @@ private int index;
private String parameter;
}</pre>
-</div></div><div class="confluence-information-macro
confluence-information-macro-tip"><span class="aui-icon aui-icon-small
aui-iconfont-approve confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Sometimes a parameter is marked as
required, but may still be omitted if the underlying value is provided by some
other means. This is the case, for example, with the Select component's value
parameter, which may have its underlying value set by <a
href="component-parameters.html">contributing a ValueEncoderSource</a>. Be sure
to read the component's parameter documentation carefully. Required simply
enables checks that the parameter is bound, it does not mean that you must
supply the binding in the template (or @Component
annotation).</p></div></div><h3
id="ComponentParameters-OptionalParameters">Optional
Parameters</h3><p>Parameters are optional unless they are marked as
required.</p><p>You may set a default value for optional parameters using the
<code>value</code> element of the @Parameter annotation. In the Count
component above, the start parameter has a default value of 1. That value is
used unless the start parameter is bound, in which case, the bound value
supersedes the default.</p><h3
id="ComponentParameters-ParameterBindingDefaults">Parameter Binding
Defaults</h3><p>The @Parameter annotation's <code>value</code> element can be
used to specify a <em>binding expression</em> that will be the default binding
for the parameter if otherwise left unbound. Typically, this is the name of a
property that that will compute the value on the fly.</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><div class="confluence-information-macro
confluence-information-macro-tip"><span class="aui-icon aui-icon-small
aui-iconfont-approve confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Sometimes a parameter is marked as
required, but may still be omitted if the underlying value is provided by some
other means. This is the case, for example, with the Select component's value
parameter, which may have its underlying value set by <a
href="using-select-with-a-list.html">contributing a ValueEncoderSource</a>. Be
sure to read the component's parameter documentation carefully. Required simply
enables checks that the parameter is bound, it does not mean that you must
supply the binding in the template (or @Component
annotation).</p></div></div><h3
id="ComponentParameters-OptionalParameters">Optional
Parameters</h3><p>Parameters are optional unless they are marked as
required.</p><p>You may set a default value for optional parameters using
the <code>value</code> element of the @Parameter annotation. In the Count
component above, the start parameter has a default value of 1. That value is
used unless the start parameter is bound, in which case, the bound value
supersedes the default.</p><h3
id="ComponentParameters-ParameterBindingDefaults">Parameter Binding
Defaults</h3><p>The @Parameter annotation's <code>value</code> element can be
used to specify a <em>binding expression</em> that will be the default binding
for the parameter if otherwise left unbound. Typically, this is the name of a
property that that will compute the value on the fly.</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;">@Parameter(value="defaultMessage") // or, equivalently,
@Parameter("defaultMessage")
private String message;
@@ -283,7 +283,7 @@ public String getDefaultMessage(){ 
}
</pre>
-</div></div><p>As elsewhere, you may use a prefix on the value. A common
prefix to use is the "message:" prefix, to access a localized message.</p><h3
id="ComponentParameters-ParameterCaching">Parameter Caching</h3><p>Reading a
parameter value can be marginally expensive (because of type coercion).
Therefore, it makes sense to cache the parameter value, at least while the
component is actively rendering itself.</p><p>In rare cases, it is desirable to
defeat the caching; this can be done by setting the cache() attribute of the
@Parameter annotation to false.</p><p><span class="confluence-anchor-link"
id="ComponentParameters-dontUseSyntax"></span></p><h1
id="ComponentParameters-Don'tusethe${...}syntax!">Don't use the ${...}
syntax!</h1><p>Main Article: <a
href="component-parameters.html">Expansions</a></p><p>You generally should
<em>not</em> use the Template Expansion syntax, ${...}, within component
parameter bindings. Doing so results in the property inside the braces being
convert
ed to an (immutable) string, and will therefore result in a runtime exception
if your component needs to update the value (whenever the default or explicit
binding prefix is <code>prop:</code> or <code>var:</code>, since such component
parameters are <em>two-way</em> bindings).</p><div
class="sectionColumnWrapper"><div class="sectionMacro"><div
class="sectionMacroRow"><div class="columnMacro"><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>This is right</b></div><div
class="codeContent panelContent pdl">
+</div></div><p>As elsewhere, you may use a prefix on the value. A common
prefix to use is the "message:" prefix, to access a localized message.</p><h3
id="ComponentParameters-ParameterCaching">Parameter Caching</h3><p>Reading a
parameter value can be marginally expensive (because of type coercion).
Therefore, it makes sense to cache the parameter value, at least while the
component is actively rendering itself.</p><p>In rare cases, it is desirable to
defeat the caching; this can be done by setting the cache() attribute of the
@Parameter annotation to false.</p><p><span class="confluence-anchor-link"
id="ComponentParameters-dontUseSyntax"></span></p><h1
id="ComponentParameters-Don'tusethe${...}syntax!">Don't use the ${...}
syntax!</h1><p>Main Article: <a
href="component-templates.html">Expansions</a></p><p>You generally should
<em>not</em> use the Template Expansion syntax, ${...}, within component
parameter bindings. Doing so results in the property inside the braces being
converte
d to an (immutable) string, and will therefore result in a runtime exception
if your component needs to update the value (whenever the default or explicit
binding prefix is <code>prop:</code> or <code>var:</code>, since such component
parameters are <em>two-way</em> bindings).</p><div
class="sectionColumnWrapper"><div class="sectionMacro"><div
class="sectionMacroRow"><div class="columnMacro"><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>This is right</b></div><div
class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:textfield t:id="color" value="color"/>
</pre>
</div></div></div><div class="columnMacro"><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>This is wrong</b></div><div
class="codeContent panelContent pdl">
@@ -296,7 +296,7 @@ public String getDefaultMessage(){ 
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><img src="context:images/banner.png"/>
</pre>
</div></div></div></div></div></div><h1
id="ComponentParameters-InformalParameters">Informal Parameters</h1><p>Main
Article: <a href="supporting-informal-parameters.html">Supporting Informal
Parameters</a></p><p>Many components support <em>informal parameters</em>,
additional parameters beyond the formally defined parameters. Informal
parameters will be rendered into the output as additional attributes on the tag
rendered by the component. Generally speaking, components that have a 1:1
relationship with a particular HTML tag (such as <TextField> and
<input> will support informal parameters.</p><p>Only components whose
class is annotated with @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SupportsInformalParameters.html";>SupportsInformalParameters</a>
will support informal parameters. Tapestry silently drops informal parameters
that are specified for components that do not have this
annotation.</p><p>Informal
parameters are often used to set the CSS class of an element, or to specify
client-side event handlers.</p><p>The default binding prefix for informal
parameters depends on <em>where</em> the parameter binding is specified. If the
parameter is bound inside a Java class, within the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation, then the default binding prefix is "prop:". If the parameter is
bound inside the component template, then the default binding prefix is
"literal:". This reflects the fact that a parameter specified in the Java
class, using the annotation, is most likely a computed value, whereas a value
in the template should simply be copied, as is, into the result HTML
stream.</p><p>Informal parameters (if supported) are always rendered into the
output <em>unless</em> they are bound to a property whose value is null. If the
bound property is null then the parameter will <em
>not</em> be present at all in the rendered output.</p><p>If your component
>should render informal parameters, just inject the <a class="external-link"
>href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>ComponentResources</a>
> for your component and invoke the <code>renderInformalParameters()</code>
>method. See <a href="supporting-informal-parameters.html">Supporting
>Informal Parameters</a> for an example of how to do this.</p><h1
>id="ComponentParameters-ParametersAreBi-Directional">Parameters Are
>Bi-Directional</h1><p>Parameters are not simply variables; each parameter
>represents a connection, or <em>binding</em>, between a component and a
>property of its container. When using the prop: binding prefix, the component
>can force changes <em>into</em> a property of its container, just by
>assigning a value to its own instance variable.</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:layout
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:layout
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<p> Countdown:
<t:count start="5" end="1" result="index">
${index} ...
@@ -308,7 +308,7 @@ public String getDefaultMessage(){ 
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <p> Countdown: 5 ... 4 ... 3 ... 2 ... 1 ...
</p>
</pre>
</div></div><p>(Though the whitespace will be quite different.)</p><p>The
relevant part is that components can read fixed values, or <em>live</em>
properties of their container, and can <em>change</em> properties of their
container as well.</p><h1
id="ComponentParameters-InheritedParameterBindings">Inherited Parameter
Bindings</h1><p>A special prefix, "inherit:" is used to identify the name of a
parameter of the containing component. If the parameter is bound in the
containing component, then it will be bound to the same value in the embedded
component.</p><p>If the parameter is not bound in the containing component,
then it will not be bound in the embedded component (and so, the embedded
component may use a default binding).</p><p>Inherited bindings are useful for
complex components; they are often used when an inner component has a default
value for a parameter, and the outer component wants to make it possible to
override that default.</p><div class="code panel pdl" style="borde
r-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Index.tml</b></div><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">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><html
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<body>
<div t:type="layout" t:menuTitle="literal:The Title">
...
@@ -317,7 +317,7 @@ public String getDefaultMessage(){ 
</html>
</pre>
</div></div><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Layout.tml</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:container
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:container
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<div t:type="title" t:title="inherit:menuTitle"></div>
@@ -375,19 +375,19 @@ public class Title {
return String.format("Maximum field length is %d.", maxLength);
}
</pre>
-</div></div><p>This form is more like using the "literal:" binding prefix,
except that the literal value is computed by the defaultMessage()
method.</p><p>Obviously, this is a lot more work than simply specifying a
default value as part of the @Parameter annotation. In the few real cases where
this is approach is used, the default binding method will usually deduce a
proper binding, typically in terms of the component's id. For example, the
TextField component will deduce a value parameter that binds to a property of
its container with the same name.</p><p>A default binding method will
<em>only</em> be invoked if the @Parameter annotation does not provide a
default value.</p><h1 id="ComponentParameters-UnboundParameters">Unbound
Parameters</h1><p>If a parameter is not bound (and is optional), then the value
may be read or <em>updated</em> at any time.</p><p>Updates to unbound
parameters cause no side effects. In the first example, the value parameter of
the Count component is not bo
und, and this is perfectly valid.</p><p>Note: updates to such fields are
temporary; when the component <em>finishes rendering</em>, the field will
revert to its default value.</p><h1
id="ComponentParameters-ParameterTypeCoercion">Parameter Type
Coercion</h1><p>Main Article: <a
href="parameter-type-coercion.html">Parameter Type Coercion</a> </p><p>Tapestry
includes a mechanism for <span class="confluence-link">coercing types
automatically</span>. Most often, this is used to convert literal strings into
appropriate values, but in many cases, more complex conversions will occur.
This mechanism is used for component parameters, such as when an outer
component passes a literal string to an inner component that is expecting an
integer.</p><p>You can easily <a href="component-parameters.html">contribute
new coercions</a> for your own purposes.</p><h1
id="ComponentParameters-ParameterNames">Parameter Names</h1><p>By default,
Tapestry converts from the field name to the parameter name
, by stripping off leading "$" and "_" characters.</p><p>This can be
overridden using the name() attribute of the @Parameter annotation.</p><h1
id="ComponentParameters-DeterminingifBound">Determining if Bound</h1><p>In rare
cases, you may want to take different behaviors based on whether a parameter is
bound or not. This can be accomplished by querying the component's resources,
which can be <a href="component-parameters.html">injected</a> into the
component using the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div></div><p>This form is more like using the "literal:" binding prefix,
except that the literal value is computed by the defaultMessage()
method.</p><p>Obviously, this is a lot more work than simply specifying a
default value as part of the @Parameter annotation. In the few real cases where
this is approach is used, the default binding method will usually deduce a
proper binding, typically in terms of the component's id. For example, the
TextField component will deduce a value parameter that binds to a property of
its container with the same name.</p><p>A default binding method will
<em>only</em> be invoked if the @Parameter annotation does not provide a
default value.</p><h1 id="ComponentParameters-UnboundParameters">Unbound
Parameters</h1><p>If a parameter is not bound (and is optional), then the value
may be read or <em>updated</em> at any time.</p><p>Updates to unbound
parameters cause no side effects. In the first example, the value parameter of
the Count component is not bo
und, and this is perfectly valid.</p><p>Note: updates to such fields are
temporary; when the component <em>finishes rendering</em>, the field will
revert to its default value.</p><h1
id="ComponentParameters-ParameterTypeCoercion">Parameter Type
Coercion</h1><p>Main Article: <a
href="parameter-type-coercion.html">Parameter Type Coercion</a></p><p>Tapestry
includes a mechanism for <span class="confluence-link">coercing types
automatically</span>. Most often, this is used to convert literal strings into
appropriate values, but in many cases, more complex conversions will occur.
This mechanism is used for component parameters, such as when an outer
component passes a literal string to an inner component that is expecting an
integer.</p><p>You can easily <a href="type-coercion.html">contribute new
coercions</a> for your own purposes.</p><h1
id="ComponentParameters-ParameterNames">Parameter Names</h1><p>By default,
Tapestry converts from the field name to the parameter name, by str
ipping off leading "$" and "_" characters.</p><p>This can be overridden using
the name() attribute of the @Parameter annotation.</p><h1
id="ComponentParameters-DeterminingifBound">Determining if Bound</h1><p>In rare
cases, you may want to take different behaviors based on whether a parameter is
bound or not. This can be accomplished by querying the component's resources,
which can be <a href="injection.html">injected</a> into the component using
the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation:</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 MyComponent
{
@Parameter
private int myParam;
@Inject
- private ComponentResources resources;
+ private ComponentResources componentResources;
@BeginRender
void setup()
{
- if (resources.isBound("myParam"))
+ if (componentResources.isBound("myParam"))
{
. . .
}
@@ -395,7 +395,7 @@ public class Title {
}
</pre>
</div></div><p>The above sketch illustrates the approach. Because the
parameter type is a primitive type, int, it is hard to distinguish between no
binding, and binding explicitly to the value 0.</p><p>The @Inject annotation
will inject the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>ComponentResources</a>
for the component. These resources are the linkage between the Java class you
provide, and the infrastructure Tapestry builds around your class. In any case,
once the resources are injected, they can be queried.</p><h1
id="ComponentParameters-PublishingParameters">Publishing
Parameters</h1><p>Often when creating new components from existing components,
you want to expose some of the functionality of the embedded component, in the
form of exposing parameters of the embedded components as parameters of the
outer component.</p><p>In Tapestry 5.0, you would define a parameter of the
outer component, and use t
he "inherit:" binding prefix to connect the inner component's parameter to the
outer component's parameter. This is somewhat clumsy, as it involves creating
an otherwise unused field just for the parameter; in practice it also leads to
duplication of the documentation of the parameter.</p><p>In Tapestry 5.1 and
later, you may use the publishParameters attribute of the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation. List one or more parameters separated by commas: those parameters
of the inner/embedded component become parameters of the outer component. You
should <strong>not</strong> define a parameter field in the outer
component.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>ContainerComponent.tml</b></div><div class="codeContent panelContent
pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:container
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:container
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<t:pageLink t:id="link">Page Link</t:pageLink>
</t:container>
</pre>
