wicket-user-guide/src/main/asciidoc/ajax/ajax_5.adoc

Wicket has two entities which allow us to control how an AJAX request is generated on client side and to specify the custom JavaScript code we want to execute during request handling. These entities are class _AjaxRequestAttributes_ and interface _IAjaxCallListener_, both placed in package _org.apache.wicket.ajax.attributes_.

AjaxRequestAttributes exposes the attributes used to generate the JavaScript call invoked on client side to start an AJAX request. Each attribute will be passed as a  http://en.wikipedia.org/wiki/JSON[JSON] parameter to the JavaScript function _Wicket.Ajax.ajax_ which is responsible for sending the concrete AJAX request. Every JSON parameter is identified by a short name. Here is a partial list of the available parameters:

|===
|*Short name* | *Description* | *Default value*
|u | The callback URL used to serve the AJAX request that will be sent. |
|c | The id of the component that wants to start the AJAX call. |
|e | A list of event (click, change, etc...) that can trigger the AJAX call. | domready
|m | The request method that must be used (GET or POST). | GET
|f | The id of the form that must be submitted with the AJAX call. |
|mp | If the AJAX call involves the submission of a form, this flag indicates whether the data must be encoded using the encoding mode “multipart/form-data”. | false
|sc | The input name of the submitting component of the form |
|async | A boolean parameter that indicates if the AJAX call is asynchronous (true) or not. | true
|dt | Specifies the type of data returned by the AJAX call (XML, HTML, JSON, etc...). | XML
|wr | Boolean flag which indicates whether the response is <ajax-response> which is handled by wicket-ajax.js or custom response type which can be handled by application's code (e.g. in IAjaxCallListener's success handler). | true
|ih, bh, pre, bsh, ah, sh, fh, coh, dh | This is a list of the listeners that are executed on client side (they are JavaScript scripts) during the lifecycle of an AJAX request. Each short name is the abbreviation of one of the methods defined in the interface IAjaxCallListener (see below). | An empty list
|===

NOTE: A full list of the available request parameters as well as more details on the related JavaScript code can be found at  https://cwiki.apache.org/confluence/display/WICKET/Wicket+Ajax[https://cwiki.apache.org/confluence/display/WICKET/Wicket+Ajax] .

Parameters 'u' (callback URL) and 'c' (the id of the component) are generated by the AJAX behavior that will serve the AJAX call and they are not accessible through _AjaxRequestAttributes_.

Here is the final AJAX function generate for the behavior used in example project _AjaxEventBehavior_ Example:

[source,java]
----
Wicket.Ajax.ajax({"u":"./?0-1.IBehaviorListener.0-clickCounterLabel", "e":"click",               
                  "c":"clickCounterLabel1"});
----

Even if most of the times we will let Wicket generate request attributes for us, both AJAX components and behaviors give us the chance to modify them overriding their method _updateAjaxAttributes (AjaxRequestAttributes attributes)_. 

One of the attribute we may need to modify is the list of _IAjaxCallListeners_ returned by method _getAjaxCallListeners()_. 

_IAjaxCallListener_ defines a set of methods which return the JavaScript code (as a _CharSequence_) that must be executed on client side when the AJAX request handling reaches a given stage:

* *getInitHandler(Component)*: returns the JavaScript code that will be executed on initialization of the Ajax call, immediately after the causing event. The code is executed in a scope where it can use variable attrs, which is an array containing the JSON parameters passed to Wicket.Ajax.ajax.
* *getBeforeHandler(Component)*: returns the JavaScript code that will be executed before any other handlers returned by IAjaxCallListener. The code is executed in a scope where it can use variable attrs, which is an array containing the JSON parameters passed to Wicket.Ajax.ajax. 
* *getPrecondition(Component)*: returns the JavaScript code that will be used as precondition for the AJAX call. If the script returns false then neither the Ajax call nor the other handlers will be executed. The code is executed in a scope where it can use variable attrs, which is the same variable seen for getBeforeHandler. 
* *getBeforeSendHandler(Component)*: returns the JavaScript code that will be executed just before the AJAX call is performed. The code is executed in a scope where it can use variables attrs, jqXHR and settings:
** attrs is the same variable seen for getBeforeHandler.
** jqXHR is the the jQuery XMLHttpRequest object used to make the AJAX call.
** settings contains the settings used for calling jQuery.ajax().
* *getAfterHandler(Component)*: returns the JavaScript code that will be executed after the AJAX call. The code is executed in a scope where it can use variable attrs, which is the same variable seen before for getBeforeHandler. 
* *getSuccessHandler(Component)*: returns the JavaScript code that will be executed if the AJAX call has successfully returned. The code is executed in a scope where it can use variables attrs, jqXHR, data and textStatus:
** attrs and jqXHR are same variables seen for getBeforeSendHandler:
** data is the data returned by the AJAX call. Its type depends on parameter wr (Wicket AJAX response).
** textStatus it's the status returned as text.
* *getFailureHandler(Component)*: returns the JavaScript code that will be executed if the AJAX call has returned with a failure. The code is executed in a scope where it can use variable attrs, which is the same variable seen for getBeforeHandler. 
* *getCompleteHandler(Component)*: returns the JavaScript that will be invoked after success or failure handler has been executed. The code is executed in a scope where it can use variables attrs, jqXHR and textStatus which are the same variables seen for getSuccessHandler. 
* *getDoneHandler(Component)*: returns the JavaScript code that will be executed after the Ajax call is done, regardless whether it was sent or not. The code is executed in a scope where it can use variable attrs, which is an array containing the JSON parameters passed to Wicket.Ajax.ajax.

In the next paragraph we will see an example of custom _IAjaxCallListener_ designed to disable a component during AJAX request processing.