    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}