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:

java.util.EventListener, javax.faces.component.ActionSource, javax.faces.component.ActionSource2, javax.faces.component.PartialStateHolder, javax.faces.component.StateHolder, javax.faces.event.ComponentSystemEventListener, javax.faces.event.FacesListener, javax.faces.event.SystemEventListenerHolder

public class CommandScript
extends javax.faces.component.UICommand

CommandScript is an extension to <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
 

Since:

1.3

Author:

Bauke Scholtz

Field Summary

static java.lang.String

COMPONENT_TYPE

Fields inherited from class javax.faces.component.UICommand

COMPONENT_FAMILY

Fields inherited from class javax.faces.component.UIComponent

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

Constructor Summary

CommandScript()

Method Summary

void	decode(javax.faces.context.FacesContext context) If this command script was invoked, queue the ActionEvent accordingly.
void	encodeChildren(javax.faces.context.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.
protected void	encodeFunction(javax.faces.context.FacesContext context, java.lang.String name) Encode the script function.
protected void	encodeOneventOption(javax.faces.context.FacesContext context, java.lang.String onbegin, java.lang.String oncomplete) Create an option for the onevent function which contains the onbegin and oncomplete scripts.
protected void	encodeOptions(javax.faces.context.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.
java.lang.String	getExecute() Returns a space separated string of client IDs to process on ajax request.
java.lang.String	getFamily() Returns ScriptFamily.COMPONENT_FAMILY.
java.lang.String	getName() Returns the script function name.
java.lang.String	getOnbegin() Returns a script to execute before ajax request is fired.
java.lang.String	getOncomplete() Returns a script to execute after ajax response is processed.
java.lang.String	getRender() Returns a space separated string of client IDs to update on ajax response.
boolean	getRendersChildren() Returns true.
protected java.lang.String	resolveClientIds(javax.faces.context.FacesContext context, java.lang.String relativeClientIds) Resolve the given space separated collection of relative client IDs to absolute client IDs.
void	setExecute(java.lang.String execute) Sets a space separated string of client IDs to process on ajax request.
void	setName(java.lang.String name) Sets the script function name.
void	setOnbegin(java.lang.String onbegin) Sets a script to execute before ajax request is fired.
void	setOncomplete(java.lang.String oncomplete) Sets a script to execute after ajax response is processed.
void	setRender(java.lang.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, encodeBegin, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, getValueBinding, invokeOnComponent, isRendered, isTransient, markInitialState, processDecodes, processRestoreState, processSaveState, processUpdates, processValidators, removeFacesListener, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding

Methods inherited from class javax.faces.component.UIComponent

encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getListenersForEventClass, getNamingContainer, getResourceBundleMap, getStateHelper, getStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, setInView, setValueExpression, subscribeToEvent, unsubscribeFromEvent, 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 java.lang.String COMPONENT_TYPE

See Also:

Constant Field Values

Constructor Detail

CommandScript

public CommandScript()

Method Detail

getFamily

public java.lang.String getFamily()

Returns ScriptFamily.COMPONENT_FAMILY.

Overrides:

getFamily in class javax.faces.component.UICommand

getRendersChildren

public boolean getRendersChildren()

Returns true.

Overrides:

getRendersChildren in class javax.faces.component.UIComponentBase

decode

public void decode(javax.faces.context.FacesContext context)

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

Overrides:

decode in class javax.faces.component.UIComponentBase

encodeChildren

public void encodeChildren(javax.faces.context.FacesContext context)
                    throws java.io.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:

encodeChildren in class javax.faces.component.UIComponentBase

Throws:

java.lang.IllegalArgumentException - When there is no parent form, or when the name attribute is missing, or when the name attribute does not represent a valid script function name.

java.io.IOException

encodeFunction

protected void encodeFunction(javax.faces.context.FacesContext context,
                              java.lang.String name)
                       throws java.io.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:

java.io.IOException - When something fails at I/O level.

encodeOptions

protected void encodeOptions(javax.faces.context.FacesContext context)
                      throws java.io.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:

java.io.IOException - When something fails at I/O level.

encodeOneventOption

protected void encodeOneventOption(javax.faces.context.FacesContext context,
                                   java.lang.String onbegin,
                                   java.lang.String oncomplete)
                            throws java.io.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:

java.io.IOException - When something fails at I/O level.

resolveClientIds

protected java.lang.String resolveClientIds(javax.faces.context.FacesContext context,
                                            java.lang.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 java.lang.String getName()

Returns the script function name.

Returns:

The script function name.

setName

public void setName(java.lang.String name)

Sets the script function name.

Parameters:

name - The script function name.

getExecute

public java.lang.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(java.lang.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 java.lang.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(java.lang.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 java.lang.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(java.lang.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 java.lang.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(java.lang.String oncomplete)

Sets a script to execute after ajax response is processed.

Parameters:

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