- 

Available since OmniFaces 1.1

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

Historical note

Previously, the <o:form> also supported includeViewParams, but this did after all not have any advantage over the later introduced useRequestURI and includeRequestParams. Hence the includeViewParams is marked deprecated since 3.0.

Demo

First do a GET request to the current page to start using a view parameter.

Do GET request with view param

Then, do one or more POSTs in an o:form to see that the GET parameter that's been used as a view parameter in the URL is preserved.

POST-BACK o:form with includeViewParams

Now do a GET request to the current page to additionally start using GET parameters which are NOT also view parameters.

Do GET request with a view param and free GET parameters

Then, do one or more POSTs in an o:form with includeRequestParams to see that all the GET parameters are being preserverd in the URL (try to click "POST-BACK o:form with includeViewParams" to see that only the view param will be preserved).

POST-BACK o:form with includeRequestParams

Then, do one or more POSTs in an o:form with useRequestURI to see that the entire request URI, including GET parameters, is being preserverd in the URL.

POST-BACK o:form with useRequestURI

Finally, do a POST via a standard JSF h:form to see that all the GET parameter in URL disappears.

POST-BACK h:form

The value: 000

Demo source code
<f:metadata>
    <o:viewParam name="foo" value="#{viewParamBean.foo}" />
</f:metadata>

<p>
    First do a GET request to the current page to start using a view parameter.
</p>
<p>
    <h:link value="Do GET request with view param">
        <f:param name="foo" value="value" />
    </h:link>
</p>

<p>
    Then, do one or more POSTs in an o:form to see that the GET parameter that's been used as a 
    view parameter in the URL is preserved.
</p>
<o:form includeViewParams="true">
    <h:commandLink value="POST-BACK o:form with includeViewParams" />
</o:form>

<p>
    Now do a GET request to the current page to additionally start using GET parameters which are NOT 
    also view parameters.
</p>
<p>
    <h:link value="Do GET request with a view param and free GET parameters">
        <f:param name="foo" value="000" />
        <f:param name="bar" value="123" />
        <f:param name="bar" value="456" />
        <f:param name="baz" value="xxx" />
    </h:link>
</p>

<p>
    Then, do one or more POSTs in an o:form with includeRequestParams to see that all the GET parameters 
    are being preserverd in the URL (try to click "POST-BACK o:form with includeViewParams" to see that only the view 
    param will be preserved).
</p>
<o:form includeRequestParams="true">
    <h:commandLink value="POST-BACK o:form with includeRequestParams" />
</o:form>

<p>
    Then, do one or more POSTs in an o:form with useRequestURI to see that the entire request URI, including
    GET parameters, is being preserverd in the URL.
</p>
<o:form useRequestURI="true">
    <h:commandLink value="POST-BACK o:form with useRequestURI" />
</o:form>

<p>
    Finally, do a POST via a standard JSF h:form to see that all the GET parameter in URL disappears.
</p>
<h:form>
    <h:commandLink value="POST-BACK h:form" />
</h:form>

<p>
    <b>The value:</b> #{viewParamBean.foo}
</p>
Documentation & Sources

VDL documentation

API documentation

Java source code