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}