Module org.omnifaces

Package org.omnifaces.util

Class Ajax

java.lang.Object

org.omnifaces.util.Ajax

public final class Ajax
extends Object

Collection of utility methods for working with PartialViewContext. There are also shortcuts to the current OmniPartialViewContext instance.

This utility class allows an easy way of programmaticaly (from inside a managed bean method) specifying new client IDs which should be ajax-updated via update(String...), also UIData rows or columns on specific index via updateRow(UIData, int) and updateColumn(UIData, int), specifying callback scripts which should be executed on complete of the ajax response via oncomplete(String...), and loading new JavaScript resources on complete of the ajax response via load(String, String).

It also supports adding arguments to the JavaScript scope via data(String, Object), data(Map) and data(Object...). The added arguments are during the "on complete" phase as a JSON object available by OmniFaces.Ajax.data in JavaScript context. The JSON object is encoded by Json.encode(Object) which supports standard Java types Boolean, Number, CharSequence and Date arrays, Collections and Maps of them and as last resort it will use the Introspector to examine it as a Javabean and encode it like a Map.

Note that updateRow(UIData, int) and updateColumn(UIData, int) can only update cell content when it has been wrapped in some container component with a fixed ID.

Usage

Here are some examples:

 // Update specific component on complete of ajax.
 Ajax.update("formId:someId");
 

 // Load script resource on complete of ajax.
 Ajax.load("libraryName", "js/resourceName.js");
 

 // Add variables to JavaScript scope.
 Ajax.data("foo", foo); // It will be available as OmniFaces.Ajax.data.foo in JavaScript.
 

 // Execute script on complete of ajax.
 Ajax.oncomplete("alert(OmniFaces.Ajax.data.foo)");
 

For a full list, check the method summary.

Since:

1.2

Author:

Bauke Scholtz

See Also:

Json, OmniPartialViewContext, OmniPartialViewContextFactory

Method Summary

Modifier and Type	Method	Description
static void	data(Object... namesValues)	Add the given data arguments to the current ajax response.
static void	data(String name, Object value)	Add the given data argument to the current ajax response.
static void	data(Map<String,Object> data)	Add the given mapping of data arguments to the current ajax response.
static PartialViewContext	getContext()	Returns the current partial view context (the ajax context).
static boolean	isExecuted(String clientId)	Returns true if the given client ID was executed in the current ajax request.
static void	load(String libraryName, String resourceName)	Load given script resource on complete of the current ajax response.
static void	oncomplete(String... scripts)	Execute the given scripts on complete of the current ajax response.
static void	update(String... clientIds)	Update the given client IDs in the current ajax response.
static void	updateAll()	Update the entire view.
static void	updateColumn(UIData table, int index)	Update the column of the given UIData component at the given zero-based column index.
static void	updateRow(UIData table, int index)	Update the row of the given UIData component at the given zero-based row index.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getContext

public static PartialViewContext getContext()

Returns the current partial view context (the ajax context).

Note that whenever you absolutely need this method to perform a general task, you might want to consider to submit a feature request to OmniFaces in order to add a new utility method which performs exactly this general task.

Returns:

The current partial view context.

See Also:

FacesContext.getPartialViewContext()

update

public static void update(String... clientIds)

Update the given client IDs in the current ajax response. Note that those client IDs should not start with the naming container separator character like :. This method also supports the client ID keywords @all, @form and @this which respectively refers the entire view, the currently submitted form as obtained by Components.getCurrentForm() and the currently processed component as obtained by UIComponent.getCurrentComponent(FacesContext). Any other client ID starting with @ is by design ignored, including @none.

Parameters:

clientIds - The client IDs to be updated in the current ajax response.

See Also:

PartialViewContext.getRenderIds()

updateAll

public static void updateAll()

Update the entire view.

Since:

1.5

See Also:

PartialViewContext.setRenderAll(boolean)

updateRow

public static void updateRow(UIData table,
                             int index)

Update the row of the given UIData component at the given zero-based row index. This will basically update all direct children of all UIColumn components at the given row index.

Note that the to-be-updated direct child of UIColumn must be a fullworthy Faces UI component which renders a concrete HTML element to the output, so that JS/ajax can update it. So if you have due to design restrictions for example a <h:panelGroup rendered="..."> without an ID, then you should give it an ID. This way it will render a <span id="..."> which is updateable by JS/ajax.

Parameters:

table - The UIData component.

index - The zero-based index of the row to be updated.

Since:

1.3

updateColumn

public static void updateColumn(UIData table,
                                int index)

Update the column of the given UIData component at the given zero-based column index. This will basically update all direct children of the UIColumn component at the given column index in all rows. The column index is the physical column index and does not depend on whether one or more columns is rendered or not (i.e. it is not necessarily the same column index as the enduser sees in the UI).

Note that the to-be-updated direct child of UIColumn must be a fullworthy Faces UI component which renders a concrete HTML element to the output, so that JS/ajax can update it. So if you have due to design restrictions for example a <h:panelGroup rendered="..."> without an ID, then you should give it an ID. This way it will render a <span id="..."> which is updateable by JS/ajax.

Parameters:

table - The UIData component.

index - The zero-based index of the column to be updated.

Since:

1.3

load

public static void load(String libraryName,
                        String resourceName)

Load given script resource on complete of the current ajax response. Basically, it loads the script resource as a String and then delegates it to oncomplete(String...).

Parameters:

libraryName - Library name of the JavaScript resource.

resourceName - Resource name of the JavaScript resource.

Throws:

IllegalArgumentException - When given script resource cannot be found.

IllegalStateException - When current request is not an ajax request with partial rendering. You should use Components.addScriptResource(String, String) instead.

Since:

2.3

oncomplete

public static void oncomplete(String... scripts)

Execute the given scripts on complete of the current ajax response.

Parameters:

scripts - The scripts to be executed.

Throws:

IllegalStateException - When current request is not an ajax request with partial rendering. You should use Components.addScript(String) instead.

See Also:

OmniPartialViewContext.addCallbackScript(String)

data

public static void data(String name,
                        Object value)

Add the given data argument to the current ajax response. They are as JSON object available by OmniFaces.Ajax.data.

Parameters:

name - The argument name.

value - The argument value.

See Also:

OmniPartialViewContext.addArgument(String, Object)

data

public static void data(Object... namesValues)

Add the given data arguments to the current ajax response. The arguments length must be even. Every first and second argument is considered the name and value pair. The name must always be a String. They are as JSON object available by OmniFaces.Ajax.data.

Parameters:

namesValues - The argument names and values.

Throws:

IllegalArgumentException - When the arguments length is not even, or when a name is not a string.

See Also:

OmniPartialViewContext.addArgument(String, Object)

data

public static void data(Map<String,Object> data)

Add the given mapping of data arguments to the current ajax response. They are as JSON object available by OmniFaces.Ajax.data.

Parameters:

data - The mapping of data arguments.

See Also:

OmniPartialViewContext.addArgument(String, Object)

isExecuted

public static boolean isExecuted(String clientId)

Returns true if the given client ID was executed in the current ajax request.

Parameters:

clientId - The client ID to be checked.

Returns:

true if the given client ID was executed in the current ajax request.

Since:

3.6