Client side code: Javascript API
JavAjax uses a javascript object to perform some activities, such error field highlighting or message/error reporting. This javascript object, Javajax, can be useful at application level as well.
- getContextPath(): returns a string containing the server context on which the application has been deployed (i.e. http://www.mysite.com/myapp/ would return /myapp/)
- loadJS(jsFile): dynamically loads the specified js file.
- loadCSS(cssFile): dynamically loads the specified css file.
- serialize(htmlElement | htmlElement.name | htmlElement.id): returns an Hash representing the serialization of any input field contained in the specified HTML element. This is useful when a large number of fields should be posted to the server. Instead of creating an Hash programatically, this method does the job for you.
- cleanErrors(htmlElement | htmlElement.name | htmlElement.id): removes any message/error report and any field highlighting contained in the specified HTML element, or on the whole page if a container is not specified.
- highLight(htmlElement): Highlights the specified field, basically adding the css class "javajax_errorfield" as the framework would do.
- searchField(fieldName, htmlElement | htmlElement.name | htmlElement.id): searches and returns the input field with the given name, optionally a container can be specified to restrict where the search should be performed.
- searchMessageContainer(htmlElement | htmlElement.name | htmlElement.id): searches and returns the first message display area created by the Tag
<javajax:messages/>
, optionally a container can be specified to restrict where the search should be performed. - searchSystemErrorContainer: searches and returns the first error display area created by the Tag
<javajax:errors/>
which is not linked to any field, optionally a container can be specified to restrict where the search should be performed. - searchFieldErrorContainer(fieldName, htmlElement | htmlElement.name | htmlElement.id): searches and returns the first error display area created by the Tag
<javajax:errors/>
which is linked to the given field, optionally a container can be specified to restrict where the search should be performed. - getLocalizedLabel(keyName, bindingName): returns the localized label referred to the specified keyName, optionally the Action URL binding name can be specified to include its resource bundle in the search domain.
- getLocalizedMessage(fieldName, keyName, bindingName): returns the localized message referred to the specified keyName for the specified field, optionally the Action URL binding name can be specified to include its resource bundle in the search domain.
Client side code: Javascript Action Interface
JavAjax offers a simple and safe way to call your action methods: Javascript Action Interface. Basically you can obtain the Action interface importing a generated javascript file, requested through the URL [Action Class|Binding].[javascript extension].By default, javascript extension is "ajs", or you can specify one in the filter configuration.
Please note that if the URLBinding contains a path, it must be specified when requesting the ajs file. Moreover, the relative javascript object name will be built adding the path to the Action className, in java syntax (i.e. action bound to "admin/Report" will generate the javascript object "AdminReport", and the url to obtain it will be "/admin/Report.ajs")
<script type="text/javascript" src="MyAction.ajs"/>
The obtained file will contain the Action interface, that will give you access to the Action methods, both for ajax and page modes.
Calling the Action in ajax mode
Ajax call is performed through the javascript call MyAction.myMethod.ajax({callParameters}), passing an hash containing specification for the call. Callback functions
will receive either Response object or jqXHR object, depending on what js framework you use, prototype.js or jquery.Available Call Parameters:
- parameters: hash containing key:value pairs that we want to post to the Action.
- container: an HTML container where the input elements should be searched in case of error.
- method: can be POST or GET, defaults to POST
- onSuccess: a callback function that will be called when no errors are raised
- onFailure: a callback function that will be called when errors are raised
- onComplete: a callback function that will be always called
- onValidationError: a callback function that will be called when one or more validation errors are raised
- onXXX: a callback function that will be called when the response has a statusCode that is equal to the specified XXX value.
- disableErrorHandling: if true, field highlighting and error message display are disabled, onFailure and onValidationError callbacks are still invoked.
- asynchronous: true if the Ajax call should be asynchronous (Default), false otherwise.
Usage:
MyAction.myMethod.ajax(
parameters:{name:'Banjamin',surname:'Franklin'}
, method:'GET'
, onSuccess:function(response|jqXHR) {
...
}
, onFailure:function(response|jqXHR) {
...
}
, on404:function(response|jqXHR) {
...
}
);
Calling the Action in page mode
Page mode call is performed through the javascript call MyAction.myMethod.page({callParameters}), passing an hash containing specification for the call.Available Call Parameters:
- parameters: hash containing key:value pairs that we want to post to the Action.
- method: can be POST or GET, defaults to POST
- target: name of the window where to open the called resource, defaults to "self"
- container: an HTML container where the input elements should be searched in case of error.
Usage:
MyAction.myMethod.page(
parameters:{name:'Banjamin',surname:'Franklin'}
, method:'GET'
, target:'mySecondWindow'
);