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}