public abstract class UIAjaxComponent extends Object
Abstract class for implementing an Ajax component.
A user interface service or a user interface editor (defined using a UIBeanEditor) can
dynamically perform certain operations using an Ajax component.
An Ajax component may be used when dynamic operations must be performed inside a user interface service or a user interface editor.
If the Ajax component is used by a user interface editor, then it must be
defined in the data model declaring the UIBeanEditor.
If the Ajax component is used by a user interface service, then it must be
either defined in the data model or the module declaring the service.
The component must be declared as a global element in the data model, as follows:
Documentation
<xs:complexType name="MyAjaxComponentName">
<xs:annotation>
<xs:appinfo>
<osd:ajaxComponent class="com.foo.MyAjaxComponent"/>
</xs:appinfo>
</xs:annotation>
</xs:complexType>
Where com.foo.MyAjaxComponent is
the fully qualified name of a class extending this class.
The declaration may also use parameters:
<osd:ajaxComponent class="com.foo.MyAjaxComponent">
<param1>...</param1>
<param2>...</param2>
</osd:ajaxComponent>
where param1 and param2 are JavaBean properties
of com.foo.MyAjaxComponent class.
For more information, see the JavaBean specification.
An Ajax component can also be used by a service defined in a module.
The component must be declared in the module.xml file associated
with the corresponding module.
The component is declared as follows:
<ajaxComponents>
<ajaxComponent name="MyAjaxComponentName" className="com.foo.MyAjaxComponent"/>
</ajaxComponents>
The element ajaxComponents must declare all
Ajax components available to the services defined
in this module.
com.foo.MyAjaxComponent is
the fully qualified name of a class extending this class.
The client-server interaction process consists of the following steps:
UIResourceLocator.getURLForAjaxComponent(String).
setParam1(...) and setParam2(...)).
doAjaxResponse(UIAjaxContext) is invoked on the instantiated object.
The use of an Ajax component implies correctly handling the HTTP request and HTTP response using JavaScript code.
To facilitate the use of Ajax components, EBX® provides the
JavaScript prototype EBX_AJAXResponseHandler for sending the request and handling the response.
This prototype defines the method sendRequest(urlToAjaxComponent) for sending the Ajax request.
The URL to the Ajax component can found by calling the method
UIResourceLocator.getURLForAjaxComponent(String)
(in the context of a UIBeanEditor, a UIAjaxContext, or a ServiceContext).
The following methods must be redefined and are mandatory in JavaScript classes that will use
the EBX_AJAXResponseHandler prototype.
handleAjaxResponseSuccess(responseContent):
this method defines the operations to perform if the Ajax
response has been generated successfully.
The parameter responseContent contains the plain-text response generated by this component.
handleAjaxResponseFailed(responseContent):
this method defines the operations to perform if the Ajax response
has failed, namely in case of a network error or server-side exception in doAjaxResponse(UIAjaxContext).
The parameter responseContent contains the plain-text response generated by this component.
The following JavaScript example shows how to use this prototype:
// Definition of the custom Ajax handler
MyAjaxHandler = function(anyParameters){
// Not mandatory, but for potential storage of parameters (eg. an id of an HTML element)
this.initialParameters = anyParameters;
// This method is mandatory
this.handleAjaxResponseSuccess = function(responseContent){
// Operations to perform if the Ajax response has been successfully generated.
};
// This method is mandatory
this.handleAjaxResponseFailed = function(responseContent){
// Operations to perform if the Ajax response has failed.
};
};
// Specifies that the custom Ajax handler uses the prototype provided by EBX®
MyAjaxHandler.prototype = new EBX_AJAXResponseHandler();
// Defines the function that sends the Ajax request.
// This function can be attached to a JavaScript event (i.e. onclick, onkeydown etc.).
function callAjaxComponent(anyParameters, anyRequestParameter){
// Initializes the custom Ajax handler
var myAjaxHandler = new MyAjaxHandler(anyParameters);
// Some parameters can be added to the request, then retrieved on the server side using UIAjaxContext.getOptionalRequestParameterValue(String)
var requestParameter = "¶meter=" + anyRequestParameter;
// Sends the request to the given Ajax component.
// The URL to the Ajax component is obtained calling UIResourceLocator.getURLForAjaxComponent(String)
myAjaxHandler.sendRequest(urlToAjaxComponent + requestParameter);
};
When the function sendRequest(urlToAjaxComponent) is called,
the request is sent to the server and the method doAjaxResponse(UIAjaxContext)
of the corresponding Ajax component is called. The server sends the response from the Ajax component
to the client code, and the function handleAjaxResponseSuccess or
handleAjaxResponseFailed will be automatically called to
handle the response.
If the method doAjaxResponse(UIAjaxContext) throws an Exception, the exception's
message will be added to kernel.log. On the client side, the method
handleAjaxResponseFailed(responseContent) will be invoked.
Error, warning and info messages can also be added to the client-side message box by calling
UIAjaxContext.addUserMessage(UserMessage).
The EBX® container ensures that an instance of this class is executed by no more than one thread at any given time.
UIResourceLocator.getURLForAjaxComponent(String),
UI Developer Guide| Constructor and Description |
|---|
UIAjaxComponent() |
| Modifier and Type | Method and Description |
|---|---|
abstract void |
doAjaxResponse(UIAjaxContext aResponse)
When the client sends an HTTP request targeting this component,
this method is invoked.
|
public abstract void doAjaxResponse(UIAjaxContext aResponse)
UIBodyWriter.add(String)