001// Copyright 2011 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007// http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5.services.ajax;
016
017import org.apache.tapestry5.ClientBodyElement;
018import org.apache.tapestry5.services.PartialMarkupRendererFilter;
019
020/**
021 * Manages the rendering of a partial page render as part of an Ajax response. This replaces
022 * the {@link org.apache.tapestry5.ajax.MultiZoneUpdate} introduced in Tapestry 5.1. Much of the API is used to
023 * queue behaviors that take effect when {@linkplain org.apache.tapestry5.services.PartialMarkupRenderer partial markup rendering takes place}.
024 * <p/>
025 * The implementation of this class provides {@link org.apache.tapestry5.services.PartialMarkupRendererFilter} to
026 * the {@link org.apache.tapestry5.internal.services.PageRenderQueue}.
027 *
028 * @since 5.3
029 */
030public interface AjaxResponseRenderer
031{
032    /**
033     * Queues the renderer to render markup for the client-side element with the provided id.
034     *
035     * @param clientId client id of zone to update with the content from the renderer
036     * @param renderer 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 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).
046     * @return this renderer, for a fluid interface
047     */
048    AjaxResponseRenderer addRender(ClientBodyElement zone);
049
050    /**
051     * 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
052     * callback is invoked before the rest of the rendering pipeline is invoked.
053     *
054     * @param callback object to be invoked
055     * @return this renderer, for a fluid interface
056     */
057    AjaxResponseRenderer addCallback(JavaScriptCallback callback);
058
059    /**
060     * 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
061     * callback is invoked before the rest of the rendering pipeline is invoked.
062     *
063     * @param callback object to be invoked
064     * @return this renderer, for a fluid interface
065     */
066    AjaxResponseRenderer addCallback(Runnable callback);
067
068    /**
069     * Adds a rendering filter.  Dynamically added filters are only in place during the handling of the current request, and come after any filters
070     * contributed to the {@link org.apache.tapestry5.services.PartialMarkupRenderer} service.
071     *
072     * @return this renderer, for a fluid interface
073     */
074    AjaxResponseRenderer addFilter(PartialMarkupRendererFilter filter);
075
076    /**
077     * Queues a callback to execute during the partial markup render. The callback is {@linkplain #addFilter(org.apache.tapestry5.services.PartialMarkupRendererFilter) added as a filter};
078     * the callback is invoked before the rest of the rendering pipeline is invoked.
079     *
080     * @param callback object o be invoked
081     * @return this renderer, for a fluid interface
082     */
083    AjaxResponseRenderer addCallback(JSONCallback callback);
084}