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

Link to jsdoc

TODO

Configuration

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

MyApplication#init():

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

  getJavaScriptLibrarySettings().setBackingLibraryReference(DojoReference.class);

  getJavaScriptLibrarySettings().setWicketEventReference(DojoWicketEventReference.class);
  
  getJavaScriptLibrarySettings().setWicketAjaxReference(DojoWicketAjaxReference.class);

}

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().setBackingLibraryReference(AnotherVersionOfJQueryReference.class);

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 fire of the Ajax call
• after handler - executed after the fire of the Ajax call but before it returns (if the Ajax call is asynchronous)
• success handler - executed on successful return of the Ajax call
• failure handler - executed on unsuccessful return of the Ajax call
• complete handler - executed on both successful and unsuccessful return

To use it do:
AnyAjaxComponent/AnyAjaxBehavior.java:

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

      AjaxCallListener myAjaxCallListener = new AjaxCallListener() {

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

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.