Form component provides easy way of creating and managing sets fields.
Form is a container for fields implementing
com.itmill.toolkit.ui.Field
interface. It
provides support for any layouts and provides buffering interface for easy
connection of commit- and discard buttons. All the form fields can be
customized by adding validators, setting captions and icons, setting
immediateness, etc. Also direct mechanism for replacing existing fields with
selections is given.
Form provides customizable editor for classes implementing
com.itmill.toolkit.data.Item
interface. Also the form itself
implements this interface for easier connectivity to other items.
To use the form as editor for an item, just connect the item to
form with
setItemDataSource(com.itmill.toolkit.data.Item)
. If only a part of the
item needs to be edited,
setItemDataSource(com.itmill.toolkit.data.Item, java.util.Collection)
can be used instead. After the item has been connected to the form,
the automatically created fields can be customized and new fields can
be added. If you need to connect a class that does not implement
com.itmill.toolkit.data.Item
interface, most properties of any
class following bean pattern, can be accessed trough
com.itmill.toolkit.data.util.BeanItem
.
3.0
Inheritance Path. java.lang.Object-> com.itmill.toolkit.ui.AbstractComponent -> com.itmill.toolkit.ui.AbstractField -> com.itmill.toolkit.ui.Form
Parameters
formLayout
The layout of the form.
Contruct a new form with default layout.
By default the form uses
OrderedLayout
with
form
-style.
Parameters
formLayout
The layout of the form.
fieldFactory
FieldFactory of the form
Contruct a new form with given layout and FieldFactory.
Parameters
propertyId
Property id the the field.
field
New field added to the form.
Add field to form.
The property id must not be already used in the form.
This field is added to the form layout in the default position
(the position used by
addComponent(com.itmill.toolkit.ui.Component)
method.
In the special case that the underlying layout is a custom layout,
string representation of the property id is used instead of the
default location.
Add a new property to form and create corresponding field.
Parameters
validator
the new validator
Adds a new validator for this object. The validator's
validate(java.lang.Object)
method is activated every time the
object's value needs to be verified, that is, when the
isValid()
method is called. This usually happens when the
object's value changes.
attach()
Exceptions
SourceException
if the operation fails because of an exception is thrown by the data source. The cause is included in the exception.
Updates all changes since the previous commit to the data source.
The value stored in the object will always be updated into the data
source when
commit
is called.
detach()
Exceptions
SourceException
if the operation fails because of an exception is thrown by the data source. The cause is included in the exception.
Discards all changes since last commit. The object updates its value from the data source.
Parameters
FieldFactory Factory used to create the fields
Get the field factory of the form.
getItemProperty(java.lang.Object)
The property identified by the property id.
The property data source of the field specified with property id is returned. If there is a (with specified property id) having no data source, the field is returned instead of the data source.
Parameters
unmodifiable collection containing IDs of the Properties stored the Item
Gets the collection of IDs of all Properties stored in the Item.
Parameters
Layout of the form.
Get the layout of the form.
By default form uses
OrderedLayout
with
form
-style.
com.itmill.toolkit.ui.AbstractField
Parameters
collection of validators or
null
getValidators()
List all validators currently registered for the object. If no
validators are registered, returns
null
.
isInvalidAllowed()
Does the validabtable object accept invalid values. The default is true.
Parameters
true
if the value in the object has been
modified since the last data source update,
false
if
not.
Tests if the value stored in the object has been modified since it was last updated from the data source.
Parameters
true
if the object is in read-through mode,
false
if it's not.
Tests if the object is in read-through mode. If the object is in read-through mode, retrieving its value will result in the value being first updated from the data source to the object. The only exception to this rule is that when the object is not in write-through mode and it's buffer contains a modified value, the value retrieved from the object will be the locally modified value in the buffer which may differ from the value in the data source.
Parameters
true
if the registered validators concur that
the value is valid,
false
otherwise
isValid()
Tests the current value of the object against all registered
validators. The registered validators are iterated and for each the
validate(java.lang.Object)
method is called. If any validator
throws the
com.itmill.toolkit.data.Validator.InvalidValueException
this method
returns
false
.
Parameters
true
if the object is in write-through mode,
false
if it's not.
Tests if the object is in write-through mode. If the object is in
write-through mode, all modifications to it will result in
commit
being called after the modification.
Parameters
Success of the operation. Removal of all fields succeeded if (and only if) the return value is true.
Removes all properties and fields from the form.
removeItemProperty(java.lang.Object)
Removes the property and corresponding field from the form.
Parameters
validator
the validator to remove
Removes a previously registered validator from the object. The
specified validator is removed from the object and its
validate
method is no longer called in
isValid()
.
Parameters
The select property generated
Set a form field to be selectable from static list of changes.
The list values and descriptions are given as array. The value-array must contain the current value of the field and the lengths of the arrays must match. Null values are not supported.
Parameters
fieldFactory
New factory used to create the fields
Set the field factory of Form. FieldFacroty is used to create fields for form properties. By default the form uses BaseFieldFactory to create Field instances.
setInvalidAllowed(boolean)
Should the validabtable object accept invalid values. Supporting this configuration possibility is optional. By default invalid values are alloved.
Set the item datasource for the form.
Setting item datasource clears any fields, the form might contain and adds all the properties as fields to the form.
Set the item datasource for the form, but limit the form contents to specified properties of the item.
Setting item datasource clears any fields, the form might contain and adds the specified the properties as fields to the form, in the specified order.
Parameters
layout
Layout of the form.
Set the layout of the form.
By default form uses
OrderedLayout
with
form
-style.
setReadOnly(boolean)
Parameters
readThrough
Boolean value to indicate if the object should be in read-through mode after the call.
Exceptions
SourceException
if the operation fails because of an exception is thrown by the data source. The cause is included in the exception.
Sets the object's read-through mode to the specified status. When switching read-through mode on, the object's value is updated from the data source.
setTabIndex(int)
Parameters
visibleProperties
The visibleProperties to set
Sets the visibleProperties.
Parameters
writeThrough
Boolean value to indicate if the object should be in write-through mode after the call.
Sets the object's write-through mode to the specified status. When
switching the write-through mode on, the
commit()
operation will be performed.
Exceptions
Validator.InvalidValueException
if the value is not valid
validate()
Checks the validity of the validatable. If the validatable is valid
this method should do nothing, and if it's not valid, it should throw
Validator.InvalidValueException