Module org.omnifaces
Package org.omnifaces.component.input

Class Form

java.lang.Object
jakarta.faces.component.UIComponent
jakarta.faces.component.UIComponentBase
jakarta.faces.component.UIForm
jakarta.faces.component.html.HtmlForm
org.omnifaces.component.input.Form
All Implemented Interfaces:
ClientBehaviorHolder, NamingContainer, PartialStateHolder, StateHolder, TransientStateHolder, UniqueIdVendor, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener
public class Form extends HtmlForm

The <o:form> is a component that extends the standard <h:form> and submits to exactly the request URI with query string as seen in browser's address. Standard Faces <h:form> submits to the view ID and does not include any query string parameters or path parameters and may therefore fail in cases when the form is submitted to a request scoped bean which relies on the same initial query string parameters or path parameters still being present in the request URI. This is particularly useful if you're using FacesViews or forwarding everything to 1 page.

Additionally, it offers in combination with the <o:ignoreValidationFailed> tag on an UICommand component the possibility to ignore validation failures so that the invoke action phase will be executed anyway.

Since version 2.1 this component also supports adding query string parameters to the action URL via nested <f:param> and <o:param>.

Since version 3.0, it will also during ajax requests automatically send only the form data which actually need to be processed as opposed to the entire form, based on the execute attribute of any nested <f:ajax>. This feature is similar to partialSubmit feature of PrimeFaces. This will reduce the request payload when used in large forms such as editable tables.

You can use it the same way as <h:form>, you only need to change h: to o:.

Use request URI

This was available since version 1.6, but since version 3.0, this has become enabled by default. So just using <o:form> will already submit to the exact request URI with query string as seen in browser's address bar. In order to turn off this behavior, set useRequestURI attribute to false. 

 <o:form useRequestURI="false">

Include request params

When you want to include request parameters only instead of the entire request URI with query string, set the includeRequestParams attribute to true. This will implicitly set useRequestURI attribute to false. 

 <o:form includeRequestParams="true">

Partial submit

This is the default behavior. So just using <o:form> will already cause the <f:ajax> to send only the form data which actually need to be processed. In order to turn off this behavior, set partialSubmit attribute to false. 

 <o:form partialSubmit="false">

Add query string parameters to action URL

The standard UIForm doesn't support adding query string parameters to the action URL. This component offers this possibility via nested <f:param> and <o:param>. 

 <o:form>
     <f:param name="somename" value="somevalue" />
     ...
 </o:form>

The <f|o:param> will override any included view or request parameters on the same name. To conditionally add or override, use the disabled attribute of <f|o:param>.

The support was added in OmniFaces 2.2.

Ignore Validation Failed

In order to properly use the <o:ignoreValidationFailed> tag on an UICommand component, its parent <h:form> component has to be replaced by this <o:form> component. See also IgnoreValidationFailed.

Since:
1.1
Author:
Arjan Tijms, Bauke Scholtz
See Also:

  • Field Details

    • COMPONENT_TYPE

      public static final String COMPONENT_TYPE
      The component type, which is "org.omnifaces.component.input.Form".
      See Also:

  • Constructor Details

    • Form

      public Form()

  • Method Details

    • processValidators

      public void processValidators(FacesContext context)
      Overrides:
      processValidators in class UIForm

    • processUpdates

      public void processUpdates(FacesContext context)
      Overrides:
      processUpdates in class UIForm

    • encodeBegin

      public void encodeBegin(FacesContext context) throws IOException
      Overrides:
      encodeBegin in class UIComponentBase
      Throws:
      IOException

    • isIncludeRequestParams

      public boolean isIncludeRequestParams()
      Returns whether or not the request parameters should be encoded into the form's action URL.
      Returns:
      Whether or not the request parameters should be encoded into the form's action URL.
      Since:
      1.5

    • setIncludeRequestParams

      public void setIncludeRequestParams(boolean includeRequestParams)
      Set whether or not the request parameters should be encoded into the form's action URL.
      Parameters:
      includeRequestParams - Whether or not the request parameters should be encoded into the form's action URL.
      Since:
      1.5

    • isUseRequestURI

      public boolean isUseRequestURI()
      Returns whether the request URI should be used as form's action URL. Defaults to true. This setting is ignored when includeRequestParams is set to true.
      Returns:
      Whether the request URI should be used as form's action URL.
      Since:
      1.6

    • setUseRequestURI

      public void setUseRequestURI(boolean useRequestURI)
      Set whether the request URI should be used as form's action URL. This setting is ignored when includeRequestParams is set to true.
      Parameters:
      useRequestURI - Whether the request URI should be used as form's action URL.
      Since:
      1.6

    • isIgnoreValidationFailed

      public boolean isIgnoreValidationFailed()
      Returns whether or not the form should ignore validation fail (and thus proceed to update model/invoke action).
      Returns:
      Whether or not the form should ignore validation fail.
      Since:
      2.1

    • setIgnoreValidationFailed

      public void setIgnoreValidationFailed(boolean ignoreValidationFailed)
      Set whether the form should ignore validation fail.
      Parameters:
      ignoreValidationFailed - Whether the form should ignore validation fail.
      Since:
      2.1

    • isPartialSubmit

      public boolean isPartialSubmit()
      Returns whether to send only the form data which actually need to be processed as opposed to the entire form. Defaults to true.
      Returns:
      Whether to send only the form data which actually need to be processed as opposed to the entire form.
      Since:
      3.0

    • setPartialSubmit

      public void setPartialSubmit(boolean partialSubmit)
      Set whether to send only the form data which actually need to be processed as opposed to the entire form.
      Parameters:
      partialSubmit - Whether to send only the form data which actually need to be processed as opposed to the entire form.
      Since:
      3.0