[CONF] Apache Tapestry > BeanEditForm Guide
BeanEditForm Guide
Page edited by Kalle Korhonen
Changes (3)
...
{code:java}
{code}
...
Full Content
Using the BeanEditForm Component
Tapestry includes a powerful component capable of generating a complete create/edit user interface for a typical JavaBean, BeanEditForm.
BeanEditForm analyzes the the properties of the bean, locating just those properties that are readable and writable. It filters down to properties whose type is mapped to a known editor (this is described in more detail below).
The default ordering for properties is in the order in which the getter methods for the properties are defined. When a super-class defines editable properties, those are ordered before sub-class properties.
Supported Types
The default set of property types supported by BeanEditForm:
String: as a text field
Number: as a text field
Enum: as a drop-down list
Boolean: as a checkbox
Date: as a _javascript_ calendar
Calendar: as a _javascript_ calendar
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.
The list of supported property types is extensible (this is documented below).
Automatic Object Creation
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.
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.
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.
One option is to provide an event handler for the "prepare" or "prepareForSubmit" events to instantiate an instance to receive the submitted information.
For a class, Tapestry will select the public constructor with the most parameters. If this is not desirable (for example, if you get an exception), then place the @Inject annotation on the constructor Tapestry should use.
Implicit Object Binding
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.
Non-Visual Properties
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 @NonVisual annotation may be applied to the property (either the getter or the setter method).
Default Validation
Default validation for fields is primary determined by property type.
If desired, additional validation may be specified using the @Validate annotation. See Forms and Validation.
As of Tapestry 5.2, validation may also be specified via the containing component's property file, using a key in the form of propertyId-validate (eg: myfield-validate=required).
Property ordering
By default, the order in which properties are presented is as defined above (order of the getter method). This can be overridden using the ReorderProperties class annotation.
Default Label
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".
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.
Property Editor Overrides
You may override the editor for any particular property, using the a block parameter to the BeanEditForm component.
An editor normally consists of a Label component and some form of field component (such as TextField or TextArea).
For example, you may want to selectively use a PasswordField component:
"loginCredentials">
for="password"/>
"password" value="loginCredentials.password"/>
The other fields
[CONF] Apache Tapestry > BeanEditForm Guide
BeanEditForm Guide
Page edited by Christophe Cordenier
Comment:
Fix broken links
Changes (7)
...
One option is to provide an event handler for the "prepare" or "prepareForSubmit" events to instantiate an instance to receive the submitted information.
For a class, Tapestry will select the public constructor with the _most_ parameters. If this is not desirable (for example, if you get an exception), then place the [Inject|../../apidocs/org/apache/tapestry5/ioc/annotations/Inject.html] [Inject|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html] annotation on the constructor Tapestry should use.
h2. Implicit Object Binding
...
h2. Non-Visual Properties
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 [NonVisual|../apidocs/org/apache/tapestry5/beaneditor/NonVisual.html] [NonVisual|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/NonVisual.html] annotation may be applied to the property (either the getter or the setter method).
h2. Default Validation
...
Default validation for fields is primary determined by property type.
If desired, additional validation may be specified using the [Validate|../apidocs/org/apache/tapestry5/beaneditor/Validate.html] [Validate|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html] annotation.
h2. Property ordering
By default, the order in which properties are presented is as defined above (order of the getter method). This can be overridden using the [ReorderProperties|../apidocs/org/apache/tapestry5/beaneditor/ReorderProperties.html] [ReorderProperties|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/ReorderProperties.html] class annotation.
h2. Default Label
...
h1. Providing the BeanModel
The BeanEditForm component operates in terms of a [BeanModel|../apidocs/org/apache/tapestry5/beaneditor/BeanModel.html], [BeanModel|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/BeanModel.html], which describes the properties, their presentation order, labels and so forth.
Normally, the BeanEditForm automatically creates the BeanModel as needed, based on the type of object bound to its object parameter.
...
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".
Next, you must make contributions to the [DataTypeAnalyzer|../apidocs/org/apache/tapestry5/services/DataTypeAnalyzer.html] [DataTypeAnalyzer|http://tapestry.apache.org/current/apidocsapidocs/org/apache/tapestry5/services/DataTypeAnalyzer.html] or [DefaultDataTypeAnalyzer|../apidocs/org/apache/tapestry5/services/DefaultDataTypeAnalyzer.html] [DefaultDataTypeAnalyzer|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/internal/services/DefaultDataTypeAnalyzer.html] services to match properties to your new name.
DataTypeAnalyzer is a chain of command that can make 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.
...
{code}
Finally, we tell the BeanEditForm component about the editor via a contribution to the [BeanBlockSource|../apidocs/org/apache/tapestry5/services/BeanBlockSource.html] [BeanBlockSource|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/BeanBlockSource.html] service:
{code:java}
...
Full Content
Using the BeanEditForm Component
Tapestry includes a powerful component capable of generating a complete create/edit user interface for a typical JavaBean, BeanEditForm.
BeanEditForm analyzes the the properties of the bean, locating just those properties that are readable and writable. It filters down to properties whose type is mapped to a known editor (this is described in more detail below).
The default ordering for properties is in the order in which the getter methods for the properties are defined. When a super-class defines edittable properties, those are ordered before sub-class properties.
Supported Types
The default set of property types s
