Author: buildbot
Date: Sun Feb 25 23:20:05 2018
New Revision: 1025970
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/annotations.html
websites/production/tapestry/content/beaneditform-guide.html
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/class-reloading.html
websites/production/tapestry/content/component-classes.html
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/component-rendering.html
websites/production/tapestry/content/component-templates.html
websites/production/tapestry/content/configuration.html
websites/production/tapestry/content/dom.html
websites/production/tapestry/content/extending-the-if-component.html
websites/production/tapestry/content/layout-component.html
websites/production/tapestry/content/legacy-javascript.html
websites/production/tapestry/content/localization.html
websites/production/tapestry/content/page-life-cycle.html
websites/production/tapestry/content/page-navigation.html
websites/production/tapestry/content/parameter-type-coercion.html
websites/production/tapestry/content/project-layout.html
websites/production/tapestry/content/property-expressions.html
websites/production/tapestry/content/request-processing.html
websites/production/tapestry/content/runtime-exceptions.html
websites/production/tapestry/content/supported-environments-and-versions.html
websites/production/tapestry/content/switching-cases.html
Modified: websites/production/tapestry/content/annotations.html
==============================================================================
--- websites/production/tapestry/content/annotations.html (original)
+++ websites/production/tapestry/content/annotations.html Sun Feb 25 23:20:05
2018
@@ -100,7 +100,7 @@
</div>
-<p> </p><p>Tapestry relies heavily on Java <strong>annotations</strong>
rather than XML files for almost all of its configuration. (In addition,
Tapestry's method naming conventions mean you don't <em>have</em> to use
annotations in many cases.)</p><p>Tapestry annotations are grouped into several
distinct modules according to their purpose.</p><h2
id="Annotations-TapestryCoreandIoCAnnotations">Tapestry Core and IoC
Annotations</h2><p>The majority of Tapestry annotations (those defined in the
tapestry-core and tapestry-ioc modules) are very specific to Tapestry
components or Tapestry IoC services:</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/annotations/package-summary.html";>Tapestry
Component Annotations</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>intended for use in page/component/mixin c
lasses</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/ioc/annotations/package-summary.html";>Tapestry
IoC Annotations</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>for use by IoC
services</p></td></tr></tbody></table></div><h2
id="Annotations-Annotationsfordataholdingclasses">Annotations for data holding
classes</h2><p>In addition to the core and IoC annotations, there are a few
annotations intended for data holding classes that are not Tapestry components;
these annotations allow high-level components such as Grid and BeanEditForm to
create powerful user interfaces with out any additional coding. Because these
annotations are separated from the rest of Tapestry, they can be used inside
your data tier classes <em>without</em> having to bring all of Tapestry into
your classpath. This is very useful in multi-tier applications where data
objects may ori
ginate in an application tier (such as a JEE application server) and travel to
the presentation tier (a Tapestry application).</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/beaneditor/package-summary.html";>BeanEditForm
Annotations</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>for users of the BeanEditForm and Grid
components</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/hibernate/annotations/package-summary.html";>Hibernate
Annotations</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>for users of the Tapestry-Hibernate
library</p></td></tr></tbody></table></div><h2
id="Annotations-UpgradeNotes–Release5.0.12">Upgrade Notes – Release
5.0.12</h2><p>The artif
act id for the annotations module has changed from
<code>tapestry-annotations</code> to <code>tapestry5-annotations</code>. This
is necessary to support Tapestry 4 and Tapestry 5 applications co-existing
within a single WAR.</p></div>
+<p> </p><p>Tapestry relies heavily on Java <strong>annotations</strong>
rather than XML files for almost all of its configuration. (In addition,
Tapestry's method naming conventions mean you don't <em>have</em> to use
annotations in many cases.)</p><p>Tapestry annotations are grouped into several
distinct modules according to their purpose.</p><h2
id="Annotations-TapestryCoreandIoCAnnotations">Tapestry Core and IoC
Annotations</h2><p>The majority of Tapestry annotations (those defined in the
tapestry-core and tapestry-ioc modules) are very specific to Tapestry
components or Tapestry IoC services:</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/annotations/package-summary.html";>Tapestry
Component Annotations</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>intended for use in page/component/mixin c
lasses</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/ioc/annotations/package-summary.html";>Tapestry
IoC Annotations</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>for use by IoC
services</p></td></tr></tbody></table></div><h2
id="Annotations-Annotationsfordataholdingclasses">Annotations for data holding
classes</h2><p>In addition to the core and IoC annotations, there are a few
annotations intended for data holding classes that are not Tapestry components;
these annotations allow high-level components such as Grid and BeanEditForm to
create powerful user interfaces with out any additional coding. Because these
annotations are separated from the rest of Tapestry, they can be used inside
your data tier classes <em>without</em> having to bring all of Tapestry into
your classpath. This is very useful in multi-tier applications where data
objects may ori
ginate in an application tier (such as a JEE application server) and travel to
the presentation tier (a Tapestry application).</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/beaneditor/package-summary.html";>BeanEditForm
Annotations</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>for users of the BeanEditForm and Grid
components</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/hibernate/annotations/package-summary.html";>Hibernate
Annotations</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>for users of the Tapestry-Hibernate
library</p></td></tr></tbody></table></div><h2
id="Annotations-UpgradeNotes–Release5.0.12">Upgrade Notes – Release
5.0.12</h2><p>The artif
act id for the annotations module has changed from
<code>tapestry-annotations</code> to <code>tapestry5-annotations</code>. This
is necessary to support Tapestry 4 and Tapestry 5 applications co-existing
within a single WAR.</p><p></p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/beaneditform-guide.html
==============================================================================
--- websites/production/tapestry/content/beaneditform-guide.html (original)
+++ websites/production/tapestry/content/beaneditform-guide.html Sun Feb 25
23:20:05 2018
@@ -31,8 +31,6 @@
<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();
@@ -77,11 +75,12 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>BeanEditForm</strong>
is a powerful Tapestry component capable of generating a complete create/edit
user interface for a typical JavaBean.</p><div class="navmenu"
style="float:right; background:#eee; margin:3px; padding:0 1em">
-<p> <strong>JumpStart Demos:</strong><br clear="none">
- <a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/input/edit1/1";
rel="nofollow">Edit (Using BeanEditForm)</a><br clear="none">
- <a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/input/create1";
rel="nofollow">Create (Using BeanEditForm)</a><br clear="none">
- <a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/input/morecontroledit1/1";
rel="nofollow">More Control Edit (Using BeanEditor)</a></p></div>BeanEditForm
analyzes the the properties of the bean, locating just those properties that
are readable and writeable. It filters down to properties whose type is mapped
to a known editor (this is described in more detail below).<p>The default
ordering for properties is in the order in which the <em>getter methods</em>
for the properties are defined. When a super-class defines editable properties,
those are ordered before sub-class properties.</p><h2
id="BeanEditFormGuide-SupportedTypes">Supported Types</h2><p>The default set of
property types supported by BeanEditForm:</p><ul><li>String: as a text
field</li><li>Number: as a text field</li><li>Enum: as a drop-down
list</li><li>Boolean: as a checkbox</li><li>Date: as a JavaScript
calendar</li><li>Calendar: as a JavaScript calendar</li></ul><p>Resolving
a property type to an editor type involves a search up the inheritance
hierarchy: thus the super-type of Integer, Long, BigDecimal, etc. is Number,
which uses a text field for data entry.</p><p>The list of supported property
types is extensible (this is documented below).</p><h2
id="BeanEditFormGuide-AutomaticObjectCreation">Automatic Object
Creation</h2><p>When a page is rendered, the BeanEditForm component will read
its object parameter as the JavaBean to edit (with the current properties of
the JavaBean becoming the defaults for the various fields). Likewise, when the
form is submitted by the user, the object parameter is read and its properties
populated from the request.</p><p>If the object does not exist, it will be
created as needed. The type is determined from the property type, which should
be a specific type in order for automatic creation to operate
properly.</p><p>The BeanEditForm component will attempt to instantiate a value
for the property as necessary, when the form
is submitted. This can be a problem when the property type is an interface,
rather than an instantiable class.</p><p>One option is to provide an event
handler for the "prepare" or "prepareForSubmit" events to instantiate an
instance to receive the submitted information.</p><p>For a class, Tapestry will
select the public constructor with the <em>most</em> parameters. If this is not
desirable (for example, if you get an exception), then place the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation on the constructor Tapestry should use.</p><h2
id="BeanEditFormGuide-ImplicitObjectBinding">Implicit Object Binding</h2><p>If
the object parameter is not bound, then an implicit binding to a property of
the containing component is made. The bound property will be the BeanEditForm
component's id, if such a property exists. Thus you may typically give the
BeanEditForm component an id (that matches a
property) and not have to bind the object parameter.</p><h2
id="BeanEditFormGuide-Non-VisualProperties">Non-Visual Properties</h2><p>In
some cases, a property may be updatable and of a supported type for editing,
but should not be presented to the user for editing: for example, a property
that holds the primary key of a database entity. In such a case, the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/NonVisual.html";>NonVisual</a>
annotation may be applied to the property (either the getter or the setter
method).</p><h2 id="BeanEditFormGuide-DefaultValidation">Default
Validation</h2><p>Default validation for fields is primary determined by
property type.</p><p>If desired, additional validation may be specified using
the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html";>Validate</a>
annotation. See <a href="forms-and-validation.html">Forms and Valid
ation</a>.</p><p>As of Tapestry 5.2, validation may also be specified via the
containing component's property file, using a key in the form of
<code>propertyId-validate</code> (eg: myfield-validate=required).</p><h2
id="BeanEditFormGuide-Propertyordering">Property ordering</h2><p>By default,
the order in which properties are presented is as defined above (order of the
getter method). This can be overridden using the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/ReorderProperties.html";>ReorderProperties</a>
class annotation.</p><h2 id="BeanEditFormGuide-DefaultLabel">Default
Label</h2><p>Tapestry will attempt to provide a reasonable default label for
each field, based on the property name being emitted. The property name is
capitalized, and spaces are added before case changes, thus property "name"
becomes label "Name" and property "streetAddress" becomes label "Street
Address".</p><p>BeanEditForm also searches for a label
for the field in the containing component's message catalog. The message key
is the property name suffixed with "-label". If such a label is found, it takes
precedence.</p><h1 id="BeanEditFormGuide-PropertyEditorOverrides">Property
Editor Overrides</h1><p>You may override the editor for any particular
property, using the a block parameter to the BeanEditForm component.</p><p>An
editor normally consists of a Label component and some form of field component
(such as TextField or TextArea).</p><p>For example, you may want to selectively
use a PasswordField component:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+ <div id="ConfluenceContent"><p><strong>BeanEditForm</strong>
is a powerful Tapestry component capable of generating a complete create/edit
user interface for a typical JavaBean.</p><div style="float: right; max-width:
30%; margin: 1em"><div class="panel" style="border-color: #eee;border-width:
1px;"><div class="panelHeader" style="border-bottom-width:
1px;border-bottom-color: #eee;background-color: #eee;"><b>JumpStart
Demos</b></div><div class="panelContent">
+<ul><li><p><a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/input/edit1/1";
rel="nofollow">Edit (Using BeanEditForm)</a></p></li><li><a
class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/input/create1";
rel="nofollow">Create (Using BeanEditForm)</a></li><li><a
class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/input/morecontroledit1/1";
rel="nofollow">More Control Edit (Using BeanEditor)</a></li></ul>
+</div></div></div>
+
+
+<p>BeanEditForm analyzes the the properties of the bean, locating just those
properties that are readable and writeable. It filters down to properties whose
type is mapped to a known editor (this is described in more detail
below).</p><p>The default ordering for properties is in the order in which the
<em>getter methods</em> for the properties are defined. When a super-class
defines editable properties, those are ordered before sub-class
properties.</p><h2 id="BeanEditFormGuide-SupportedTypes">Supported
Types</h2><p>The default set of property types supported by
BeanEditForm:</p><ul><li>String: as a text field</li><li>Number: as a text
field</li><li>Enum: as a drop-down list</li><li>Boolean: as a
checkbox</li><li>Date: as a JavaScript calendar</li><li>Calendar: as a
JavaScript calendar</li></ul><p>Resolving a property type to an editor type
involves a search up the inheritance hierarchy: thus the super-type of Integer,
Long, BigDecimal, etc. is Number, which uses a text field for da
ta entry.</p><p>The list of supported property types is extensible (this is
documented below).</p><h2
id="BeanEditFormGuide-AutomaticObjectCreation">Automatic Object
Creation</h2><p>When a page is rendered, the BeanEditForm component will read
its object parameter as the JavaBean to edit (with the current properties of
the JavaBean becoming the defaults for the various fields). Likewise, when the
form is submitted by the user, the object parameter is read and its properties
populated from the request.</p><p>If the object does not exist, it will be
created as needed. The type is determined from the property type, which should
be a specific type in order for automatic creation to operate
properly.</p><p>The BeanEditForm component will attempt to instantiate a value
for the property as necessary, when the form is submitted. This can be a
problem when the property type is an interface, rather than an instantiable
class.</p><p>One option is to provide an event handler for the "prepare" o
r "prepareForSubmit" events to instantiate an instance to receive the
submitted information.</p><p>For a class, Tapestry will select the public
constructor with the <em>most</em> parameters. If this is not desirable (for
example, if you get an exception), then place the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation on the constructor Tapestry should use.</p><h2
id="BeanEditFormGuide-ImplicitObjectBinding">Implicit Object Binding</h2><p>If
the object parameter is not bound, then an implicit binding to a property of
the containing component is made. The bound property will be the BeanEditForm
component's id, if such a property exists. Thus you may typically give the
BeanEditForm component an id (that matches a property) and not have to bind the
object parameter.</p><h2 id="BeanEditFormGuide-Non-VisualProperties">Non-Visual
Properties</h2><p>In some cases, a property may be updatable a
nd of a supported type for editing, but should not be presented to the user
for editing: for example, a property that holds the primary key of a database
entity. In such a case, the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/NonVisual.html";>NonVisual</a>
annotation may be applied to the property (either the getter or the setter
method).</p><h2 id="BeanEditFormGuide-DefaultValidation">Default
Validation</h2><p>Default validation for fields is primary determined by
property type.</p><p>If desired, additional validation may be specified using
the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html";>Validate</a>
annotation. See <a href="forms-and-validation.html">Forms and
Validation</a>.</p><p>As of Tapestry 5.2, validation may also be specified via
the containing component's property file, using a key in the form of
<code>propertyId-validate</code> (e
g: myfield-validate=required).</p><h2
id="BeanEditFormGuide-Propertyordering">Property ordering</h2><p>By default,
the order in which properties are presented is as defined above (order of the
getter method). This can be overridden using the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/ReorderProperties.html";>ReorderProperties</a>
class annotation.</p><h2 id="BeanEditFormGuide-DefaultLabel">Default
Label</h2><p>Tapestry will attempt to provide a reasonable default label for
each field, based on the property name being emitted. The property name is
capitalized, and spaces are added before case changes, thus property "name"
becomes label "Name" and property "streetAddress" becomes label "Street
Address".</p><p>BeanEditForm also searches for a label for the field in the
containing component's message catalog. The message key is the property name
suffixed with "-label". If such a label is found, it takes precedence.</p><h1 id
="BeanEditFormGuide-PropertyEditorOverrides">Property Editor
Overrides</h1><p>You may override the editor for any particular property, using
the a block parameter to the BeanEditForm component.</p><p>An editor normally
consists of a Label component and some form of field component (such as
TextField or TextArea).</p><p>For example, you may want to selectively use a
PasswordField component:</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;"> <t:beaneditform object="loginCredentials">
<p:password>
<t:label for="password"/>
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/class-reloading.html
==============================================================================
--- websites/production/tapestry/content/class-reloading.html (original)
+++ websites/production/tapestry/content/class-reloading.html Sun Feb 25
23:20:05 2018
@@ -31,8 +31,6 @@
<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();
@@ -111,11 +109,11 @@
<p>One of the best features of Tapestry is automatic reloading of changed
classes and templates. <em>Page and component</em> classes will automatically
reload when changed. Likewise, changes to component templates and other related
resources will also be picked up immediately. In addition, starting in version
5.2, your service classes will also be reloaded automatically after changes (if
you're using <a href="ioc.html">Tapestry IoC</a>).</p><h2
id="ClassReloading-Contents">Contents</h2><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1519597265966 {padding: 0px;}
-div.rbtoc1519597265966 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1519597265966 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1519600768313 {padding: 0px;}
+div.rbtoc1519600768313 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1519600768313 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1519597265966">
+/*]]>*/</style></p><div class="toc-macro rbtoc1519600768313">
<ul class="toc-indentation"><li><a
href="#ClassReloading-TemplateReloading">Template Reloading</a></li><li><a
href="#ClassReloading-ClassReloading">Class Reloading</a></li><li><a
href="#ClassReloading-PackagesScanned">Packages Scanned</a></li><li><a
href="#ClassReloading-FileSystemOnly">File System Only</a></li><li><a
href="#ClassReloading-ClassLoaderIssues">Class Loader Issues</a></li><li><a
href="#ClassReloading-ClassCastExceptions">ClassCastExceptions</a></li><li><a
href="#ClassReloading-HandlingReloadsinyourCode">Handling Reloads in your
Code</a></li><li><a href="#ClassReloading-CheckingForUpdates">Checking For
Updates</a></li><li><a
href="#ClassReloading-TroubleshootingLiveClassReloading">Troubleshooting Live
Class Reloading</a>
<ul class="toc-indentation"><li><a
href="#ClassReloading-QuickChecklist">Quick Checklist</a></li><li><a
href="#ClassReloading-IfLiveClassReloadingdoesn'twork">If Live Class Reloading
doesn't work</a>
<ul class="toc-indentation"><li><a
href="#ClassReloading-ProductionMode">Production Mode</a></li><li><a
href="#ClassReloading-BuildPathIssues">Build Path Issues</a></li><li><a
href="#ClassReloading-BuildingAutomatically">Building
Automatically</a></li><li><a
href="#ClassReloading-TurnoffJVMhotcodeswapping&automaticrestarts">Turn off
JVM hot code swapping & automatic restarts</a></li></ul>
@@ -142,7 +140,7 @@ div.rbtoc1519597265966 li {margin-left:
</div></div><p>This is the intent of service builder methods; to do more than
just injecting dependencies.</p><h2
id="ClassReloading-CheckingForUpdates">Checking For Updates</h2><p>The built in
InvalidationEventHub services provide notifications of changes to component
classes, to component templates, and to component message catalogs. If you wish
to check some other resources (for example, files in a directory of the file
system or rows in a database table), you should register as an <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/UpdateListener.html";>UpdateListener</a>
with the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/UpdateListenerHub.html";>UpdateListenerHub</a>
service.</p><p>Periodically (the frequency is configurable), UpdateListeners
are notified that they should check for updates. Typically, UpdateListeners are
also InvalidationEventHubs (or provide Invali
dationEventHubs), so that other interested parties can be alerted when
underlying data changes.</p><h2
id="ClassReloading-TroubleshootingLiveClassReloading">Troubleshooting Live
Class Reloading</h2><h3 id="ClassReloading-QuickChecklist">Quick
Checklist</h3><ul><li>"Production Mode" must be false (in Tapestry 5.3 and
later)</li><li>The class must be one that Tapestry instantiates (a page,
component, or mixin class, or a Tapestry IOC service implementation that
implements an interface)</li><li>Turn on "Build Automatically" in your IDE, or
remember to build manually.</li><li>Turn <em>off</em> JVM hot code swapping, if
your servlet container supports it.</li><li>Eclipse: Uncheck the "derived"
checkbox for the Target dir (in the Project Explorer view, right click on
"target", select properties, uncheck "derived" on the Resource
tab)</li></ul><p>Some of these issues are described in more detail
below.</p><h3 id="ClassReloading-IfLiveClassReloadingdoesn'twork">If Live Class
Reloading doesn
't work</h3><h4 id="ClassReloading-ProductionMode">Production
Mode</h4><p>Starting with Tapestry 5.3, Live Class Reloading only works when
not in "Production Mode". Check your application module (usually
AppModule.java) to be sure you have:</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;">configuration.add(SymbolConstants.PRODUCTION_MODE,
"false");
</pre>
-</div></div><p>and that this isn't being overridden to "true" on your
application's startup command line.</p><h4
id="ClassReloading-BuildPathIssues">Build Path Issues</h4><p>Live Class
Reloading can fail if your build path isn't set correctly, and the exact
configuration may differ between Maven plugin versions and Eclipse versions.
The build process must be set to create classes in a folder which is in the
servlet container's classpath.</p><p>Live Class Reloading won't work correctly
with vanilla Tomcat without some tweaks (see below).</p><p>Non-Tapestry filters
can interfere with LCR. Try disabling other filters in your web.xml file to see
if that helps.</p><h4 id="ClassReloading-BuildingAutomatically">Building
Automatically</h4><p>Although LCR allows you to see changes without restarting
your app, you still need to "build" your project (to compile the Java source
into byte code). Your IDE can be set to do this automatically every time you
save a file. (In Eclipse, this is done us
ing <code>Project > Build Automatically</code>.) Alternatively, you can
manually trigger a build after you save a file. (In Eclipse, this is done using
<code>Project > Build</code>, or by pressing <code>Control-B</code>.)</p><h4
id="ClassReloading-TurnoffJVMhotcodeswapping&automaticrestarts">Turn off
JVM hot code swapping & automatic restarts</h4><p>Many servlet containers,
including Tomcat and Jetty, support various forms of hot code swapping and/or
automatic restarts when file changes are detected. These are generally
<strong>much slower</strong> than LCR and usually should be turned off with
Tapestry applications. If you're using RunJettyRun plugin for Eclipse, for
example, edit your Run Configuration, and on the Jetty tab, click Show Advanced
Options and uncheck the Enable Scanner checkbox.</p><h3
id="ClassReloading-TomcatSpecifics">Tomcat Specifics</h3><p>See <a
class="external-link"
href="http://www.tynamo.org/Developing+with+Tomcat+and+Eclipse/"; rel="nofollow">
these Tomcat-specific hints</a></p><h3
id="ClassReloading-IfLiveClassReloadingworksbutisslow">If Live Class Reloading
works but is slow</h3><p>If LCR works for you but is slow (more than a second
or two), consider the following.</p><ul><li>Be sure your project source files
(your workspace in Eclipse, for example), are on a local drive, NOT a network
location. Network drives are always slower, and the file system scanning needed
for LCR can add a noticable lag if I/O is slow. If you use Maven, be sure to
put your local repository (e.g. ~/.m2/repository) on a local drive for similar
reasons.</li><li><p>Java 7 and below: Since LCR adds classes to your PermGen
space, you may be running low on PermGen memory (and may eventually get a
"java.lang.OutOfMemoryError: PermGen space" error). Try increasing PermGen size
with a JVM argument of something like -XX:MaxPermSize=400m. (PermGen
settings are not relevant for Java 8 and
above.)</p></li></ul><p> </p></div>
+</div></div><p>and that this isn't being overridden to "true" on your
application's startup command line.</p><h4
id="ClassReloading-BuildPathIssues">Build Path Issues</h4><p>Live Class
Reloading can fail if your build path isn't set correctly, and the exact
configuration may differ between Maven plugin versions and Eclipse versions.
The build process must be set to create classes in a folder which is in the
servlet container's classpath.</p><p>Live Class Reloading won't work correctly
with vanilla Tomcat without some tweaks (see below).</p><p>Non-Tapestry filters
can interfere with LCR. Try disabling other filters in your web.xml file to see
if that helps.</p><h4 id="ClassReloading-BuildingAutomatically">Building
Automatically</h4><p>Although LCR allows you to see changes without restarting
your app, you still need to "build" your project (to compile the Java source
into byte code). Your IDE can be set to do this automatically every time you
save a file. (In Eclipse, this is done us
ing <code>Project > Build Automatically</code>.) Alternatively, you can
manually trigger a build after you save a file. (In Eclipse, this is done using
<code>Project > Build</code>, or by pressing <code>Control-B</code>.)</p><h4
id="ClassReloading-TurnoffJVMhotcodeswapping&automaticrestarts">Turn off
JVM hot code swapping & automatic restarts</h4><p>Many servlet containers,
including Tomcat and Jetty, support various forms of hot code swapping and/or
automatic restarts when file changes are detected. These are generally
<strong>much slower</strong> than LCR and usually should be turned off with
Tapestry applications. If you're using RunJettyRun plugin for Eclipse, for
example, edit your Run Configuration, and on the Jetty tab, click Show Advanced
Options and uncheck the Enable Scanner checkbox.</p><h3
id="ClassReloading-TomcatSpecifics">Tomcat Specifics</h3><p>See <a
class="external-link"
href="http://www.tynamo.org/Developing+with+Tomcat+and+Eclipse/"; rel="nofollow">
these Tomcat-specific hints</a></p><h3
id="ClassReloading-IfLiveClassReloadingworksbutisslow">If Live Class Reloading
works but is slow</h3><p>If LCR works for you but is slow (more than a second
or two), consider the following.</p><ul><li>Be sure your project source files
(your workspace in Eclipse, for example), are on a local drive, NOT a network
location. Network drives are always slower, and the file system scanning needed
for LCR can add a noticable lag if I/O is slow. If you use Maven, be sure to
put your local repository (e.g. ~/.m2/repository) on a local drive for similar
reasons.</li><li><p>Java 7 and below: Since LCR adds classes to your PermGen
space, you may be running low on PermGen memory (and may eventually get a
"java.lang.OutOfMemoryError: PermGen space" error). Try increasing PermGen size
with a JVM argument of something like -XX:MaxPermSize=400m. (PermGen
settings are not relevant for Java 8 and
above.)</p></li></ul><p></p><p> </p><p> </p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/component-classes.html
==============================================================================
--- websites/production/tapestry/content/component-classes.html (original)
+++ websites/production/tapestry/content/component-classes.html Sun Feb 25
23:20:05 2018
@@ -171,7 +171,7 @@ public class HelloWorld
}
}
</pre>
-</div></div><p>In this example, just like the first one, the component's only
job is to write out a fixed message. The @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender.html";>BeginRender</a>
annotation is a type of <em><a href="component-rendering.html">render phase
annotation</a></em></p><p>, a method annotation that instructs Tapestry when
and under what circumstances to invoke methods of your class.</p><p>These
methods are not necessarily public; they can have any access level you like
(unlike in Tapestry 4). By convention they usually have package-private access
level (the default).</p><h2 id="ComponentClasses-ComponentPackages">Component
Packages</h2><p>Component classes must exist within an appropriate package
(this is necessary for runtime code transformation and class reloading to
operate).</p><p>These packages exist under the application's root package, as
follows:</p><ul><li>For pages, place classes in
<em>root</em>.<strong>pages</strong>. Page names are mapped to classes within
this package.</li><li>For mixins, place classes in
<em>root</em>.<strong>mixins</strong>. Mixin types are mapped to classes within
this package.</li><li>For other components, place classes in
<em>root</em>.<strong>components</strong>. Component types are mapped to
classes within this package.</li></ul><p>In addition, it is common for an
application to have base classes, often <em>abstract</em> base classes, that
should not be directly referenced. These should <em>not</em> go in the
<strong>pages</strong>, <strong>components</strong> or <strong>mixins</strong>
packages, because they then look like valid pages, components or mixins.
Instead, use the <em>root</em>.<strong>base</strong> package to store such base
classes.</p><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-error confluence-information-macro-icon"></span><div class
="confluence-information-macro-body"><p>Only component classes should go in
any of these controlled packages; classes representing data, or interfaces, or
anything that isn't precisely a component class, must go elsewhere. Any
top-level class in any of the controlled packages will be transformed at
runtime. The only exception is inner classes (anonymous or not), which are
loaded by the same class loader as the component class loader, but not
transformed as components.</p></div></div><h2
id="ComponentClasses-Sub-Folders/Sub-Packages">Sub-Folders /
Sub-Packages</h2><p>Classes do not have to go directly inside the package
(pages, components, mixins, etc.). It is valid to create a sub-package to store
some of the classes. The sub-package name becomes part of the page name or
component type. Thus you might define a page component
<code>com.example.myapp.pages.admin.CreateUser</code> and the logical page name
(which often shows up inside URLs) will be <strong>admin/CreateUser</strong>.</p
><p>Tapestry performs some simple optimizations of the logical page name (or
>component type, or mixin type). It checks to see if the package name is
>either a prefix or a suffix of the unqualified class name (case
>insensitively, of course) and removes the prefix or suffix if so. The net
>result is that a class name such as
><code>com.example.myapp.pages.user.EditUser</code> will have a page name of
><code>user/Edit</code> (instead of user<code>/EditUser</code>). The goal here
>is to provide shorter, more natural URLs.</p><h2
>id="ComponentClasses-IndexPages">Index Pages</h2><p>One special
>simplification exists for Index pages: if the logical page name is Index
>after removing the package name from the unqualified class name, it will map
>to the root of that folder. A class such as
><code>com.example.myapp.pages.user.IndexUser</code> or
><code>com.example.myapp.pages.user.UserIndex</code> will have a page name of
><code>user/</code>.</p><p>In previous versions of Tapestry there was also the
>con
cept of a start page configured with the <code><a
href="configuration.html">tapestry.start-page-name</a></code> configuration
symbol (defaults to "start"). If a page with a name as configured with that
symbol exists at the root level, this page is used as the root URL. This has
precedence over an existing Index page. If for example you have a page class
<code>com.example.myapp.pages.Start</code> it will map to
<code>/</code>.</p><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-error confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Use of start-pages is discouraged
and support for it will eventually be removed. Use an Index page
instead.</p></div></div><h2 id="ComponentClasses-Pagesvs.Components">Pages vs.
Components</h2><p>The distinction between pages and component is very, very
small. The primary difference is the package name:
<em>root</em>.<strong>pages</st
rong>.<em>PageName</em> for pages, and
<em>root</em>.<strong>components</strong>.<em>ComponentType</em> for
components. Conceptually, page components are simply the <em>root
component</em> of a page's component tree.</p><p><em>For Tapestry 4 users:
there was a much greater distinction in Tapestry 4 between pages and
components, which showed up as separate interfaces and a hierarchy of abstract
implementations to extend your classes from.</em></p><h2
id="ComponentClasses-ClassTransformation">Class Transformation</h2><p>Tapestry
uses your class as a starting point. It <em>transforms</em> your class at
runtime. This is necessary for a number of reasons, including to address how
Tapestry shares pages between requests.</p><p>For the most part, these
transformations are both sensible and invisible. In a few limited cases, they
comprise a marginally <a class="external-link"
href="http://www.joelonsoftware.com/printerFriendly/articles/LeakyAbstractions.html";
rel="nofollow">leaky abstr
action</a> – for instance, the scope restrictions on instance
variables described below – but the programming model in general supports
a very high level of developer productivity.</p><p>Because transformation
doesn't occur until <em>runtime</em>, the build stage of your application is
not affected by the fact that you are creating a Tapestry application. Further,
your classes are absolutely simple POJOs during unit testing.</p><h2
id="ComponentClasses-LiveClassReloading">Live Class Reloading</h2><p>Main
Article: <a href="class-reloading.html">Class Reloading</a></p><p>Component
classes are monitored for changes by the framework. <a
href="class-reloading.html">Classes are reloaded when changed</a>. This allows
you to build your application with a speed approaching that of a scripting
environment, without sacrificing any of the power of the Java
platform.</p><p>And it's fast! You won't even notice that this magic class
reloading has occurred.</p><p>The net result:
super productivity — change your class, see the change instantly. This
is designed to be a blend of the best of scripting environments (such as Python
or Ruby) with all the speed and power of Java backing it up.</p><p>However,
class reloading <em>only</em> applies to component classes (pages, components
and mixins) and, starting in 5.2, Tapestry IOC-based service implementations
(with some restrictions). Other classes, such as service interfaces,
entity/model classes, and other data objects, are loaded by the normal class
loader and not subject to live class reloading.</p><h2
id="ComponentClasses-InstanceVariables">Instance Variables</h2><p>Tapestry
components may have instance variables (unlike Tapestry 4, where you had to use
<em>abstract properties</em>).</p><p>Since release 5.3.2, instance variables
may be protected, or package private (that is, no access modifier). Under
specific circumstances they may even be public (public fields must either be
final, or have the @<a c
lass="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Retain.html";>Retain</a> annotation).</p><p><span>Be
aware that you will need to either provide getter and setter methods to access
your classes' instance variables, or else annotate the fields
with</span><span> @</span><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Property.html";>Property</a>.</p><h2
id="ComponentClasses-TransientInstanceVariables">Transient Instance
Variables</h2><p>Unless an instance variable is decorated with an annotation,
it will be a <em>transient</em> instance variable. This means that its value
resets to its default value at the end of reach request (when the <a
href="page-life-cycle.html">page is detached from the
request</a></p><p>).</p><div class="confluence-information-macro
confluence-information-macro-note"><p class="title">About
initialization</p><span class="aui-icon aui-icon-sm
all aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Never initialize an instance field
to a <em>mutable</em> object at the point of declaration. If this is done, the
instance created from that initializer becomes the default value for that field
and is reused inside the component on every request. This could cause state to
inadvertently be shared between different sessions in an
application.</p></div></div>
+</div></div><p>In this example, just like the first one, the component's only
job is to write out a fixed message. The @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender.html";>BeginRender</a>
annotation is a type of <em><a href="component-rendering.html">render phase
annotation</a></em></p><p>, a method annotation that instructs Tapestry when
and under what circumstances to invoke methods of your class.</p><p>These
methods are not necessarily public; they can have any access level you like
(unlike in Tapestry 4). By convention they usually have package-private access
level (the default).</p><h2 id="ComponentClasses-ComponentPackages">Component
Packages</h2><p>Component classes must exist within an appropriate package
(this is necessary for runtime code transformation and class reloading to
operate).</p><p>These packages exist under the application's root package, as
follows:</p><ul><li>For pages, place classes in
<em>root</em>.<strong>pages</strong>. Page names are mapped to classes within
this package.</li><li>For mixins, place classes in
<em>root</em>.<strong>mixins</strong>. Mixin types are mapped to classes within
this package.</li><li>For other components, place classes in
<em>root</em>.<strong>components</strong>. Component types are mapped to
classes within this package.</li></ul><p>In addition, it is common for an
application to have base classes, often <em>abstract</em> base classes, that
should not be directly referenced. These should <em>not</em> go in the
<strong>pages</strong>, <strong>components</strong> or <strong>mixins</strong>
packages, because they then look like valid pages, components or mixins.
Instead, use the <em>root</em>.<strong>base</strong> package to store such base
classes.</p><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-error confluence-information-macro-icon"></span><div class
="confluence-information-macro-body"><p>Only component classes should go in
any of these controlled packages; classes representing data, or interfaces, or
anything that isn't precisely a component class, must go elsewhere. Any
top-level class in any of the controlled packages will be transformed at
runtime. The only exception is inner classes (anonymous or not), which are
loaded by the same class loader as the component class loader, but not
transformed as components.</p></div></div><h2
id="ComponentClasses-Sub-Folders/Sub-Packages">Sub-Folders /
Sub-Packages</h2><p>Classes do not have to go directly inside the package
(pages, components, mixins, etc.). It is valid to create a sub-package to store
some of the classes. The sub-package name becomes part of the page name or
component type. Thus you might define a page component
<code>com.example.myapp.pages.admin.CreateUser</code> and the logical page name
(which often shows up inside URLs) will be <strong>admin/CreateUser</strong>.</p
><p>Tapestry performs some simple optimizations of the logical page name (or
>component type, or mixin type). It checks to see if the package name is
>either a prefix or a suffix of the unqualified class name (case
>insensitively, of course) and removes the prefix or suffix if so. The net
>result is that a class name such as
><code>com.example.myapp.pages.user.EditUser</code> will have a page name of
><code>user/Edit</code> (instead of user<code>/EditUser</code>). The goal here
>is to provide shorter, more natural URLs.</p><h2
>id="ComponentClasses-IndexPages">Index Pages</h2><p>One special
>simplification exists for Index pages: if the logical page name is Index
>after removing the package name from the unqualified class name, it will map
>to the root of that folder. A class such as
><code>com.example.myapp.pages.user.IndexUser</code> or
><code>com.example.myapp.pages.user.UserIndex</code> will have a page name of
><code>user/</code>.</p><p>In previous versions of Tapestry there was also the
>con
cept of a start page configured with the <code><a
href="configuration.html">tapestry.start-page-name</a></code> configuration
symbol (defaults to "start"). If a page with a name as configured with that
symbol exists at the root level, this page is used as the root URL. This has
precedence over an existing Index page. If for example you have a page class
<code>com.example.myapp.pages.Start</code> it will map to
<code>/</code>.</p><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-error confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Use of start-pages is discouraged
and support for it will eventually be removed. Use an Index page
instead.</p></div></div><h2 id="ComponentClasses-Pagesvs.Components">Pages vs.
Components</h2><p>The distinction between pages and component is very, very
small. The primary difference is the package name:
<em>root</em>.<strong>pages</st
rong>.<em>PageName</em> for pages, and
<em>root</em>.<strong>components</strong>.<em>ComponentType</em> for
components. Conceptually, page components are simply the <em>root
component</em> of a page's component tree.</p><p><em>For Tapestry 4 users:
there was a much greater distinction in Tapestry 4 between pages and
components, which showed up as separate interfaces and a hierarchy of abstract
implementations to extend your classes from.</em></p><h2
id="ComponentClasses-ClassTransformation">Class Transformation</h2><p>Tapestry
uses your class as a starting point. It <em>transforms</em> your class at
runtime. This is necessary for a number of reasons, including to address how
Tapestry shares pages between requests.</p><p>For the most part, these
transformations are both sensible and invisible. In a few limited cases, they
comprise a marginally <a class="external-link"
href="http://www.joelonsoftware.com/printerFriendly/articles/LeakyAbstractions.html";
rel="nofollow">leaky abstr
action</a> – for instance, the scope restrictions on instance
variables described below – but the programming model in general supports
a very high level of developer productivity.</p><p>Because transformation
doesn't occur until <em>runtime</em>, the build stage of your application is
not affected by the fact that you are creating a Tapestry application. Further,
your classes are absolutely simple POJOs during unit testing.</p><h2
id="ComponentClasses-LiveClassReloading">Live Class Reloading</h2><p>Main
Article: <a href="class-reloading.html">Class Reloading</a></p><p>Component
classes are monitored for changes by the framework. <a
href="class-reloading.html">Classes are reloaded when changed</a>. This allows
you to build your application with a speed approaching that of a scripting
environment, without sacrificing any of the power of the Java
platform.</p><p>And it's fast! You won't even notice that this magic class
reloading has occurred.</p><p>The net result:
super productivity — change your class, see the change instantly. This
is designed to be a blend of the best of scripting environments (such as Python
or Ruby) with all the speed and power of Java backing it up.</p><p>However,
class reloading <em>only</em> applies to component classes (pages, components
and mixins) and, starting in 5.2, Tapestry IOC-based service implementations
(with some restrictions). Other classes, such as service interfaces,
entity/model classes, and other data objects, are loaded by the normal class
loader and not subject to live class reloading.</p><h2
id="ComponentClasses-InstanceVariables">Instance Variables</h2><p>Tapestry
components may have instance variables (unlike Tapestry 4, where you had to use
<em>abstract properties</em>).</p><p>Since release 5.3.2, instance variables
may be protected, or package private (that is, no access modifier). Under
specific circumstances they may even be public (public fields must either be
final, or have the @<a c
lass="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Retain.html";>Retain</a> annotation).</p><p><span>Be
aware that you will need to either provide getter and setter methods to access
your classes' instance variables, or else annotate the fields
with</span><span> @</span><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Property.html";>Property</a>.</p><h2
id="ComponentClasses-TransientInstanceVariables">Transient Instance
Variables</h2><p>Unless an instance variable is decorated with an annotation,
it will be a <em>transient</em> instance variable. This means that its value
resets to its default value at the end of reach request (when the <a
href="page-life-cycle.html">page is detached from the request</a>).</p><div
class="confluence-information-macro confluence-information-macro-note"><p
class="title">About initialization</p><span class="aui-icon aui-icon-small aui
-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Never initialize an instance field
to a <em>mutable</em> object at the point of declaration. If this is done, the
instance created from that initializer becomes the default value for that field
and is reused inside the component on every request. This could cause state to
inadvertently be shared between different sessions in an
application.</p></div></div>
<div class="aui-message aui-message-warning macro-deprecated"><b
class="param-deprecated">Deprecated since 5.2</b>
@@ -209,7 +209,7 @@ public class Countdown
private int countValue;
}
</pre>
-</div></div><p>The above defines a component whose embedded id is "count"
(this id is derived from the name of the field and an element with that id must
be present in the corresponding template, otherwise an error is displayed (see
below)). The type of the component is org.example.app.components.Count. The
start and end parameters of the Count component are bound to literal values,
and the value parameter of the Count component is bound to the countValue
property of the Countdown component.</p><p>Technically, the start and end
parameters should be bound to properties, just like the value parameter.
However, certain literal values, such as the numeric literals in the example,
are accepted by the <code>prop:</code> binding prefix even though they are not
actually properties (this is largely as a convenience to the application
developer). We could also use the <code>literal:</code> prefix,
<code>"start=literal:5"</code>, which accomplishes largely the same
thing.</p><p>You may specify
additional parameters inside the component template, but parameters in the
component class take precedence.</p><p><strong>TODO: May want a more complex
check; what if user uses prop: in the template and there's a
conflict?</strong></p><p>You may override the default component id (as derived
from the field name) using the id() attribute of the Component
annotation.</p><p>If you define a component in the component class, and there
is no corresponding element in the template, Tapestry will log an error. In the
example above that would be the case if the template for the Countdown page
didn't contain an element with <code><t:count
t:id="count"></code>.</p></div>
+</div></div><p>The above defines a component whose embedded id is "count"
(this id is derived from the name of the field and an element with that id must
be present in the corresponding template, otherwise an error is displayed (see
below)). The type of the component is org.example.app.components.Count. The
start and end parameters of the Count component are bound to literal values,
and the value parameter of the Count component is bound to the countValue
property of the Countdown component.</p><p>Technically, the start and end
parameters should be bound to properties, just like the value parameter.
However, certain literal values, such as the numeric literals in the example,
are accepted by the <code>prop:</code> binding prefix even though they are not
actually properties (this is largely as a convenience to the application
developer). We could also use the <code>literal:</code> prefix,
<code>"start=literal:5"</code>, which accomplishes largely the same
thing.</p><p>You may specify
additional parameters inside the component template, but parameters in the
component class take precedence.</p><p><strong>TODO: May want a more complex
check; what if user uses prop: in the template and there's a
conflict?</strong></p><p>You may override the default component id (as derived
from the field name) using the id() attribute of the Component
annotation.</p><p>If you define a component in the component class, and there
is no corresponding element in the template, Tapestry will log an error. In the
example above that would be the case if the template for the Countdown page
didn't contain an element with <code><t:count
t:id="count"></code>.</p><p></p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/component-mixins.html
==============================================================================
--- websites/production/tapestry/content/component-mixins.html (original)
+++ websites/production/tapestry/content/component-mixins.html Sun Feb 25
23:20:05 2018
@@ -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/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><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><p></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 Sun Feb 25
23:20:05 2018
@@ -77,7 +77,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Component
parameters</strong> are the primary means for a component instance and its
container to communicate with each other. Parameters are used to
<em>configure</em> component instances.</p><div class="aui-label"
style="float:right" title="Related Articles">
+ <div id="ConfluenceContent"><p><strong>Component
parameters</strong> are the primary means for a component instance and its
container to communicate with each other. Parameters are used to
<em>configure</em> component instances.</p><div class="aui-label"
style="float:right; margin: 1em" title="Related Articles">
@@ -180,11 +180,11 @@
</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.rbtoc1519597259054 {padding: 0px;}
-div.rbtoc1519597259054 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1519597259054 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1519600770048 {padding: 0px;}
+div.rbtoc1519600770048 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1519600770048 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style><div class="toc-macro rbtoc1519597259054">
+/*]]>*/</style><div class="toc-macro rbtoc1519600770048">
<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">
@@ -408,7 +408,7 @@ public class Title {
</div></div><div class="code panel pdl" style="border-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;"><t:ContainerComponent t:id="Container"
t:page="About" />
</pre>
-</div></div><p>There are still cases where you want to use the "inherit:"
binding prefix. For example, if you have several components that need to share
a parameter, then you must do it the Tapestry 5.0 way: a true parameter on the
outer component, and "inherit:" bindings on the embedded components. You can
follow a similar pattern to rename a parameter in the outer component.</p></div>
+</div></div><p>There are still cases where you want to use the "inherit:"
binding prefix. For example, if you have several components that need to share
a parameter, then you must do it the Tapestry 5.0 way: a true parameter on the
outer component, and "inherit:" bindings on the embedded components. You can
follow a similar pattern to rename a parameter in the outer
component.</p><p></p></div>
</div>
<div class="clearer"></div>
