|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.apache.tapestry5.corelib.components.Zone
@SupportsInformalParameters public class Zone
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 anActionLink
whose zone parameter is set, the
corresponding 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 Form
component may also trigger an update of a
client-side Zone.
The server side event handler can return a Block
or a component to render as the new
content on the client side. Often, re-rendering the Zone's body is useful. Multiple
client-side zones may be updated by returning a 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 QueryParameterConstants.ZONE_ID
parameter. An example use of this would
be 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.
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.
AjaxFormLoop
,
FormFragment
Component Parameters | ||||||
---|---|---|---|---|---|---|
Name | Description | Type | Flags | Default | Default Prefix | Since |
elementName | The element name to render for the zone; this defaults to the element actually used in the template, or "div" if no specific element was specified. | String | Required, Not Null | literal | ||
id | If bound, then the id attribute of the rendered element will be this exact value. If not bound, then a unique id is generated for the element. | String | literal | |||
show | Name of a function on the client-side Tapestry.ElementEffect object that is invoked to make the Zone's div visible before being updated. If not specified, then the basic "show" method is used. | String | symbol: | literal | ||
update | Name of a function on the client-side Tapestry.ElementEffect object that is invoked after the Zone's content has been updated. If not specified, then the basic "highlight" method is used, which performs a classic "yellow fade" to indicate to the user that and update has taken place. | String | symbol: | literal | ||
visible | If true (the default) then the zone will render normally. If false, then the "t-invisible" CSS class is added, which will make the zone initially invisible. | boolean | prop |
<t:zone t:id="counterZone" id="counterZone"> <p>You have clicked the link <strong>${clickCount}</strong> times.</p> </t:zone> <p> <t:actionlink t:id="clicker" zone="counterZone">increment the count</t:actionlink> </p>
It's pretty standard to bind the id parameter of a zone; the zone parameter of ActionLink and Form are theclient-side element id, not the component id. They are often, but not always, the same. Binding the id parameter ensures that a particular, fixed value is used.
Binding the zone parameter of the ActionLink, EventLink or Form (the "trigger" component) is what triggers the partial-render and update logic.
public class ZoneDemo { @Property @Persist private int clickCount; @InjectComponent private Zone counterZone; Object onActionFromClicker() { clickCount++; return counterZone.getBody(); } }
The event handler method for the clicker component increments the count, then returns the body of the zone. The body will be re-rendered (reflecting the new count), and sent to the client, which will update the zone in place, and trigger and animation (by default, a simple yellow fade) to draw the user's attention.
Not shown here, but fully valid, is to include JavaScript libraries and generate initialization JavaScript. This fully consistent with ordinary full-page renders.
Constructor Summary | |
---|---|
Zone()
|
Method Summary | |
---|---|
Block |
getBody()
Returns the zone's body (the content enclosed by its start and end tags). |
String |
getClientId()
The client id of the Zone; this is set when the Zone renders and will either be the value bound to the id parameter, or an allocated unique id. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public Zone()
Method Detail |
---|
public String getClientId()
getClientId
in interface ClientElement
public Block getBody()
getBody
in interface ClientBodyElement
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |