Ajax support is included in many built-in components and component mixins via the
async parameter (in Tapestry 5.4+) and the
zone parameter (for earlier versions). Here we use an EventLink component to trigger an Ajax update of another area of the page:
The corresponding Java code might look like this:
onUpdateTime method is just an ordinary Tapestry event handler, except that it uses an injected
AjaxResponseRenderer to tell Tapestry what zone to update when the link is clicked.
Since Tapestry 5.4.2, you can also easily invoke server-side event handlers using the
@PublishEvents annotation and the
Zones are Tapestry's approach to performing partial page updates. A Zone component renders as an HTML element, typically a <div>, and serves as a marker for where dynamically-updated content should be replaced. A zone is recognizable in the DOM because it will have the attribute
data-container-type=zone. The client-side support for Zones is keyed off of this attribute and value.
Starting in Tapestry 5.4 you can use any HTML element in your template as a zone marker, by passing its client-side id to the two-argument version of the addRender method.
A Zone updated can be triggered by an EventLink, ActionLink or Select component, or by a Form. All of these components support the
zone parameters. Clicking such a link will invoke an event handler method on the server as normal ... except that a partial page response is sent to the client, and the content of that response is used to update the Zone's <div> in place.
Event Handler Return Types
In a traditional request, the return value of an event handler method may used to determine which page will render a complete response, and a redirect may sent to the client to render the new page (as a new request).
In contrast, with a Zone update, the return value may used to render a partial response within the same request.
Starting in Tapestry 5.3, Ajax event handlers typically have a void return type and use AjaxResponseRenderer to indicate which zone to update. The AjaxResponseRender approach means that the
zone parameter's value (oridinarily indicating which zone to update) is no longer needed. Tapestry 5.4 introduced the
async="true" parameter to avoid having to redundantly indicate which zone to update.
If you only have one zone to update and don't want to use AjaxResponseRenderer, you can instead return a value from your event handler method. The simplest case is just to return the zone's own body:
The possible return values are:
- An injected Block or Component to render as the response. The response will be a JSON hash, with a "content" key whose value is the rendered markup. This is the basis for updates with the Zone component.
- The zone's own body (using Zone's getBody() method)
- null (to redraw the current page)
- A JSONObject or JSONArray, which will be sent as the response.
- A StreamResponse, which will be sent as the response.
- A Link, which will send a redirect to the client.
- A page name (as a String), or a page class, or a page instance, which will send a redirect to the indicated page.
See Page Navigation for full descriptions of the above.
This happens automatically when your event handler method has a void return type.
However, to support graceful degradation when your event handler method has a non-void return type, you should detect non-Ajax requests and return a traditional response, typically null to redraw the whole page. This is accomplished by injecting the Request object, and invoking the isXHR() method. This value will be true for Ajax requests, and false for traditional request.
Multiple Zone UpdatesAn event handler often needs to update multiple zones on the client side. To accomplish this, use an AjaxResponseRenderer, indicating the zones to update. You must know the client-side id for each zone to update (the best way for this is to lock down the zone's id using the id parameter of the Zone component).
AjaxResponseRenderer was introduced in Tapestry 5.3. For Tapestry 5.2 and earlier, return a MultiZoneUpdate object instead.
This example assumes that there are two zones, "userInput" and "helpPanel", somewhere in the rendered page, waiting to receive the updated content.
In this example, the Zone receives the update but does not provide any content. That's OK, the other client-side elements (
helpPanel) will be updated, and the zone's content left unchanged.
This demonstrates why it is necessary for the developer to specify a particular client-side id for Zone components; if they were dynamically allocated ids, as is typical in most other elements, it would be impossible for this code to know what client-side id was used for the Zone.
Zone Component Id vs. Zone Element Id
Like all Tapestry components, Zones have a component id, specified using the
t:id attribute. If you do not assign a component id, a unique id is assigned by Tapestry.
However, to coordinate things on the client side, it is necessary for components that wish to update the zone know the client-side element id. This is specified with the
id parameter of the Zone component. If the
id parameter is not bound, then a unique value (for the current page and render) is generated by Tapestry and this value is difficult to predict. (The actual value will be available as the
clientId property of the Zone component itself.)
Remember that the component id (
t:id) is used to inject the Zone component into the containing page or component. The client-side id (
id) is used on the client side to orchestrate requests and updates. You will often seen the following construct:
The Containing Zone (zone="^")
If the Form or Link is enclosed by the Zone itself, and you're using the
zone parameter instead of the
async parameter, then the
zone parameter may be set to the special value
(the carat). The zone is found – on the client side – by searching up form the form or link element for the first enclosing element that is a Zone. In this way, the client-side coordination can occur without having to know what the specific client-side id of the Zone is. Because of this, in some cases it is no longer necessary to specify the Zone's
An Update div within a Zone div (Tapestry 5.3 and earlier)
Deprecated : This feature is removed starting with Tapestry 5.4
In many situations, a Zone is a kind of "wrapper" or "container" for dynamic content; one that provides a look and feel ... a bit of wrapping markup to create a border. In that situation, the Zone <div> may contain an update <div>.
An Update <div> is specifically a <div> element marked with the CSS class "t-zone-update", inside the Zone's <div>.
If an Update div exists within a Zone div, then when Tapestry updates a zone only the update <div>'s content will be changed, rather than the entire Zone <div>.
The show and update functions (see Zone Functions, below) apply to the Zone <div>, not just the update <div>.
Zone Effect Functions (Tapestry 5.3 and earlier)
Deprecated: This feature refers to client-side logic only present in Tapestry 5.3 or earlier. For 5.4, there are client-side events that are triggered before and after changes to the Zone; listeners on those events can trigger whatever animations they like.
A Zone may be initially visible or invisible. When a Zone is updated, it is made visible if not currently so. This is accomplished via a function on the Tapestry.ElementEffect client-side object. By default, the show() function is used for this purpose. If you want Tapestry to call a different Tapestry.ElementEffect function when updates occur, specify its name with the zone's show parameter.
If a Zone is already visible, then a different effect function is used to highlight the change. By default, the highlight() function is called, which performs a yellow fade to highlight that the content of the Zone has changed. Alternatively, you can specify a different effect function with the Zone's update parameter:
(the default) highlight changes to an already-visible zone
make the zone visible if it isn't already visible
scroll the content down
slide the content back up (opposite of slidedown)
fade the content out (opposite of show)
To have Tapestry update a zone without the usual yellow highlight effect, just specify "show" for the update parameter:
Unlike many other situations, Tapestry relies on you to specify useful and unique ids to Zone components, then reference those ids inside EventLink (or ActionLink, or Form) components. Using Zone components inside any kind of loop may cause additional problems, as Tapestry will uniqueify the client id you specify (appending an index number).
If you create a component that contains a zone, and you use that component in a loop, you'll likely need to set the client-side id like this:
See this JumpStart Example for details.
Zones may only be used inside the body of a page, not the head.
For examples of extending a Form with a Zone and updating multiple zones at once, see the Ajax Components FAQ.
Autocomplete MixinThe Autocomplete mixin exists to allow a text field to query the server for completions for a partially entered phrase. It is often used in situations where the field exists to select a single value from a large set, too large to successfully download to the client as a drop down list; for example, when the number of values to select from is numbered in the thousands.
Autocomplete can be added to an existing text field:
The mixin can be configured in a number of ways, see the component reference.
You must write an event handler to provide these completions. The name of the event is "providecompletions". The context is the partial input value, and the return value will be converted into the selections for the user.
This presumes that
findByPartialAccountName() will sort the values, otherwise you will probably want to sort them. The Autocomplete mixin does not do any sorting.
You can return an object array, a list, even a single object. You may return objects instead of strings ... and
toString() will be used to convert them into client-side strings.
t5/core/ajax function, but with slightly different parameters.
t5/core/ajax function has two parameters:
options. Prior to Tapestry 5.4.2, the first one was difficult to get when doing AJAX requests to event handler methods. You needed to inject
ComponentResources in your component class, call
componentResources.createEventLink() for each event handler method, then pass all this information back to the browser through one of the
All event data is stored in
data-componenent-events attributes. For page classes, the attribute is added to the
<body> element. For components, it's added to the first element rendered by the component. Given an HTML element, the search is performed in the following order until information for the given event is first found:
- The element itself
- The element's previous siblings, closest first (bottom-up)
- The element's parents
- The page's
Here's one example:
onAction() are ordinary event handlers, with nothing specific besides the
The template also has nothing special. When rendered, the component's events information is placed in the outer
We want to update the text of
<p id="result"> with the value of the
If you're trying to invoke a page class event handler, you can change line 5 above to
element: null. You do need to explicitly set the
element property, otherwise the
ajax function will treat the first parameter,
url, as an URL and not as an event name.