Wicket Ajax

What ?

Since version 6.0 Wicket uses jQuery as a backing library for its Ajax functionality.

Why ?

The previous implementations of wicket-ajax.js and wicket-event.js were home baked solutions that worked well but also suffered from the differences in the browsers. Often users complained that some functionality doesn't work on particular version of particular browser. That's why the Wicket team chose to use jQuery to deal with browser inconsistencies and leave us to do our business logic.

Design and implementation

The new implementations (wicket-ajax-jquery.js and wicket-event-jquery.js) use jQuery internally but expose Wicket.** API similar to the previous version.

All Java components and behaviors should still use the Wicket.** API. This way if someday we decide to not use jQuery anymore we will have less work to do. Also if a user uses Dojo/YUI/ExtJS/... and prefer to not have jQuery in her application then she will be able to provide wicket-ajax-xyz.js implementation and replace the default one.

Table with renamed methods from the previous version

1.5	6.0
Wicket.fixEvent	Wicket.Event.fix
Wicket.stopEvent	Wicket.Event.stop
Wicket.show	Wicket.DOM.show
Wicket.showIncrementally	Wicket.DOM.showIncrementally
Wicket.hide	Wicket.DOM.hide
Wicket.hideIncrementally	Wicket.DOM.hideIncrementally
Wicket.decode	Wicket.Head.Contributor.decode
Wicket.ajaxGet, wicketAjaxGet	Wicket.Ajax.get
Wicket.ajaxPost, wicketAjaxPost	Wicket.Ajax.post
Wicket.submitForm	Wicket.Ajax.submitForm
Wicket.submitFormById	Wicket.Ajax.submitForm
Wicket.replaceOuterHtml	Wicket.DOM.replace
Wicket.Form.doSerialize	Wicket.Form.serializeForm

Configuration

Setup

To replace any of the JavaScript files the user application may use:

MyApplication#init():

public void init() {
  super.init();

  IJavaScriptLibrarySettings jsSettings = getJavaScriptLibrarySettings();

  jsSettings.setJQueryReference(new MyJQueryReference());

  jsSettings.setWicketEventReference(new DojoWicketEventReference());

  jsSettings.setWicketAjaxReference(new DojoWicketAjaxReference());

}

Resource dependencies

Since Wicket 6.0 ResourceReference can have dependencies and it is recommended to properly define the dependency chain between this classes.
See the code of org.apache.wicket.ajax.WicketAjaxJQueryResourceReference to see how the default jQuery based implementation does that.

If the user application needs to upgrade/downgrade to new/old version of jQuery then just the first line above is needed:

  getJavaScriptLibrarySettings().setJQueryReference(new AnotherVersionOfJQueryReference());

If the user application needs to use Dojo instead of jQuery then it has provide JavaScriptResourceReferences for wicket-event-dojo.js and wicket-ajax-dojo.js (e.g. DojoWicketEventReference and DojoWicketAjaxReference). Those references should define dependency to DojoReference (a reference that delivers dojo.js). Wicket uses IJavaScriptLibrarySettings#getWicketAjaxReference() and all its transitive dependencies for its JavaScript needs.

AjaxRequestAttributes

Each Ajax behavior and component can use o.a.w.ajax.attributes.AjaxRequestAttributes to configure how exactly the Ajax call should be executed and how its response should be handled. To do this use:

AnyAjaxComponent/AnyAjaxBehavior.java:

protected void updateAjaxAttributes(AjaxRequestAttributes attributes)
{
    super.updateAjaxAttributes(AjaxRequestAttributes attributes);

    attributes.[set some attribute]();
}

The available attributes are:

Name	Description	Default value	Short name
method	the request method to use (GET or POST)	GET	m
multipart	whether form submittion should use content type: multipart/form-data. Implies POST method	false	mp
event names	a list of event names for which the Ajax call will be executed. For example: click, change, keyup, etc.	domready	e
form id	the id of the form which should be submitted with this Ajax call.		f
submitting component name	the input name of the component which submits the form.		sc
data type	what kind of data is expected in the response of the Ajax call (e.g. XML, JSON, HTML, JSONP).	xml	dt
wicket ajax response	a 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	wr
channel	the name and type of the Ajax channel to use. Channels are used to queue the Ajax requests at the client side. See org.apache.wicket.ajax.AjaxChannel javadoc for more details.	channel with name '0', and 'queue' behavior	ch
ajax call listeners	a list of listeners which are called at the most important points of the lifetime of the Ajax call. See below for more information.	empty list	bh, pre, bsh, ah, sh, fh, coh
extra parameters	a map of parameters which should be added to the query string/post data of the Ajax call. The name and value of such parameters should be known at the server side.	empty map	ep
dynamic extra parameters	parameters which values are calculated at the client side and added dynamically to the query string/post data of the Ajax call.	empty list	dep
request timeout	a timeout to abort the request if there is no response.	0 (no timeout)	rt
allow default	a boolean flag which indicates whether to allow the default behavior of the HTML element which listens for the event. For example: clicking on Ajax checkbox should allow the default behavior to actually check the box.	false	ad
async	a boolean flag that indicates whether the Ajax call should be asynchronous or not.	true	async
throttling settings	settings which define whether the Ajax call should be throttled and for how long. See the javadoc of org.apache.wicket.ajax.attributes.ThrottlingSettings for more information.	no throttling	tr

Attributes 'c' (component id) and 'u' (callback url) are automatically set by the Ajax behavior and they are not part of AjaxRequestAttributes.

While constructing the JavaScript that will register the event listener for that Ajax component/behavior these settings are serialized to optimized JSON object which is passed as a parameter to Wicket.Ajax.(get|post|ajax) methods.
For example an AjaxLink contributes JavaScript similar to :

  Wicket.Ajax.get({"u":"the/url/to/the/link", "e": "click", "c":"linkId"});

Many of the attributes have default values which are not written in the JSON settings and they are initialized at the client side (i.e. wicket-ajax.js knows the defaults). The example above can be read as: when HTML element with id 'linkId' is clicked fire an Ajax call with Url 'the/url/to/the/link'.
If you need more examples how to use it from JS, take a look at wicket sources: wicket-core/src/test/js/ajax.js

Migration steps

o.a.w.ajax.IAjaxCallDecorator is replaced with o.a.w.ajax.attributes.IAjaxCallListener.

Since Wicket Ajax now register DOM events (like click, change, ...) instead of using inline attributes like onclick, onchange, ... there is no more a script to decorate. Instead the new implementation provides points to listen to:

before handler - executed before the data for the Ajax call is calculated. Even before the preconditions.
precondition - if it returns false then the Ajax call (and all handlers below) is not executed at all
beforeSend handler - executed before the actual execution of the Ajax call.
after handler - if the Ajax call is asynchronous then it is executed right after its firing. If it is synchronous then it is executed after the complete handler
success handler - executed on successful return of the Ajax call
failure handler - executed on unsuccessful return of the Ajax call
complete handler - executed at the very end. After either the success or failure handlers.

To use it do:
AnyAjaxComponent/AnyAjaxBehavior.java:

protected void updateAjaxAttributes(AjaxRequestAttributes attributes)
{
    super.updateAjaxAttributes(attributes);

    AjaxCallListener myAjaxCallListener = new AjaxCallListener() {

        @Override 
        public CharSequence getBeforeHandler(Component component) { 
            return "alert('I\'m executed before the firing of the Ajax call')"; 
        }
    };
    attributes.getAjaxCallListeners().add(myAjaxCallListener);
}

There are also handy methods like onBefore(CharSequence), onComplete(CharSequence), ... but they do not provide access to the component which is bound with the Ajax behavior.

An Ajax request can have 0 or more IAjaxCallListener's.
o.a.w.ajax.attributes.AjaxCallListener is an adapter of IAjaxCallListener that implements all methods with noop bodies. If the body returns null or empty string then it is discarded.

Global Ajax call listeners

IAjaxCallListener's can be used to listen for the lifecycle of an Ajax call for a specific component.
If the user application needs to listen for all Ajax calls then it may subscribe to the following topics:

/ajax/call/before
/ajax/call/precondition
/ajax/call/beforeSend
/ajax/call/after
/ajax/call/success
/ajax/call/failure
/ajax/call/complete

Those replaces the old Wicket.Ajax.(registerPreCallHandler|registerPostCallHandler|registerFailureHandler) methods and uses publish/subscribe mechanism.

Example (JavaScript):

Wicket.Event.subscribe('/ajax/call/failure', function(jqEvent, attributes, jqXHR, errorThrown, textStatus) {
  // do something when an Ajax call fails
});

All global listeners receive the same arguments as the respective IAjaxCallListener handler plus jQuery.Event that is passed by the PubSub system. This event is not the event that caused the Ajax call. The one that caused the Ajax call is 'attrs.event'.

There are two additional topics which are used to notify the subscribers when an HTML element is about to be removed and when a new one is added to the document:

/dom/node/removing - receives as parameters the jQuery.Event and the HTMLElement that will be removed
/dom/node/added - receives as parameters the jQuery.Event and the HTMLElement that has just been added

Automatically migrated attributes.

Some of the attributes are available from the previous versions of Wicket as an overridable methods in AbstractDefaultAjaxBehavior. These methods are marked as deprecated and will be removed in Wicket 7.0 and for now Wicket automatically translates them into AjaxRequestAttributes.
These methods are:

org.apache.wicket.ajax.AbstractDefaultAjaxBehavior#getPreconditionScript()
org.apache.wicket.ajax.AbstractDefaultAjaxBehavior#getSuccessScript()
org.apache.wicket.ajax.AbstractDefaultAjaxBehavior#getFailureScript()
org.apache.wicket.ajax.AbstractDefaultAjaxBehavior#getChannel()

It is recommended to override org.apache.wicket.ajax.AbstractDefaultAjaxBehavior#updateAjaxAttributes(AjaxRequestAttributes) and configure those directly in the passed 'attributes'.

Tests for the client side Wicket Ajax functionality

At ajax.js you may see the currently available JavaScript unit tests that we have for the Ajax functionality in wicket-ajax.js

Blog articles

An introduction to the new functionalities are described at Wicket In Action. There is also a link to a demo application.

FAQ

How to check whether my custom version of the backing JavaScript library (jQuery) doesn't break Wicket internals somehow ?

Clone Wicket from its Git repository
git clone http://git-wip-us.apache.org/repos/asf/wicket.git
Open wicket-core/src/test/js/all.html and change it to point to your version of the backing library.
Run the non-Ajax tests by opening file:///path/to/wicket/wicket-core/src/test/js/all.html
To run the Ajax tests see the description at the top of wicket-core/src/test/js/ajax.js. It is required to run them through Web Server

What parameters are passed to the handlers ?

before handler - attributes (the Ajax call attributes)
beforeSend handler - attributes, jqXHR (the jQuery XMLHttpRequest object), settings (the jQuery ajax settings)
after handler - attributes
success handler - attributes, jqXHR, data (the response), textStatus (the response status)
failure handler - attributes, errorMessage (the error message from jQuery)
complete handler - attrs, jqXHR, textStatus

The global listeners receive the same parameters prepended by jqEvent. This is the event triggered by jQuery. See section Global Ajax call listeners above.

How to use the preconditions with non-native/JavaScript-based confirm dialogs ?

See possible solutions from a mailing list discussion