org.omnifaces.component.script

Class CommandScript

java.lang.Object

javax.faces.component.UIComponent

javax.faces.component.UIComponentBase

javax.faces.component.UICommand

org.omnifaces.component.script.CommandScript

All Implemented Interfaces:

EventListener, ActionSource, ActionSource2, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder

public class CommandScript
extends UICommand

The <o:commandScript> is a component based on the standard <h:commandXxx> which generates a JavaScript function in the global JavaScript scope which allows the end-user to execute a JSF ajax request by just a function call functionName() in the JavaScript context.

The <o:commandScript> component is required to be enclosed in a UIForm component. The name attribute is required and it represents the JavaScript function name. The execute and render attributes work exactly the same as in <f:ajax>. The onbegin and oncomplete attributes must represent (valid!) JavaScript code which will be executed before sending the ajax request and after processing the ajax response respectively. The action, actionListener and immediate attributes work exactly the same as in <h:commandXxx>.

Basic usage example of <o:commandScript> which submits the entire form on click of a plain HTML button:

 <h:form>
     <h:inputText value="#{bean.input1}" ... />
     <h:inputText value="#{bean.input2}" ... />
     <h:inputText value="#{bean.input3}" ... />
     <o:commandScript name="submitForm" action="#{bean.submit}" render="@form" />
 </h:form>
 <input type="button" value="submit" onclick="submitForm()" />
 

Usage example which uses the <o:commandScript> as a poll function which updates every 3 seconds:

 <h:form>
     <h:dataTable id="data" value="#{bean.data}" ...>...</h:dataTable>
     <o:commandScript name="updateData" action="#{bean.reloadData}" render="data" />
 </h:form>
 <h:outputScript target="body">setInterval(updateData, 3000);</h:outputScript>
 

The component also supports nesting of <f:param>, <f:actionListener> and <f:setPropertyActionListener>, exactly like as in <h:commandXxx>. The function also supports a JS object as argument which will then end up in the HTTP request parameter map:

 functionName({ name1: "value1", name2: "value2" });
 

With the above example, the parameters are in the action method available as follows:

 String name1 = Faces.getRequestParameter("name1"); // value1
 String name2 = Faces.getRequestParameter("name2"); // value2
 

This is much similar to PrimeFaces <p:remoteCommand>, expect that the <o:commandScript> uses the standard JSF ajax API instead of the PrimeFaces/jQuery ajax API. So it wouldn't trigger jQuery-specific event listeners, but only JSF-specific event listeners (e.g. jsf.ajax.addOnEvent() and so on).

Since:

1.3

Author:

Bauke Scholtz

Field Summary

Fields

Modifier and Type	Field and Description
static String	COMPONENT_TYPE

Fields inherited from class javax.faces.component.UICommand

COMPONENT_FAMILY

Fields inherited from class javax.faces.component.UIComponent

ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY

Constructor Summary

Constructors

Constructor and Description
CommandScript() Constructs the CommandScript component.

Method Summary

Modifier and Type	Method and Description
void	decode(FacesContext context) If this command script was invoked, queue the ActionEvent accordingly.
void	encodeBegin(FacesContext context) Write a <span><script> with therein the script function which allows the end-user to execute a JSF ajax request by a just script function call functionName() in the JavaScript context.
void	encodeEnd(FacesContext context)
protected void	encodeFunction(FacesContext context, String name) Encode the script function.
protected void	encodeOneventOption(FacesContext context, String onbegin, String oncomplete) Create an option for the onevent function which contains the onbegin and oncomplete scripts.
protected void	encodeOptions(FacesContext context) Encode the JS object which holds the jsf.ajax.request options, such as additional request parameters from <f:param>, the values of execute and render attributes and the onevent function which contains the onbegin and oncomplete scripts.
String	getExecute() Returns a space separated string of client IDs to process on ajax request.
String	getFamily() Returns ScriptFamily.COMPONENT_FAMILY.
String	getName() Returns the script function name.
String	getOnbegin() Returns a script to execute before ajax request is fired.
String	getOncomplete() Returns a script to execute after ajax response is processed.
String	getRender() Returns a space separated string of client IDs to update on ajax response.
boolean	isAutorun() Returns whether the command script should automatically run inline during page load.
protected String	resolveClientIds(FacesContext context, String relativeClientIds) Resolve the given space separated collection of relative client IDs to absolute client IDs.
void	setAutorun(boolean autorun) Sets whether the command script should automatically run inline during page load.
void	setExecute(String execute) Sets a space separated string of client IDs to process on ajax request.
void	setName(String name) Sets the script function name.
void	setOnbegin(String onbegin) Sets a script to execute before ajax request is fired.
void	setOncomplete(String oncomplete) Sets a script to execute after ajax response is processed.
void	setRender(String render) Sets a space separated string of client IDs to update on ajax response.

Methods inherited from class javax.faces.component.UICommand

addActionListener, broadcast, getAction, getActionExpression, getActionListener, getActionListeners, getValue, isImmediate, queueEvent, removeActionListener, setAction, setActionExpression, setActionListener, setImmediate, setValue

Methods inherited from class javax.faces.component.UIComponentBase

addClientBehavior, addFacesListener, clearInitialState, encodeChildren, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getListenersForEventClass, getParent, getPassThroughAttributes, getRenderer, getRendererType, getRendersChildren, getValueBinding, invokeOnComponent, isRendered, isTransient, markInitialState, processDecodes, processRestoreState, processSaveState, processUpdates, processValidators, removeFacesListener, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding, subscribeToEvent, unsubscribeFromEvent

Methods inherited from class javax.faces.component.UIComponent

encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, setValueExpression, visitTree

Methods inherited from class java.lang.Object

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

Field Detail

COMPONENT_TYPE

public static final String COMPONENT_TYPE

See Also:

Constant Field Values

Constructor Detail

CommandScript

public CommandScript()

Constructs the CommandScript component.

Method Detail

getFamily

public String getFamily()

Returns ScriptFamily.COMPONENT_FAMILY.

Overrides:

getFamily in class UICommand

decode

public void decode(FacesContext context)

If this command script was invoked, queue the ActionEvent accordingly.

Overrides:

decode in class UIComponentBase

encodeBegin

public void encodeBegin(FacesContext context)
                 throws IOException

Write a <span><script> with therein the script function which allows the end-user to execute a JSF ajax request by a just script function call functionName() in the JavaScript context.

Overrides:

encodeBegin in class UIComponentBase

Throws:

IllegalStateException - When there is no parent form.

IllegalArgumentException - When the name attribute is missing, or when the name attribute does not represent a valid script function name.

IOException

encodeEnd

public void encodeEnd(FacesContext context)
               throws IOException

Overrides:

encodeEnd in class UIComponentBase

Throws:

IOException

encodeFunction

protected void encodeFunction(FacesContext context,
                              String name)
                       throws IOException

Encode the script function. It has the following syntax:

 var name = function() {
     jsf.ajax.request(clientId, null, options);
 });
 

The first argument clientId is the client ID of the current component which will ultimately be sent as javax.faces.source request parameter, so that the decode(FacesContext) can properly intercept on it. The second argument is the event type, which is irrelevant here. The third argument is a JS object which holds the jsf.ajax.request options, such as additional request parameters from <f:param>, the values of execute and render attributes and the onevent function which contains the onbegin and oncomplete scripts.

Parameters:

context - The faces context to work with.

name - The script function name.

Throws:

IOException - When something fails at I/O level.

encodeOptions

protected void encodeOptions(FacesContext context)
                      throws IOException

Encode the JS object which holds the jsf.ajax.request options, such as additional request parameters from <f:param>, the values of execute and render attributes and the onevent function which contains the onbegin and oncomplete scripts.

Parameters:

context - The faces context to work with.

Throws:

IOException - When something fails at I/O level.

encodeOneventOption

protected void encodeOneventOption(FacesContext context,
                                   String onbegin,
                                   String oncomplete)
                            throws IOException

Create an option for the onevent function which contains the onbegin and oncomplete scripts. This will return null when no scripts are been definied.

Parameters:

context - The faces context to work with.

onbegin - The onbegin script.

oncomplete - The oncomplete script.

Throws:

IOException - When something fails at I/O level.

resolveClientIds

protected String resolveClientIds(FacesContext context,
                                  String relativeClientIds)

Resolve the given space separated collection of relative client IDs to absolute client IDs.

Parameters:

context - The faces context to work with.

relativeClientIds - The space separated collection of relative client IDs to be resolved.

Returns:

A space separated collection of absolute client IDs, or null if the given relative client IDs is empty.

getName

public String getName()

Returns the script function name.

Returns:

The script function name.

setName

public void setName(String name)

Sets the script function name.

Parameters:

name - The script function name.

getExecute

public String getExecute()

Returns a space separated string of client IDs to process on ajax request.

Returns:

A space separated string of client IDs to process on ajax request.

setExecute

public void setExecute(String execute)

Sets a space separated string of client IDs to process on ajax request.

Parameters:

execute - A space separated string of client IDs to process on ajax request.

getRender

public String getRender()

Returns a space separated string of client IDs to update on ajax response.

Returns:

A space separated string of client IDs to update on ajax response.

setRender

public void setRender(String render)

Sets a space separated string of client IDs to update on ajax response.

Parameters:

render - A space separated string of client IDs to update on ajax response.

getOnbegin

public String getOnbegin()

Returns a script to execute before ajax request is fired.

Returns:

A script to execute before ajax request is fired.

setOnbegin

public void setOnbegin(String onbegin)

Sets a script to execute before ajax request is fired.

Parameters:

onbegin - A script to execute before ajax request is fired.

getOncomplete

public String getOncomplete()

Returns a script to execute after ajax response is processed.

Returns:

A script to execute after ajax response is processed.

setOncomplete

public void setOncomplete(String oncomplete)

Sets a script to execute after ajax response is processed.

Parameters:

oncomplete - A script to execute after ajax response is processed.

isAutorun

public boolean isAutorun()

Returns whether the command script should automatically run inline during page load.

Returns:

Whether the command script should automatically run inline during page load.

Since:

2.2

setAutorun

public void setAutorun(boolean autorun)

Sets whether the command script should automatically run inline during page load.

Parameters:

autorun - Whether the command script should automatically run inline during page load.

Since:

2.2