org.apache.tapestry5.corelib.components.AjaxFormLoop.xdoc Maven / Gradle / Ivy
Show all versions of tapestry-core Show documentation
AjaxFormLoop renders an extensible, editable list of entities. It is intended for use with Master/Detail
relationships
(such as between an Order and a LineItem, in an e-commerce application). It allows new detail objects
to be added on the server side, with corresponding new user interface added to the client side.
Likewise,
existing server-side objects can be removed, and the corresponding user interface also removed.
AjaxFormLoop is dependent on the ability to extract an identifier (a primary key) from objects when
rendering, and
then retrieve the full object in a later request, such as when the form is submitted. This aligns well
with
an Object Relational Mapping layer such as Hibernate.
This example has an address book of Persons, each of which has multiple Phones. It is, in fact,
implemented in terms of Hibernate, using the tapestry-hibernate module.
Notice that the number field is nullable but required. This is because, when creating a new Phone
instance, we have no number to fill in.
However, a number is expected, and the user interface enforces that.
Here we're editing the direct properties of the Person object and adding a section below to allow
the phones for the person to be edited. The AjaxFormLoop looks much like a Loop component here,
except we must provide a PrimaryKeyEncoder object.
Each row provides a RemoveRowLink component that will remove that row (from the server side, then on
the client side).
The AjaxFormLoop provides a default row for adding additional data rows.
The onAddRowFromPhones() event handler method's job is to add a new Phone instance and
connect it to the Person. The @CommitAfter annotation ensures that changes are saved
to the database (including generating a primary key for the new Phone instance).
The flip side is onRemoveRowFromPhones(), which is the event handler when removing a row.
The event handler method is passed the Phone object to remove. Again, it is necessary
to commit the Hibernate transaction.
AjaxFormLoop has to determine how to store an id for each editable row (remember that the client
side can only really store strings, not full Java objects); in some cases you will
have to bind the encoder parameter to a ValueEncoder object that is specific for your data type.
However, this is not necessary for any Hibernate entities, as Tapestry automatically provides
th ValueEncoder.