.. +------------------------------------------------------------------------------------------------------------- The corresponding java page class: +------------------------------------------------------------------------------------------------------------- .. public abstract BasicAjax extends BasePage { public abstract void setTime(Date time); public void setTime() { setTime(new java.util.Date()); } } +------------------------------------------------------------------------------------------------------------- That's it! Building and running this small example should be all you need to start using the very basic AJAX functionality provided by Tapestry. ** updateComponents == IComponent.getClientId() There are a few subtle things happening here that may not be apparent at first glance. One of the more important changes in Tapestry 4.1.x was the addition of the {{{../apidocs/org/apache/tapestry/IComponent.html#getClientId()}IComponent.getClientId()}} method to all component classes. When dealing with client side javascript functionality the unique client side element id of the html elements your components generate becomes very important. What this method gives you is the unique element id attribute that will be written for any given component depending on the context in which you call it. If you are in a {{{../components/general/for.html}For}} loop then the <<>> will automatically be incremented for each loop and always represent the unique value of the component. The same semantics work whether in {{{../components/form/form.html}Forms}} / {{{../components/general/for.html}For}} or any other nested type of structure. This has been one of key changes in the API that has made the AJAX functionality provided easier to work with. In our example the <<>> parameter given made use of the new smart auto binding functionality added to the framework recently, but you could write the equivalent parameter using an ognl expression as well: +------------------------------------------------------------------------------------------------------------- Refresh time +------------------------------------------------------------------------------------------------------------- Things can get a lot uglier once you start trying to update multiple components: +------------------------------------------------------------------------------------------------------------- Refresh time +------------------------------------------------------------------------------------------------------------- The much easier simple string list <<>> is not only shorter / easier to understand but also more efficient and robust in many different circumstances. For instance, the auto binding functionality would be able to detect that you were trying to update a component contained within one of your own custom components as well as a component on the page containing your component and wire up and find all the correct <<>> values for you automatically. The thing to walk away with here is that in 98% of the cases you run in to this style of <<>> syntax is the way to go: +------------------------------------------------------------------------------------------------------------- Refresh time +------------------------------------------------------------------------------------------------------------- ** How clientId values are generated The actual value that is output by a component is determined by a number of rules depending on the context and type of component involved. Of course, no id will be generated at all if your custom components don't call the new {{{../apidocs/org/apache/tapestry/AbstractComponent.html#renderIdAttribute(org.apache.tapestry.IMarkupWriter,%20org.apache.tapestry.IRequestCycle)}AbstractComponent.renderIdAttribute(IMarkupWriter, IRequestCycle)}} method provided in the base <<>> superclass that most components derive from. When that method is called the rules for determining what value to render out in to the generated html element are evaluated in this order: [[1]] <> - If the definition of the component being rendered had an informal <<>> parameter specified that will take higher precendence than anything else. It may eventually end up being output as <<>> if your component is being rendered in a loop but it will still use the id as the basis for its client side id values. +----------------------------------------------

Content

+---------------------------------------------- [[1]] <> - If no informal id parameter is bound then the next candidate used to seed the clientIds is the value returned from <<>>. This will be the id specified in your <<>> file or the id assigned in your html snippet as in: +----------------------------------------------

Content

or .page file: +---------------------------------------------- [[1]] <

> - If the component in question implements {{{../apidocs/org/apache/tapestry/form/IFormComponent.html}IFormComponent}} then the same semantics as above apply with the caveat that the inner workings of client id generation work slightly differently here as they are synchronized back with the normal {{{../components/form/form.html}Form}} input name/clientId semantics that Tapestry has always had. [] The previously mentioned <<>> method is the crucual piece that anyone writing custom components will need to make sure to call if you plan on overriding <<>>. One very simplistic example of calling this new base method would be: +------------------------------------------------------------------------------------------------------------- .. public abstract MyCustomComponent extends AbstractComponent { public void renderComponent(IMarkupWriter writer, IRequestCycle cycle) { writer.begin("div"); writer.renderIdAttribute(writer, cycle); <----------------------------------* writer.renderInformalParamters(writer, cycle); writer.print("Custom text content.."); writer.end(); } } +------------------------------------------------------------------------------------------------------------- ** Common Mistake: Can't update a component not already rendered on the page One of more common questions on the users mailing list inevitably involves this innocent looking block of code modified from our previous examples: +------------------------------------------------------------------------------------------------------------- ..

Basic javascript inclusion sample.

Refresh time.

.. +------------------------------------------------------------------------------------------------------------- The problem with this code is that the component being requested to update - <<>> - doesn't actually exist as a valid client side html element when you click on the <<>> link. The initial block of html generated from this template will really look like: +------------------------------------------------------------------------------------------------------------- ..

Basic javascript inclusion sample.

Refresh time.

.. +------------------------------------------------------------------------------------------------------------- The crucial piece missing in the above sample snippet is an html block for our <<>> component. It wasn't rendered initially because the time value was null. The semantics of how the client side XHR io logic works basically comes down to: * <> - Initiate client side XHR request which will eventually return a block of html for our <<>> component of: +-------------------------------------------------------------------------------------------------------------

10:49 am 1/2/2007

+------------------------------------------------------------------------------------------------------------- * <> - This is the part that breaks down. The very basic minimal example of how it is done would look something like: +------------------------------------------------------------------------------------------------------------- .. var responseNode = getResponseHtml(); // this is the time div block from the last example var updateNode = document.getElementById("time"); updateNode.innerHTML = getContentAsString(responseNode); .. +------------------------------------------------------------------------------------------------------------- The resulting client side error that is logged should be something along the lines of <<<"couldn't find a matching client side dom node to update with id of 'time'">>>. The solution to get around this varies for each situation but the most common / easiest method is usually done by just wrapping the block that conditionally renders with a simple {{{../components/general/any.html}Any}} component: +------------------------------------------------------------------------------------------------------------- ..

Basic javascript inclusion sample.

Refresh time.

.. +------------------------------------------------------------------------------------------------------------- Now the example specifies a <<>> definition for which components to update and has the {{{../components/general/any.html}Any}} updated instead of <<>> directly as it exist on the client side prior to our requesting an update on it and shouldn't interfere overly much with whatever CSS/design we have setup.