| ------ |
| Ajax/DHTML Guide - ResponseBuilder |
| ------ |
| Jesse Kuhnert |
| ------ |
| 28 July 2006 |
| ------ |
| |
| Overview |
| |
| One of the largest changes made to Tapestry 4.1 was the rendering cycle. Traditionally, responses were made |
| using one basic {{{../apidocs/org/apache/tapestry/IMarkupWriter.html}IMarkupWriter}} instance |
| to capture and render output back to the browser. <(this isn't entirely true, NullWriter instances are used |
| in some instances, like rewinding {{{../components/form/form.html}Form}} components)> |
| |
| The new method looks basically the same on the surface, but rendering output is now managed by specific |
| {{{../apidocs/org/apache/tapestry/services/ResponseBuilder.html}ResponseBuilder}} instances, |
| depending on the type of request. These classes are responsible for calling |
| {{{../apidocs/org/apache/tapestry/AbstractComponent.html#render(org.apache.tapestry.IMarkupWriter,%20org.apache.tapestry.IRequestCycle)}AbstractComponent.html#render(IMarkupWriter writer, IRequestCycle cycle}} |
| for all component renders. They are also responsible for managing javascript output from script templates. |
| |
| You can always get a reference to the correct {{{../apidocs/org/apache/tapestry/services/ResponseBuilder.html}ResponseBuilder}} for |
| the current request by calling <<<cycle.getResponseBuilder()>>> on your {{{../apidocs/org/apache/tapestry/IRequestCycle.html}IRequestCycle}} |
| instance. |
| |
| <<See also:>> {{{../apidocs/org/apache/tapestry/services/ResponseBuilder.html}ResponseBuilder}}, |
| {{{../apidocs/org/apache/tapestry/services/impl/DojoAjaxResponseBuilder.html}DojoAjaxResponseBuilder}}, |
| {{{../apidocs/org/apache/tapestry/services/impl/JSONResponseBuilder.html}JSONResponseBuilder}} |
| |
| * Using ResponseBuilder to dynamically update content |
| |
| Based on the type of request made, one of the three available {{{../apidocs/org/apache/tapestry/services/ResponseBuilder.html}ResponseBuilder}}s |
| will be chosen to handle it. In the case of a request made using the {{{EventListener.html}EventListener}} annotation, the |
| builder used will <(not in all cases, if you specify async=false on your annotation the request will be a |
| normal http post)> be {{{../apidocs/org/apache/tapestry/services/impl/DojoAjaxResponseBuilder.html}DojoAjaxResponseBuilder}}. |
| |
| Building on the example started in the {{{EventListener.html}EventListener}} overview, this is how you |
| would dynamically update the contents of a component: |
| |
| +----------------------------------------------------------------------- |
| .... |
| |
| @EventListener(targets = "projectChoose", events = "onValueChanged") |
| public void projectSelected(IRequestCycle cycle) |
| { |
| cycle.getResponseBuilder().updateComponent("myComponentId"); |
| } |
| |
| .... |
| +----------------------------------------------------------------------- |
| |
| The string value passed in to <<<updateComponent(String componentId)>>> is the component id of the component |
| which you would like to update. |
| |
| Tapestry will correctly manage and render all javascript/form state/etc needed, depending on the component |
| type you are requesting an update on. |
| |
| |