Modified: websites/production/tapestry/content/beaneditform-guide.html
==============================================================================
--- websites/production/tapestry/content/beaneditform-guide.html (original)
+++ websites/production/tapestry/content/beaneditform-guide.html Tue Sep 26
19:20:27 2017
@@ -27,16 +27,6 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
- <link href='/resources/highlighter/styles/shCoreCXF.css'
rel='stylesheet' type='text/css' />
- <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet'
type='text/css' />
- <script src='/resources/highlighter/scripts/shCore.js'
type='text/javascript'></script>
- <script src='/resources/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
- <script src='/resources/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
- <script src='/resources/highlighter/scripts/shBrushPlain.js'
type='text/javascript'></script>
- <script>
- SyntaxHighlighter.defaults['toolbar'] = false;
- SyntaxHighlighter.all();
- </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -77,20 +67,18 @@
</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><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>Res
olving 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 th
e 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 ma
tches 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 an
d 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> (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">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <t:beaneditform object="loginCredentials">
+ <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><plain-text-body>{float:right|background=#eee|padding=0 1em}
+ *JumpStart Demos:*
+ [Edit (Using
BeanEditForm)|http://jumpstart.doublenegative.com.au/jumpstart/examples/input/edit1/1]
+ [Create (Using
BeanEditForm)|http://jumpstart.doublenegative.com.au/jumpstart/examples/input/create1]
+ [More Control Edit (Using
BeanEditor)|http://jumpstart.doublenegative.com.au/jumpstart/examples/input/morecontroledit1/1]
+{float}</plain-text-body><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 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 ha
ndler 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 pr
operty 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
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>prop
ertyId-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 ta
kes 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><parameter
ac:name="">java</parameter><plain-text-body> <t:beaneditform
object="loginCredentials">
<p:password>
<t:label for="password"/>
<t:passwordfield t:id="password"
value="loginCredentials.password"/>
</p:password>
</t:beaneditform>
-</pre>
-</div></div><p>The other fields will render normally (using the built-in
editors).</p><h1 id="BeanEditFormGuide-CustomizingtheBeanModel">Customizing the
BeanModel</h1><p>You may want to customize the BeanModel further, to remove
from the form properties that should not be editable by the user, and to change
the order in which properties are presented within the form.</p><p>The
BeanEditForm component has several parameters for this purpose:</p><ul><li>add:
A comma separated list of property names to add to the model.</li><li>include:
A comma separated list of property names to keep with the model (others are
excluded).</li><li>exclude: A comma separated list of property names to exclude
from the model.</li><li>reorder: A comma separated list of property names
indicating the desired order.<br clear="none"> If a model has more properties
that are listed in the reorder parameter, then the additional properties will
be ordered at the end of the form.</li></ul><p>Note that these parameter
s <em>modify</em> the BeanModel. If you supply your own BeanModel (via the
model parameter) you should not use the add, include, exclude or reorder
parameters.</p><p>Added properties must not conflict with normal properties.
Cells for added properties will render blank unless an override is
provided.</p><h1 id="BeanEditFormGuide-ProvidingtheBeanModel">Providing the
BeanModel</h1><p>The BeanEditForm component operates in terms of a <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/BeanModel.html";>BeanModel</a>,
which describes the properties, their presentation order, labels and so
forth.</p><p>Normally, the BeanEditForm automatically creates the BeanModel as
needed, based on the type of object bound to its object
parameter.</p><p>Alternately, the BeanModel can be supplied as the model
parameter. This can be useful in situations where the exclude and reorder
parameters are insufficient. For example, if the the type of the prope
rty being edited is an interface type, it may be useful to provide an explicit
BeanModel around an underlying implementation class.</p><p>The model can be
created when the page is first instantiated:</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 MyPage
+</plain-text-body><p>The other fields will render normally (using the built-in
editors).</p><h1 id="BeanEditFormGuide-CustomizingtheBeanModel">Customizing the
BeanModel</h1><p>You may want to customize the BeanModel further, to remove
from the form properties that should not be editable by the user, and to change
the order in which properties are presented within the form.</p><p>The
BeanEditForm component has several parameters for this purpose:</p><ul><li>add:
A comma separated list of property names to add to the model.</li><li>include:
A comma separated list of property names to keep with the model (others are
excluded).</li><li>exclude: A comma separated list of property names to exclude
from the model.</li><li>reorder: A comma separated list of property names
indicating the desired order.<br clear="none"> If a model has more properties
that are listed in the reorder parameter, then the additional properties will
be ordered at the end of the form.</li></ul><p>Note that these par
ameters <em>modify</em> the BeanModel. If you supply your own BeanModel (via
the model parameter) you should not use the add, include, exclude or reorder
parameters.</p><p>Added properties must not conflict with normal properties.
Cells for added properties will render blank unless an override is
provided.</p><h1 id="BeanEditFormGuide-ProvidingtheBeanModel">Providing the
BeanModel</h1><p>The BeanEditForm component operates in terms of a <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/BeanModel.html";>BeanModel</a>,
which describes the properties, their presentation order, labels and so
forth.</p><p>Normally, the BeanEditForm automatically creates the BeanModel as
needed, based on the type of object bound to its object
parameter.</p><p>Alternately, the BeanModel can be supplied as the model
parameter. This can be useful in situations where the exclude and reorder
parameters are insufficient. For example, if the the type of the
property being edited is an interface type, it may be useful to provide an
explicit BeanModel around an underlying implementation class.</p><p>The model
can be created when the page is first instantiated:</p><parameter
ac:name="">java</parameter><plain-text-body>public class MyPage
{
@Inject
private BeanModelSource beanModelSource;
@@ -112,18 +100,12 @@
}
}
-</pre>
-</div></div><p>And, in the component template, the built model can be passed
to the BeanEditForm component explicitly:</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="bean" model="model"/>
-</pre>
-</div></div><h1 id="BeanEditFormGuide-AddingNewPropertyEditors">Adding New
Property Editors</h1><p>Adding a new property editor is a three step
process.</p><p>First, decide on a logical name for the data type. For example,
you may decide that the BigDecimal type will represent currency in your
application, so name the data type "currency".</p><p>Next, you must make
contributions to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocsapidocs/org/apache/tapestry5/services/DataTypeAnalyzer.html";>DataTypeAnalyzer</a>
or <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/internal/services/DefaultDataTypeAnalyzer.html";>DefaultDataTypeAnalyzer</a>
services to match properties to your new name.</p><p>DataTypeAnalyzer is a
chain of command that can match properties to data types based on property type
or annotations on the property. In general, DefaultDataTypeAnalyzer is used, as
that only needs to consider property type.
DefaultDataTypeAnalyzer matches property types to data types, based on a
search up the inheritance path.</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 static void
contributeDefaultDataTypeAnalyzer(MappedConfiguration<Class, String>
configuration)
+</plain-text-body><p>And, in the component template, the built model can be
passed to the BeanEditForm component explicitly:</p><parameter
ac:name="">java</parameter><plain-text-body> <t:beaneditform object="bean"
model="model"/>
+</plain-text-body><h1 id="BeanEditFormGuide-AddingNewPropertyEditors">Adding
New Property Editors</h1><p>Adding a new property editor is a three step
process.</p><p>First, decide on a logical name for the data type. For example,
you may decide that the BigDecimal type will represent currency in your
application, so name the data type "currency".</p><p>Next, you must make
contributions to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocsapidocs/org/apache/tapestry5/services/DataTypeAnalyzer.html";>DataTypeAnalyzer</a>
or <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/internal/services/DefaultDataTypeAnalyzer.html";>DefaultDataTypeAnalyzer</a>
services to match properties to your new name.</p><p>DataTypeAnalyzer is a
chain of command that can match properties to data types based on property type
or annotations on the property. In general, DefaultDataTypeAnalyzer is used, as
that only needs to consider property
type. DefaultDataTypeAnalyzer matches property types to data types, based on
a search up the inheritance path.</p><parameter
ac:name="">java</parameter><plain-text-body>public static void
contributeDefaultDataTypeAnalyzer(MappedConfiguration<Class, String>
configuration)
{
configuration.add(BigDecimal.class, "currency");
}
-</pre>
-</div></div><p>You must provide an editor for the "currency" data type. An
editor is a block of a page of the application; this page is not normally
rendered itself, but acts as a container for one or more blocks.</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 AppPropertyEditBlocks
+</plain-text-body><p>You must provide an editor for the "currency" data type.
An editor is a block of a page of the application; this page is not normally
rendered itself, but acts as a container for one or more blocks.</p><parameter
ac:name="">java</parameter><plain-text-body>public class AppPropertyEditBlocks
{
@Property
@Environmental
@@ -148,20 +130,15 @@
return context.getTranslator(current);
}
}
-</pre>
-</div></div><p>The hard part is the translator; this is a piece of code that
understands how to format and how to parse a currency value. It must be wrapped
to create a FieldTranslator.</p><p>The editor is a block inside the component
template:</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:block id="currency">
+</plain-text-body><p>The hard part is the translator; this is a piece of code
that understands how to format and how to parse a currency value. It must be
wrapped to create a FieldTranslator.</p><p>The editor is a block inside the
component template:</p><parameter ac:name="">java</parameter><plain-text-body>
<t:block id="currency">
<t:label for="currency"/>
<t:textfield t:id="currency" size="10"/>
</t:block>
-</pre>
-</div></div><p>Finally, we tell the BeanEditForm component about the editor
via a contribution to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/BeanBlockSource.html";>BeanBlockSource</a>
service:</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 static void
contributeBeanBlockSource(Configuration<BeanBlockContribution>
configuration)
+</plain-text-body><p>Finally, we tell the BeanEditForm component about the
editor via a contribution to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/BeanBlockSource.html";>BeanBlockSource</a>
service:</p><parameter ac:name="">java</parameter><plain-text-body>public
static void
contributeBeanBlockSource(Configuration<BeanBlockContribution>
configuration)
{
configuration.add(new BeanBlockContribution("currency",
"AppPropertyEditBlocks", "currency", true));
}
-</pre>
-</div></div><p>Now, when the BeanEditForm sees a property of type BigDecimal,
it will map that to datatype "currency" and from there to the currency block of
the AppPropertyEditBlocks page of the application.</p></div>
+</plain-text-body><p>Now, when the BeanEditForm sees a property of type
BigDecimal, it will map that to datatype "currency" and from there to the
currency block of the AppPropertyEditBlocks page of the application.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
