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.attributes;
018
019import org.apache.wicket.Component;
020
021/**
022 * Interface used to listen at the most important points when Wicket performs an Ajax callback.
023 *
024 * <p>Each method can return JavaScript that will be used as a body of a function that is executed
025 * at the appropriate time. If the method returns {@code null} or an empty string then it is ignored
026 * and no function will be executed for this listener. Each JavaScript function receives arguments
027 * in the exact order as specified in the method's javadoc.</p>
028 *
029 *  <p>Ajax call listeners are potential contributors to the page header by implementing
030 * {@link org.apache.wicket.markup.html.IComponentAwareHeaderContributor}. E.g. the JavaScript used
031 * by the listener may depend on some JavaScript library, by implementing
032 * {@link org.apache.wicket.markup.html.IComponentAwareHeaderContributor} interface they can assure
033 * it will be loaded.</p>
034 * 
035 * @since 6.0
036 */
037public interface IAjaxCallListener
038{
039        /**
040         * The JavaScript that will be executed on initialization of the Ajax call, immediately after the causing event.
041         * The script will be executed in a function that receives the following
042         * parameters:
043         * <ol>
044         * <li>attrs - the AjaxRequestAttributes as JSON</li>
045         * </ol>
046         * 
047         * @param component
048         *            the Component with the Ajax behavior
049         * @return the JavaScript that will be executed on initialization of the Ajax call.
050         */
051        default CharSequence getInitHandler(Component component)
052        {
053                return null;
054        }
055
056        /**
057         * The JavaScript that will be executed before the Ajax call, as early as possible. Even before
058         * the preconditions. The script will be executed in a function that receives the following
059         * parameters:
060         * <ol>
061         * <li>attrs - the AjaxRequestAttributes as JSON</li>
062         * </ol>
063         * 
064         * @param component
065         *            the Component with the Ajax behavior
066         * @return the JavaScript that will be executed before the Ajax call.
067         */
068        default CharSequence getBeforeHandler(Component component)
069        {
070                return null;
071        }
072
073        /**
074         * A JavaScript function that is invoked before the request is being executed. If it returns
075         * {@code false} then the execution of the Ajax call will be cancelled. The script will be
076         * executed in a function that receives the following parameters:
077         * <ol>
078         * <li>attrs - the AjaxRequestAttributes as JSON</li>
079         * </ol>
080         * 
081         * @param component
082         *            the Component with the Ajax behavior
083         * @return the JavaScript that should be used to decide whether the Ajax call should be made at
084         *         all.
085         */
086        default CharSequence getPrecondition(Component component)
087        {
088                return null;
089        }
090
091        /**
092         * The JavaScript that will be executed right before the execution of the the Ajax call, only if all
093         * preconditions pass. The script will be executed in a function that receives the following
094         * parameters:
095         * <ol>
096         * <li>attrs - the AjaxRequestAttributes as JSON</li>
097         * <li>jqXHR - the jQuery XMLHttpRequest object</li>
098         * <li>settings - the settings used for the jQuery.ajax() call</li>
099         * </ol>
100         * 
101         * @param component
102         *            the Component with the Ajax behavior
103         * @return the JavaScript that will be executed before the Ajax call.
104         */
105        default CharSequence getBeforeSendHandler(Component component)
106        {
107                return null;
108        }
109
110        /**
111         * The JavaScript that will be executed after the Ajax call. The script will be executed in a
112         * function that receives the following parameters:
113         * <ol>
114         * <li>attrs - the AjaxRequestAttributes as JSON</li>
115         * </ol>
116         * <strong>Note</strong>: if the Ajax call is synchronous (see
117         * {@link AjaxRequestAttributes#setAsynchronous(boolean)}) then this JavaScript will be executed
118         * after the {@linkplain #getCompleteHandler(org.apache.wicket.Component) complete handler},
119         * otherwise it is executed right after the execution of the Ajax request.
120         * 
121         * @param component
122         *            the Component with the Ajax behavior
123         * @return the JavaScript that will be executed after the start of the Ajax call but before its
124         *         response is returned.
125         */
126        default CharSequence getAfterHandler(Component component)
127        {
128                return null;
129        }
130
131        /**
132         * The JavaScript that will be executed after successful return of the Ajax call. The script
133         * will be executed in a function that receives the following parameters:
134         * <ol>
135         * <li>attrs - the AjaxRequestAttributes as JSON</li>
136         * <li>jqXHR - the jQuery XMLHttpRequest object</li>
137         * <li>data - the Ajax response. Its type depends on {@link AjaxRequestAttributes#dataType}</li>
138         * <li>textStatus - the status as text</li>
139         * </ol>
140         * 
141         * @param component
142         *            the Component with the Ajax behavior
143         * @return the JavaScript that will be executed after a successful return of the Ajax call.
144         */
145        default CharSequence getSuccessHandler(Component component)
146        {
147                return null;
148        }
149
150        /**
151         * The JavaScript that will be executed after unsuccessful return of the Ajax call. The script
152         * will be executed in a function that receives the following parameters:
153         * <ol>
154         * <li>attrs - the AjaxRequestAttributes as JSON</li>
155         * <li>jqXHR - the jQuery XMLHttpRequest object</li>
156         * <li>errorMessage - in case of HTTP error the textual portion of the HTTP status</li>
157         * <li>textStatus - type of failure: null, "timeout", "error", "abort" or "parsererror"</li>
158         * </ol>
159         * 
160         * @param component
161         *            the Component with the Ajax behavior
162         * @return the JavaScript that will be executed after a unsuccessful return of the Ajax call.
163         */
164        default CharSequence getFailureHandler(Component component)
165        {
166                return null;
167        }
168
169        /**
170         * The JavaScript that will be executed after both successful and unsuccessful return of the
171         * Ajax call. The script will be executed in a function that receives the following parameters:
172         * <ol>
173         * <li>attrs - the AjaxRequestAttributes as JSON</li>
174         * <li>jqXHR - the jQuery XMLHttpRequest object</li>
175         * <li>textStatus - the status as text</li>
176         * </ol>
177         * 
178         * @param component
179         *            the Component with the Ajax behavior
180         * @return the JavaScript that will be executed after both successful and unsuccessful return of
181         *         the Ajax call.
182         */
183        default CharSequence getCompleteHandler(Component component)
184        {
185                return null;
186        }
187
188        /**
189         * The JavaScript that will be executed after the Ajax call is done, regardless whether it was
190         * sent or not. The script will be executed in a function that receives the following
191         * parameters:
192         * <ol>
193         * <li>attrs - the AjaxRequestAttributes as JSON</li>
194         * </ol>
195         *
196         * @param component
197         *            the Component with the Ajax behavior
198         * @return the JavaScript that will be executed after the Ajax call is done.
199         */
200        default CharSequence getDoneHandler(Component component)
201        {
202                return null;
203        }
204}