WAjaxControl

WAjaxControl provides a mechanism to link a UI control to an asynchronous server request. WAjaxControl does not have a UI artefact itself, it is used to tell the UI that a particular component will trigger an AJAX action and which UI component(s) are the AJAX action's target(s).

A WAjaxControl is associated with a single trigger component but may have one or more target components.

• Example
• Trigger components
• Target components
• Intrinsic Ajax controllers
• Setting focus
• Related components
• Further information

Example

When a WButton which has an AJAX target is clicked, for example, an AJAX request is made to the server. The server response will only contain an update for the branch of the UI which starts at the target component.

It is possible to use other input components as AJAX triggers, and update multiple sections of the UI using WAjaxControl. The following code snippet shows how to set up an WAjaxControl which updates multiple components when a WButton is pressed.

final WTextField myTextField = new WTextField();
add(myTextField);

final WText myText = new WText();
WPanel myPanel = new WPanel();
myPanel.add(myText);
add(myPanel);

WButton myButton = new WButton("AJAX button");
add(myButton);

WAjaxControl ajaxControl = new WAjaxControl(myButton,
                            new AjaxTarget[]{myPanel, myTextField});

add(ajaxControl);

myButton.setAction(new Action() {
   public void execute(final ActionEvent event) {
      String message = "Updated at " + new Date();
      myText.setText(message);
      myTextField.setText(message);
   }
});

Trigger components

WComponents which are able to trigger a WAjaxControl implement the AjaxTrigger interface so the best reference for determining those controls is the Javadoc.

Target components

Any WComponent which implements the AjaxTarget interface may be a target component of a WAjaxControl.

Intrinsic Ajax controllers

Some container WComponents are interactive containers or containers which have the ability to retrieve or update their content asynchronously without needing an explicit WAjaxControl. These components are described in Ajax modes.

Setting focus

A response from an AJAX action may try to reset the focus point in the UI. This is done by calling setFocussed() (see com.github.bordertech.wcomponents.AbstractWComponent for JavaDoc) on the component to be focussed. This request for focus is not guaranteed to be honoured. Indeed, in most cases it will be ignored. See Setting focus for more information.

Focus will only be set after an AJAX transaction if the user has lost focus so as to not interrupt the current work flow. Focus will be lost only if:

1. the control which had focus at the time of the AJAX request is a target of that request or is a descendant of a target of the request; and
2. the user has not refocussed on another component manually between the request being made and the response being received; or
3. the user explicitly discards focus (for example by clicking on a non-interactive control or container) which is extremely unlikely.

See WApplication for information regarding setting default focus on page load.

Related components

• WSubordinateControl

Further information

• JavaDoc;
• JavaDoc AjaxTrigger;
• JavaDoc AjaxTarget
• Ajax modes;
• List of WComponents.