A Zone is portion of the output page designed for easy dynamic updating via Ajax or other client-side effects. A Zone renders out as a <div> element (or whatever is specified in the template) and may have content initially, or may only get its content as a result of client side activity.
Often, Zones are initially invisible, in which case the visible parameter may be set to false (it defaults to true).
When a user clicks an {@link org.apache.tapestry5.corelib.components.ActionLink} whose zone parameter is set, thecorresponding client-side Tapestry.ZoneManager object is located. It will update the content of the Zone's <div> and then invoke either a show method (if the div is not visible) or an update method (if the div is visible). The show and update parameters are the
names of functions attached to the Tapestry.ElementEffect object. Likewise, a {@link org.apache.tapestry5.corelib.components.Form} component may also trigger an update of aclient-side Zone.
The server side event handler can return a {@link org.apache.tapestry5.Block} or a component to render as the newcontent on the client side. Often, re-rendering the Zone's {@linkplain #getBody() body} is useful. Multipleclient-side zones may be updated by returning a {@link org.apache.tapestry5.ajax.MultiZoneUpdate}.
Renders informal parameters, adding CSS class "t-zone" and possibly, "t-invisible".
You will often want to specify the id parameter of the Zone, in addition to it's Tapestry component id; this "locks down" the client-side id, so the same value is used even in later partial renders of the page (essential if the Zone is nested inside another Zone). When you specify the client-side id, it is used exactly as provided (meaning that you are responsible for ensuring that there will not be an id conflict even in the face of multiple partial renders of the page). Failure to provide an explicit id results in a new, and non-predictable, id being generated for each partial render, which will often result in client-side failures to locate the element to update when the Zone is triggered.
In some cases, you may want to know (on the server side) the client id of the zone that was updated; this is passed as part of the Ajax request, as the {@link QueryParameterConstants#ZONE_ID} parameter. An example use of this wouldbe to provide new content into a Zone that updates the same Zone, when the Zone's client-side id is dynamically allocated (rather than statically defined). In most cases, however, the programmer is responsible for assigning a specific client-side id, via the id parameter.
A Zone starts and stops a {@link Heartbeat} when it renders (both normally, and when re-rendering).
After the client-side content is updated, a client-side event is fired on the zone's element. The constant Tapestry.ZONE_UPDATED_EVENT can be used to listen to the event.
@tapestrydoc
@see AjaxFormLoop
@see FormFragment