Definition

Single Submit provides the ability to submit one component to execute in the JSF lifecycle, and is integral to the Automatic Ajax mechanism in ICEfaces 2. This means that only the specified component will decode, validate, update its bean model state, and trigger events, but a full render phase will occur. Direct-to-DOM Rendering is then used to determine the set of incremental page updates that must occur in the client browser DOM.

Comparison with Partial Submit

Single Submit is similar in intent to ICEfaces 1.8.x Partial Submit, but is an improvement which leverages JSF 2's expanded capabilities. With Partial Submit, every component in the submitted form still executes, but the other components' required properties are temporarily disabled, which allows them to pass required validation, but does not stop their validators from running, which can cause FacesMessages to be created for components which the user had not yet interacted with.

Single Submit will not cause the errant FacesMessages, as it will not execute any undesired validation. So, if the input for the submitted component are valid, then the bean model's state is guaranteed to be updated, which could not be guaranteed with Partial Submit, as another component in the form could have a validator, and cause the UpdateModel phase to not execute. Also, Single Submit is more performant, as it skips executing the undesired components, and does not manipulate required attributes on other components.

singleSubmit Attribute

In ICEfaces 2.x the feature can be controlled via a singleSubmit attribute on each of the ACE Components.

Note that as of ICEfaces 3.0, the ACE Components no longer support the singleSubmit attribute. With ICEfaces 3.x, the singleSubmit attribute has has been removed in favor of the ace:ajax tag, which provides a more JSF standard "f:ajax"-like approach to controlling form submission, component tree execution, and rendering.

In general, components can be classified by three categories: input, command, and container. Complex components may have aspects of functionality from more than one category. For the singleSubmit attribute, it has two distinct meanings, one if the component is primarily an input component, and one if it is primarily a command component. What is similar between the two, is that when singleSubmit="true", the component deviates from its default behavior such that only that component will submit and execute. The default value is false.

Input components usually have javax.faces.component.UIInput as a superclass. Examples of input components are: h:inputText, h:selectOneMenu and ace:checkboxButton. With an input component, when singleSubmit="true", changing the value of this component will submit and execute this component only. This is equivalent to having <f:ajax execute="@this" render="@all"> set inside the standard h: components. When singleSubmit="false", no submit occurs.

Command components usually have javax.faces.component.UICommand as a superclass. Examples of command components are: h:commandButon, h:commandLink and ace:pushButton. With a command component, when singleSubmit="true", triggering an action on this component will submit and execute this component only. This is equivalent to having <f:ajax execute="@this" render="@all"> set inside the standard h: components. When singleSubmit="false", triggering an action on this component will submit and execute the full form that this component is contained within.

<icecore:singleSubmit/> Tag

The <icecore:singleSubmit/> tag is a convenient and easy way to Single Submit enable standard h: components without having to litter the page with <f:ajax> tags. It allows an entire page region to be enabled at once. The behavior can be configured via the attribute submitOnBlur="true", such as <icecore:singleSubmit submitOnBlur="true" /> to cause form submission to occur on "blur" events as well as "change" events. (For example, this is necessary if "required" validation is expected to run each time a user visits a field.)

With Cancel Buttons

When making a cancel button, or any other button whose goal is to skip any form validation, avoid the UpdateModel phase, and potentially navigate to another page, the best practice has changed.  In the past, it was best to have immediate="true" and partialSubmit="true" on the cancel button, to achieve those goals. Now, it's possible, to instead use one of the above single submit mechanisms. This is better because using single submit to only execute the cancel button means that no other component will be validated or do their UpdateModel phase, since they won't be executed at all. Single submit is more efficient, and safer, as it has no edge cases, like if an input component itself has immediate="true" and uses a custom validator.

FacesMessage Caching

When JSF completes a lifecycle, it discards all of the FacesMessage objects that have been added to the FacesContext. This means that next lifecycle, any pertinent FacesMessage objects have to be re-created and re-added to the FacesContext, for h:message components to be able to display them. When doing full form submits, where every component in the form is executed, this is not a problem, as every component will get its chance to add whatever FacesMessage objects are appropriate. When doing partial executes, either because of Single Submit, or because of <f:ajax> tags, then certain portions of the view will not execute, and any FacesMessage objects they had previously added to the FacesContext will be lost. This might mislead the user to thinking that the fields they had previously interacted with, and mis-entered data in, are now valid. ICEfaces carries forward these FacesMessages, until either a full form submit and execute occurs, or until those specific components are executed again.