001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.ajax;
018
019import java.util.Map;
020
021import org.apache.wicket.Component;
022import org.apache.wicket.Page;
023import org.apache.wicket.ajax.attributes.AjaxRequestAttributes;
024import org.apache.wicket.core.request.handler.IPartialPageRequestHandler;
025import org.apache.wicket.request.ILoggableRequestHandler;
026
027/**
028 *
029 * @since 6.0
030 */
031public interface AjaxRequestTarget extends IPartialPageRequestHandler, ILoggableRequestHandler
032{
033        /**
034         * An {@link AjaxRequestTarget} listener that can be used to respond to various target-related
035         * events
036         *
037         */
038        interface IListener
039        {
040                /**
041                 * Triggered before the target begins writing components.
042                 *
043                 * @param map
044                 *            modifiable map (markupId -> component) of components already added to the target
045                 * @param target
046                 *            the target itself. Could be used to add components or to append/prepend
047                 *            JavaScript
048                 *
049                 */
050                default void onBeforeRespond(Map<String, Component> map, AjaxRequestTarget target)
051                {}
052
053                /**
054                 * Triggered after the target has written components. At this point only
055                 * additional JavaScript can be added to the response.
056                 *
057                 * NOTE: During this stage of processing any calls that manipulate components will result in
058                 * an exception.
059                 *
060                 * @param map
061                 *            read-only map:markupId-&gt;component of components already added to the target
062                 * @param response
063                 *            response object that can be used to output JavaScript
064                 *            
065                 * @deprecated implement {@link #onAfterRespond(Map, AjaxRequestTarget)} instead
066                 */
067                @Deprecated
068                default void onAfterRespond(Map<String, Component> map, AjaxRequestTarget.IJavaScriptResponse response)
069                {}
070
071                /**
072                 * Triggered after the target has written components. At this point only
073                 * additional JavaScript can be added to the response.
074                 *
075                 * NOTE: During this stage of processing any calls that manipulate components will result in
076                 * an exception. After notification of all listeners no JavaScript can be added any longer.
077                 *
078                 * @param map
079                 *            read-only map:markupId-&gt;component of components already added to the target
080                 * @param target
081                 *            the target itself. Could be used to append/prepend JavaScript
082                 */
083                default void onAfterRespond(Map<String, Component> map, AjaxRequestTarget target)
084                {
085                        onAfterRespond(map, target::appendJavaScript);
086                }
087
088                /**
089                 * Triggered for every Ajax behavior. Can be used to configure common settings.
090                 * 
091                 * @param behavior
092                 *            the behavior the attributes are updated for
093                 * @param attributes
094                 *            The attributes for the Ajax behavior
095                 * @since 7.0.0
096                 */
097                default void updateAjaxAttributes(AbstractDefaultAjaxBehavior behavior, AjaxRequestAttributes attributes)
098                {}
099        }
100
101        /**
102         * An ajax JavaScript response that allows users to add JavaScript to be executed on the client
103         * side
104         *
105         * @author ivaynberg
106         * 
107         * @deprecated use {@link AjaxRequestTarget#prependJavaScript(CharSequence)} and
108         *             {@link AjaxRequestTarget#appendJavaScript(CharSequence)} instead
109         */
110        @Deprecated
111        @FunctionalInterface
112        interface IJavaScriptResponse
113        {
114                /**
115                 * Adds more JavaScript to the ajax response that will be executed on the client side
116                 *
117                 * @param script
118                 *            JavaScript
119                 */
120                void addJavaScript(String script);
121        }
122
123        /**
124         * Components can implement this interface to get a notification when AjaxRequestTarget begins
125         * to respond. This can be used to postpone adding components to AjaxRequestTarget until the
126         * response begins.
127         *
128         * @author Matej Knopp
129         */
130        @FunctionalInterface
131        interface ITargetRespondListener
132        {
133                /**
134                 * Invoked when AjaxRequestTarget is about to respond.
135                 *
136                 * @param target
137                 */
138                void onTargetRespond(AjaxRequestTarget target);
139        }
140
141        /**
142         * Adds a listener to this target
143         *
144         * @param listener
145         * @throws IllegalStateException
146         *             if {@link AjaxRequestTarget.IListener}'s events are currently being fired or have both been fired
147         *             already
148         */
149        void addListener(AjaxRequestTarget.IListener listener);
150
151        /**
152         * Register the given respond listener. The listener's
153         * {@link org.apache.wicket.ajax.AjaxRequestTarget.ITargetRespondListener#onTargetRespond} method will be invoked when
154         * the {@link AjaxRequestTarget} starts to respond.
155         *
156         * @param listener
157         */
158        void registerRespondListener(ITargetRespondListener listener);
159
160        /**
161         * Returns the HTML id of the last focused element.
162         *
163         * @return markup id of last focused element, <code>null</code> if none
164         */
165        String getLastFocusedElementId();
166
167        /**
168         * Returns the page. Be aware that the page can be instantiated if this wasn't the case already.
169         *
170         * @return page instance
171         */
172        @Override
173        Page getPage();
174}