001// Licensed under the Apache License, Version 2.0 (the "License"); 002// you may not use this file except in compliance with the License. 003// You may obtain a copy of the License at 004// 005// http://www.apache.org/licenses/LICENSE-2.0 006// 007// Unless required by applicable law or agreed to in writing, software 008// distributed under the License is distributed on an "AS IS" BASIS, 009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 010// See the License for the specific language governing permissions and 011// limitations under the License. 012 013package org.apache.tapestry5.services.ajax; 014 015import org.apache.tapestry5.ClientBodyElement; 016import org.apache.tapestry5.services.PartialMarkupRendererFilter; 017 018/** 019 * Manages the rendering of a partial page render as part of an Ajax response. This replaces 020 * the {@link org.apache.tapestry5.ajax.MultiZoneUpdate} introduced in Tapestry 5.1. Much of the API is used to 021 * queue behaviors that take effect when {@linkplain org.apache.tapestry5.services.PartialMarkupRenderer partial markup rendering takes place}. 022 * 023 * The implementation of this class provides {@link org.apache.tapestry5.services.PartialMarkupRendererFilter} to 024 * the {@link org.apache.tapestry5.internal.services.PageRenderQueue}. 025 * 026 * @since 5.3 027 */ 028public interface AjaxResponseRenderer 029{ 030 /** 031 * Queues the renderer to render markup for the client-side element with the provided id. 032 * 033 * @param clientId 034 * client id of zone to update with the content from the renderer 035 * @param renderer 036 * a {@link org.apache.tapestry5.Block}, {@link org.apache.tapestry5.runtime.Component} or other object that can be 037 * {@linkplain org.apache.tapestry5.ioc.services.TypeCoercer coerced} to {@link org.apache.tapestry5.runtime.RenderCommand}. 038 * @return the renderer, for a fluid interface 039 */ 040 AjaxResponseRenderer addRender(String clientId, Object renderer); 041 042 /** 043 * Queues an update to the zone, using the zone's body as the new content. 044 * 045 * @param zone 046 * the element that contains both a client id and a body (this is primarily used to represent a {@link org.apache.tapestry5.corelib.components.Zone} component). 047 * @return this renderer, for a fluid interface 048 */ 049 AjaxResponseRenderer addRender(ClientBodyElement zone); 050 051 /** 052 * Queues a callback to execute during the partial markup render. The callback is {@linkplain #addFilter(org.apache.tapestry5.services.PartialMarkupRendererFilter) added as a filter}; the 053 * callback is invoked before the rest of the rendering pipeline is invoked. 054 * 055 * @param callback 056 * object to be invoked 057 * @return this renderer, for a fluid interface 058 */ 059 AjaxResponseRenderer addCallback(JavaScriptCallback callback); 060 061 /** 062 * Queues a callback to execute during the partial markup render. . The callback is {@linkplain #addFilter(org.apache.tapestry5.services.PartialMarkupRendererFilter) added as a filter}; the 063 * callback is invoked before the rest of the rendering pipeline is invoked. 064 * 065 * @param callback 066 * object to be invoked 067 * @return this renderer, for a fluid interface 068 */ 069 AjaxResponseRenderer addCallback(Runnable callback); 070 071 /** 072 * Adds a rendering filter. Dynamically added filters are only in place during the handling of the current request, and come after any filters 073 * contributed to the {@link org.apache.tapestry5.services.PartialMarkupRenderer} service. 074 * 075 * @return this renderer, for a fluid interface 076 */ 077 AjaxResponseRenderer addFilter(PartialMarkupRendererFilter filter); 078 079 /** 080 * Queues a callback to execute during the partial markup render. The callback is {@linkplain #addFilter(org.apache.tapestry5.services.PartialMarkupRendererFilter) added as a filter}; 081 * the callback is invoked before the rest of the rendering pipeline is invoked. 082 * 083 * @param callback 084 * object o be invoked 085 * @return this renderer, for a fluid interface 086 */ 087 AjaxResponseRenderer addCallback(JSONCallback callback); 088 089 /** 090 * Initializes partial response rendering by identifying the page "responsible" for the response. This is mostly 091 * used for selecting the character set for the response. 092 * 093 * @param pageName 094 * identifies page to render 095 * @since 5.4 096 */ 097 void setupPartial(String pageName); 098}