DiF provides support for AJAX out-of-the-box.
It is intended that developers build applications with AJAX-like resources without having to implement a single line of code of the AJAX request management, XML/JSON encoding of data and JavaScript dynamic update of the page components. This is made possible, again though convention, by using the @OnAJAX tag and the UI Components many AJAX features.
We can see the reference documentation on this annotation here.
These methods are meant to be called by the AJAX servlet. All AJAX enabled DiF web applications should have this servlet declared in the web.xml descriptor. See here for more on this.
This servlet interprets the requested ajax event id, and executes the associated stage method.
These AJAX event methods can have several return types. They will be processed by DiF's stage enhancement code and added to the DIFResponse output map.
The AJAX renderer will then pick them up and render them in JSON or XML, whichever we have requested in the AJAX event call.
This is as simple as this. The XML/JSON conversion is taken care by the AJAX renderer, and the method invocation is managed as usual by the internal DiF's ChAL/Dispatcher "team".
An AJAX submit is much like a normal page submit.
For a normal page request we issue something like this:
http://server/appContext/page?stage=someStageID¶m1=value1¶m2=value2
If we wish to place an AJAX event request we must call a diferent servlet, the AJAX servlet, and specify what event we want executed. Like this:
http://server/appContext/ajax?stage=someStageID&_ajaxevent=eventID¶m1=value1¶m2=value2
As you can see we submit the request to the ajax servlet (instead of the page servlet).
We still have to pass the stage ID, since all AJAX events must be implemented in a stage, and add the _ajaxevent to identify the ajax evento we want to execute.
This is all academic, for the normal user, since we will never have to issue such a request if we use the DIF UI Component set. With these components we simply have to configure them to use the given AJAX event ID for data gathering and they will take care of the rest.
AJAX requests are, as we've seen above, stage requests above all. They have all the stage resources available, as messages, access control, and... parameter validation and managment.
As such AJAX requests do not required any additional parameter management feature. All stage parameter annotated attributes can be accessed by the AJAX event handler method, thus having all the default DiF's parameter managment functionalities like, scope, default values, type conversion and constraint validation.
There are several components that support AJAX requests native and automatically:
The majority of these work with @OnAjax events on the server class, and others are meant to be used with each other.
You can see the usage details on each component reference page listed above.
DIF provides this functionality through the combined usage of the components:
As you can see in their documentation pages a DIF component that a specific stage (let's call it "innerPage") should be inserted in-place, inside the host page.
With the "innerPage" set up, you can instruct either the ajaxRequest or serverProcess components to issue an update of the corresponding page section after sucessfull and/or erroneous execution of their specific tasks.
You can see usage samples on the these component reference pages.
When the automated tasks do not provide all that you require, you can extend them, or implement whatever AJAX bahaviour you need in your web pages.
You can do it using the same Client side JavaScript API that the DIF integrates and so take advantage of the deployed API allready present in your pages. \
The DIF AJAX implementation uses ExtJS from Sencha.
You can use it to execute whatever AJAX event you need, and even use the @OnAjax event methods that will convert any return type to JSON automatically.