Single Submit

Version 21 by Ken Fyten
on Nov 13, 2014 11:28.

<< Changes from 20 to 21

compared with

Current by Arran Mccullough
on Jan 22, 2015 10:31.

Key

These lines were removed. This word was removed.

These lines were added. This word was added.

View page history

There are 4 changes. View first change.

		h1. Definition

		Single Submit provides the ability to submit one component to execute in the JSF lifecycle, and is integral to the [Automatic Ajax\|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\|Direct-to-DOM Rendering] is then used to determine the set of incremental page updates that must occur in the client browser DOM.

		h1. 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.

		h1. _singleSubmit_ Attribute

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

		{note}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\|ajax] tag, which provides a more JSF standard "f:ajax"-like approach to controlling form submission, component tree execution, and rendering.{note}

		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 _[ice:checkboxButton\|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.
		Input components usually have _javax.faces.component.UIInput_ as a superclass. Examples of input components are: _h:inputText_, _h:selectOneMenu_ and _[ace:checkboxButton\|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 _[ice:pushButton\|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.
		Command components usually have _javax.faces.component.UICommand_ as a superclass. Examples of command components are: _h:commandButon_, _h:commandLink_ and _[ace:pushButton\|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.

		h1. _<icecore:singleSubmit/>_ Tag

		The _[<icecore:singleSubmit/>\|ICECORE Components#icecoresinglesubmit]_ 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.)

		h1. 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.

		h1. 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.