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    
015    package org.apache.tapestry5.services.ajax;
016    
017    import org.apache.tapestry5.ClientBodyElement;
018    import 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     */
030    public 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    }