o (OmniFaces VDL Documentation - Generated Documentation)

XML Declaration Syntax:

<anyxmlelement xmlns:o="http://omnifaces.org/ui"/>

Description:

OmniFaces UI components.

Tag Library Information
Info	Value
ID (tag prefix)	`o`
URI	`http://omnifaces.org/ui`

Tag Description

cache

Cache is a component that initially renders the output of its children into a buffer instead of to the response. This output is then inserted into a cache and on subsequent requests the content retrieved from the cache is used.

By default the viewid concatenated to the component id via an underscore is used as the cache key.

Note that this component does not support a cache loader and locking mechanism. This mean several simultaenous page requests may render the same content and it's undetermined which of those will end up being cached.

An optional caching provider (see below) can be set to control the caching implementation that is used for the actual caching. If no such provider is installed, a default caching implementation is used that's based on LruCache in case a maximum cache capacity is set, or on a plain ConcurrentHashMap if no capacity is set.

Setting a custom caching provider

A custom caching provider can be set by using the org.omnifaces.CACHE_PROVIDER context parameter in web.xml to point to an implementation of org.omnifaces.component.output.cache.CacheProvider. For example:

<context-param>
    <param-name>org.omnifaces.CACHE_PROVIDER</param-name>
    <param-value>com.example.MyProvider</param-value>
</context-param>

The default provider, org.omnifaces.component.output.cache.DefaultCacheProvider can be used as an example.

Global settings

For the default provider, the maximum capacity and the default time to live can be specified for the supported scopes "session" and "application". If the maximum capacity is reached, an entry will be evicted following a least recently used policy. The default time to live specifies for how long entries are considered to be valid. A value for the time attribute on this component will override this global default time to live. The following context parameters can be used in web.xml:

`org.omnifaces.CACHE_SETTING_APPLICATION_MAX_CAPACITY`	Sets the maximum number of elements that will be stored per web module (application scope). Default: no limit
`org.omnifaces.CACHE_SETTING_SESSION_MAX_CAPACITY`	Sets the maximum number of elements that will be stored per session. Default: no limit
`org.omnifaces.CACHE_SETTING_APPLICATION_TTL`	Sets the maximum amount of time in seconds that cached content is valid for the application scope. Can be overriden by individal cache components. Default: no limit
`org.omnifaces.CACHE_SETTING_SESSION_TTL`	Sets the maximum amount of time in seconds that cached content is valid for the session scope. Can be overriden by individal cache components. Default: no limit
`org.omnifaces.CACHE_INSTALL_BUFFER_FILTER`	Boolean that when true installs a Servlet Filter (Servlet 3.0+ only) that works in conjunction with the `useBuffer` attribute of the Cache component to enable an alternative way to grab the content that needs to be cached. This is a convenience setting that is a short-cut for installing the `org.omnifaces.servlet.BufferedHttpServletResponse` filter manually. If more finegrained control is needed regarding which place in the filter chain the filter appears and which resources it exactly filters, this setting should not be used and the mentioned filter should be manually configured. Default: `false`)

cacheValue

Tag handler (runs at tree build-time) that makes a value expression available under the given name that caches its value. Although the value expressions scope is that of the entire Facelet in which this tag appears, the value it self is cached using the parent Cache component.

This means that if the parent o:Cache component clears its cache (e.g. because of time to live expiration), the value cached by this value expression will be automatically cleared as well.

The direct parent of this component MUST be o:Cache or a potential subclass of the associated UIComponent. It's an error to have any other kind of parent.

The intended use of this is to explicitly cache a value expression that is used by one of the component children of o:Cache, so that even after a post-back (where the cached markup is of nu use) the original value expression will not be re-evaluated.

commandScript

CommandScript is an extension to <h:commandXxx> which generates a JavaScript function in the global JavaScript scope which allows the enduser to execute a JSF ajax request by a just function call functionName() in the JavaScript context.

The <o:commandScript> component is required to be enclosed in an 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

componentIdParam

ComponentIdParam is a component that allows component ids to be provided as request parameters causing only components with matching ids to be rendered.

Both simple component ids as well as client ids are supported. Components can be rendered without their parents having to be rendered. As such, e.g. single rows appearing in a table can be rendered without any of the surrounding markup appearing in the response.

The intended usage of this component is to allow client-side scripts to request markup for specific components via a GET request (as opposed to AJAX based post-backs).

This component is used in the same way view parameters are and needs to be put into the metadata section of a Facelet.

conditionalComment

o:conditionalComment is an UIComponent which renders a conditional comment. Conditional comments are an IE specific feature which enables the developer to (out)comment blocks of HTML depending on whether the client is using IE and if so even which version. They are often seen in combination with CSS stylesheets like so:

<!--[if lte IE 7]>
  <link rel="stylesheet" href="ie6-ie7.css" />
<![endif]-->

However, Facelets renders them HTML-escaped and if jakarta.faces.FACELETS_SKIP_COMMENTS context param is set to true then it will even not be rendered at all. You would need to workaround this with an ugly <h:outputText escape="false">.

<h:outputText value="&lt;!--[if lte IE 7]&gt;&lt;link rel=&quot;stylesheet&quot; href=&quot;ie6-ie7.css&quot; /&gt;&lt;![endif]--&gt;" escape="false" />

This component is designed to solve this problem.

<o:conditionalComment if="lte IE 7">
  <link rel="stylesheet" href="ie6-ie7.css" />
</o:conditionalComment>

Note that you cannot use this with <h:outputStylesheet> as it would implicitly be relocated as direct child of <h:head>.

converter

The <o:converter> basically extends the <f:converter> tag family with the possibility to evaluate the value expression in all attributes on a per request basis instead of on a per view build time basis. This allows the developer to change the attributes on a per request basis.

When you specify for example the standard <f:convertDateTime> by converterId="jakarta.faces.DateTime", then you'll be able to use all its attribuces such as pattern and locale as per its documentation, but then with the possibility to supply request based value expressions.

<o:converter converterId="jakarta.faces.DateTime" pattern="#{item.pattern}" locale="#{item.locale}" />

criticalStylesheet CriticalStylesheet is a component which renders a <link rel="preload" as="style"> instead of <link rel="stylesheet">.

deferredScript

DeferredScript is a component which defers the loading of the given script resource to the window load event. In other words, the given script resource is only loaded when the window is really finished with loading. So, the enduser can start working with the webpage without waiting for the additional scripts to be loaded. Usually, it are those kind of scripts which are just for progressive enhancement and thus not essential for the functioning of the webpage.

This will give bonus points with among others the Google PageSpeed tool, on the contrary to placing the script at bottom of body, or using defer="true" or even async="true".

enableRestorableView

The <o:enableRestorableView> instructs the view handler to recreate the entire view whenever the view has been expired, i.e. whenever #restoreView(FacesContext, String) returns null and the current request is a postback. This effectively prevents ViewExpiredException on the view. This tag needs to be placed in <f:metadata> of the view.

There are however technical design limitations: please consult the javadoc for details. To the point, the bean associated with the view has to be exclusively request scoped in order to properly recreate the same view.

form Form is a component that extends the standard UIForm and submits by default to current request URI with query string and 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. It also supports adding custom query string parameters via a nested <o|h:param>.

genericEnumConverter Automatically detects enum type in generic collections. See GenericEnumConverter showcase.

graphicImage The <o:graphicImage> is a component that extends the standard <h:graphicImage> with support for referencing an InputStream or byte[] property in value attribute. This property must point to a stateless @ApplicationScoped bean (both JSF and CDI scopes are supported).

hashParam

The <o:hashParam> is a component that extends the standard <f:viewParam> with support for setting hash query parameter values in bean and automatically reflecting updated model values in hash query string.

The "hash query string" is the part in URL after the # which could be formatted in the same format as a regular request query string (the part in URL after the ?). An example:

https://example.com/page.xhtml#foo=baz&bar=kaz

This specific part of the URL (also called hash fragment identifier) is by default not sent to the server. This component will on page load send it anyway and on every ajax request update the hash query string in client side when the model value has changed in server side. *

Usage

It's very similar to the <o:viewParam>.

<f:metadata>
    <o:hashParam name="foo" value="#{bean.foo}" />
    <o:hashParam name="bar" value="#{bean.bar}" />
</f:metadata>

This only requires that the JSF page has at least one {@link UIForm} component, such as <h:form> or <o:form>, otherwise the <o:hashParam> won't be able to fire the ajax request which sets the with hash query parameter values in bean. In such case an error will be printed to JS console when the project stage is Development.

You can use the render attribute to declare which components should be updated when a hash parameter value is present.

<f:metadata>
    <o:hashParam name="foo" value="#{bean.foo}" render="fooResult" />
    <o:hashParam name="bar" value="#{bean.bar}" />
</f:metadata>
...
<h:body>
    ...
    <h:panelGroup id="fooResult">
        ...
    </h:panelGroup>
    ...
</h:body>

You can use the default attribute to declare a non-null value which should be interpreted as the default value. In other words, when the current model value matches the default value, then the hash parameter will be removed.

<f:metadata>
    <o:hashParam name="foo" value="#{bean.foo}" />
    <o:hashParam name="bar" value="#{bean.bar}" default="kaz" />
</f:metadata>

When #{bean.foo} is "baz" and #{bean.bar} is "kaz" or empty, then the reflected hash query string will become https://example.com/page.xhtml#foo=baz. If #{bean.bar} is any other value, then it will appear in the hash query string.

highlight

o:highlight is a helper component which highlights all invalid UIInput components and the associated labels by adding an error style class to them. Additionally, it by default focuses the first invalid UIInput component. The <o:highlight /> component can be placed anywhere in the view, as long as there's only one of it. Preferably put it somewhere in the master template for forms.

<h:form>
  <h:inputText value="#{bean.input1}" required="true" />
  <h:inputText value="#{bean.input1}" required="true" />
  <h:commandButton value="Submit" action="#{bean.submit}" />
</h:form>
<o:highlight />

The default error style class name is error. You need to specify a CSS style associated with the class yourself. For example,

label.error {
  color: #f00;
}
input.error, select.error, textarea.error {
  background-color: #fee;
}

You can override the default error style class by the styleClass attribute:

<o:highlight styleClass="invalid" />

You can disable the default focus on the first invalid input element setting the focus attribute.

<o:highlight styleClass="invalid" focus="false" />

ignoreValidationFailed

The <o:ignoreValidationFailed> allows the developer to ignore validation failures when executing an UICommand action. This taghandler must be placed inside an UICommand component and the parent UIForm must be an <o:form>.

Any validation errors will be ignored and thus not be displayed. Note that the model values will (obviously) only be updated for components which have passed the validation.

implicitNumberConverter Extends NumberConverter to automatically drop/imply currency and percent symbol. See ImplicitNumberConverter showcase.

importConstants

The <o:importConstants> allows the developer to have a mapping of all constant field values of the given type in the request scope. The constant field values are those public static final fields. This works for classes, interfaces and enums. For example:

public class Foo {
    public static final String FOO1 = "foo1";
    public static final String FOO2 = "foo2";
}

public interface Bar {
    public static final String BAR1 = "bar1";
    public static final String BAR2 = "bar2";
}

public enum Baz {
    BAZ1, BAZ2;
}

The constant field values of the above types can be mapped into the request scope as follows:

<o:importConstants type="com.example.Foo" />
<o:importConstants type="com.example.Bar" />
<o:importConstants type="com.example.Baz" var="Bazzz" />
...
#{Foo.FOO1}, #{Foo.FOO2}, #{Bar.BAR1}, #{Bar.BAR2}, #{Bazzz.BAZ1}, #{Bazzz.BAZ2}

The map is by default stored in the request scope by the simple name of the type as variable name. You can override this by explicitly specifying the var attribute, as demonstrated for com.example.Baz in the above example.

The resolved constants are by reference stored in the cache to improve retrieving performance.

importFunctions

The <o:importFunctions> allows the developer to have access to all functions of the given fully qualified name of a type in the Facelet scope using the usual EL functions syntax without the need to register them in .taglib.xml file. The functions are those public static methods with a non-void return type. For example:

<o:importFunctions type="java.lang.Math" var="m" />
<o:importFunctions type="org.omnifaces.util.Faces" />
...
#{m:abs(-10)}
#{m:max(bean.number1, bean.number2)}
...
<base href="#{Faces:getRequestBaseURL()}" />

The functions prefix becomes by default the simple name of the type. You can override this by explicitly specifying the var attribute. If there are multiple function methods with exactly the same name, then the one with the least amount of parameters will be used. If there are multiple function methods with exactly the same name and amount of parameters, then the choice is unspecified (technically, JVM-dependent) and should not be relied upon. So if you absolutely need to differentiate functions in such case, give them each a different name.

Note that the colon : operator to invoke the method is as required by EL functions spec. It's by design not easily possible to change it to the period . operator. Also note that in case of org.omnifaces.util.Faces it's considered poor practice if the same functionality is already available through the implicit EL variables #{facesContext}, #{view}, #{request}, etc such as #{request.contextPath} which should be preferred over #{Faces:getRequestContextPath()}.

The resolved functions are by reference stored in the cache to improve retrieving performance.

inputFile The <o:inputFile> is a component that extends the standard <h:inputFile> and adds support for multiple, directory, accept and maxsize attributes, along with built-in server side validation on accept and maxsize attributes. Additionally, it makes sure that the value of HTML file input element is never rendered. The standard <h:inputFile> renders Part#toString() to it which is unnecessary.

inputHidden The <o:inputHidden> is a component that extends the standard <h:inputHidden> and changes the behavior to immediately convert, validate and update during apply request values phase, regardless of any conversion/validation errors on other UIInput components within the same form. The standard <h:inputHidden> follows the same lifecycle as other UIInput components which is in the end unintuive as hidden input fields are usually under control of the developer.

link The <o:link> is a component that extends the standard <h:link> and allows including the request query string parameters of the current URL into the link's target URL. Standard Faces <h:link> does not include any query string parameters which are not declared as view parameters. This is particularly useful if you expect some state in the target page and don't want to repeat <f|o:param> all over place.

listConverter Automatically converts based on toString() of given list items. See ListConverter showcase.

listIndexConverter Automatically converts based on index of given list items. See ListIndexConverter showcase.

loadBundle

The <o:loadBundle> taghandler basically extends the standard <f:loadBundle> with a new loader attribute allowing you to explicitly set the desired {@link ClassLoader} where the resource bundle should be looked up. Also the {@link Locale} of the bundle is obtained with better default values than the default Faces implementation.

You can use the loader attribute to specify an object whose class loader will be used to load the resource bundle specified in the basename attribute. The class loader of the given object is resolved as specified in {@link Utils#getClassLoader(Object)}. In the end this should allow you to use a more specific resource bundle when there are duplicate instances in the runtime classpath, e.g. via multiple (plugin) libraries.

The locale of the resource bundle is obtained as specified in {@link Faces#getLocale()}.

Usage

You can use it the same way as <f:loadBundle>, you only need to change f: into o: to get the extra support for loader attribute and the improved locale resolving.

massAttribute

The <o:massAttribute> sets an attribute of the given name and value on all nested components, if they don't already have an attribute set. On boolean attributes like disabled, readonly and rendered, any literal (static) attribute value will be ignored and overridden. Only if they have already a value expression #{...} as attribute value, then it won't be overridden. This is a technical limitation specifically for boolean attributes as they don't default to null.

For example, the following setup

<o:massAttribute name="disabled" value="true">
    <h:inputText id="input1" />
    <h:inputText id="input2" disabled="true" />
    <h:inputText id="input3" disabled="false" />
    <h:inputText id="input4" disabled="#{true}" />
    <h:inputText id="input5" disabled="#{false}" />
</o:massAttribute>

will set the disabled="true" attribute in input1, input2 and input3 as those are the only components without a value expression on the boolean attribute.

As another general example without booleans, the following setup

<o:massAttribute name="styleClass" value="#{component.valid ? '' : 'error'}">
    <h:inputText id="input1" />
    <h:inputText id="input2" styleClass="some" />
    <h:inputText id="input3" styleClass="#{'some'}" />
    <h:inputText id="input4" styleClass="#{null}" />
</o:massAttribute>

will only set the styleClass="#{component.valid ? '' : 'error'}" attribute in input1 as that's the only component on which the attribute is absent. Do note that the specified EL expression will actually be evaluated on a per-component basis.

To target a specific component (super)class, use the target attribute. The example below skips labels (as that would otherwise fail in the example below because they don't have a valid property):

<o:massAttribute name="styleClass" value="#{component.valid ? '' : 'error'}" target="jakarta.faces.component.UIInput">
    <h:outputLabel for="input1" />
    <h:inputText id="input1" />
    <h:outputLabel for="input2" />
    <h:inputText id="input2" />
    <h:outputLabel for="input3" />
    <h:inputText id="input3" />
</o:massAttribute>

messages

The <o:messages> is a component that extends the standard <h:messages> with the following new features:

Multiple for components

Possibility to specify multiple client IDs space separated in the for attribute. The example below would only display messages for input1 and input3:


<h:form>
  <o:messages for="input1 input3" />
  <h:inputText id="input1" />
  <h:inputText id="input2" />
  <h:inputText id="input3" />
  <h:inputText id="input4" />
</h:form>

It can even refer non-input components which in turn contains input components. The example below would only display messages for input1 and input2:


<h:form>
  <o:messages for="inputs" />
  <h:panelGroup id="inputs">
    <h:inputText id="input1" />
    <h:inputText id="input2" />
  </h:panelGroup>
  <h:inputText id="input3" />
  <h:inputText id="input4" />
</h:form>

You can even combine them. The example below would only display messages for input1, input2 and input4.


<h:form>
  <o:messages for="inputs input4" />
  <h:panelGroup id="inputs">
    <h:inputText id="input1" />
    <h:inputText id="input2" />
  </h:panelGroup>
  <h:inputText id="input3" />
  <h:inputText id="input4" />
</h:form>

Displaying single message

Show a single custom message whenever the component has received any faces message. This is particularly useful when you want to display a global message in case any of the in for specified components has a faces message. For example:


<o:messages for="form" message="There are validation errors. Please fix them." />
<h:form id="form">
  <h:inputText id="input1" /><h:message for="input1" />
  <h:inputText id="input2" /><h:message for="input2" />
  <h:inputText id="input3" /><h:message for="input3" />
</h:form>

HTML escaping

Control HTML escaping by the new escape attribute.


<o:messages escape="false" />

Beware of potential XSS attack holes when user-controlled input is redisplayed through messages!

Iteration markup control

Control iteration markup fully by the new var attribute which sets the current FacesMessage in the request scope and disables the default table/list rendering. For example,


<dl>
  <o:messages var="message">
    <dt>#{message.severity}</dt>
    <dd title="#{message.detail}">#{message.summary}</dd>
  </o:messages>
</dl>

Note: the iteration is by design completely stateless. It's therefore not recommended to nest form components inside the <o:messages> component. It should be used for pure output only, like as the standard <h:messages>. Plain output links are however no problem. Also note that the message and escape attributes have in this case no effect. With a single message, there's no point of iteration. As to escaping, just use <h:outputText escape="false"> the usual way.

Design notice: the component class is named OmniMessages instead of Messages to avoid confusion with the Messages utility class.

methodParam

o:methodParam is a tag handler that can be used to pass a method expression into a Facelets tag.

By default this is not possible, and the expression that's intended to be a method expression will be created and made available as a value expression. This handler should be placed inside a Facelets tag as follows:

<ui:composition
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ui="http://xmlns.jcp.org/jsf/facelets"
    xmlns:h="http://xmlns.jcp.org/jsf/html"
    xmlns:o="http://omnifaces.org/ui"
>
    <o:methodParam name="method" value="#{action}"/>

    <h:commandButton value="test" action="#{method}" />

</ui:composition>

Assuming the above is a tag called actionmethod in the namespace test, a method can be passed into it as follows:

<test:actionmethod action="#{methodParamBean.doAction}" />

In case a method with no parameters is passed that is to be used as an action listener with no parameters, then the component using this method unfortunely has to be wrapped by a component that puts the method in request scoped (with nested visibility), e.g. by using ui:repeat as follows:

<ui:repeat var="method" value="#{method}">
    <h:commandButton value="test" actionListener="#{method}" />
</ui:repeat>

Using modern EL implementations, this is not needed in case the EL expression references the method using explicit parenthesis, e.g. #{methodParamBean.doAction()}

moveComponent MoveComponent is a utility component via which a components and behaviors can be moved to a target component at various ways.

onloadScript

o:onloadScript is an extension to <h:outputScript> which will be executed in the end of the HTML body (thus when all HTML elements are initialized in the HTML DOM tree) and will re-execute its script body on every ajax request. This is particularly useful if you want to re-execute a specific helper script to manipulate the HTML DOM tree, such as (re-)adding fancy tooltips, performing highlights, etcetera, also after changes in the HTML DOM tree on ajax responses.

You can put it anywhere in the view, it will always be relocated to the end of body.

<o:onloadScript>alert('OnloadScript is invoked!');</o:onloadScript>

outputFormat OutputFormat is a component that extends the standard HtmlOutputFormat and provides support for capturing the output and exposing it into the request scope by the variable name as specified by the var attribute.

outputLabel

o:outputLabel is a component that extends the standard outputLabel and provides extra support for automatically setting its value as the label of the component identified by its for attribute.

It renders an HTML "label" element. If a "for" attribute is specified, the component specified by the value of the "for" attribute is queried for its client id, which is then rendered as the value of the "for" attribute of the HTML label element.

param

Param is a component that extends the standard UIParameter to implement ValueHolder and thus support a Converter to convert the supplied value to string, if necessary.

You can use it the same way as <f:param>, you only need to change f: into o: to get the extra support for a Converter by usual means via the converter attribute of the tag, or the nested <f:converter> tag, or just automatically if a converter is already registered for the target class. Also, if no value is specified, but children are present, then the encoded output of children will be returned as value. This is useful when you want to supply JSF components or HTML as parameter of an unescaped <h:outputFormat>. For example,

                <h:outputFormat value="#{bundle.paragraph}" escape="false">
                  <o:param><h:link outcome="contact" value="#{bundle.contact}" /></o:param>
                </h:outputFormat>

with this bundle

                paragraph = Please {0} for more information.
                contact = contact us

will result in the link being actually encoded as output format parameter value.

pathParam

The PathParam is a component that extends the OmniFaces Param to support MultiViews feature of FacesViews. It is done by rendering the supplied parameters of such components as <h:link> and <h:button> among others as path parameters and not as query parameters as otherwise will be produced by <o:param> and <f:param> tags.

The component has built-in support for a Converter to convert the supplied value to string by usual means via the converter attribute of the tag, or the nested <f:converter> tag, or just automatically if a converter is already registered for the target class via @FacesConverter(forClass).

This component doesn't support returning encoded output of its children as parameter value in case no value is present. This feature is provided by Param component instead.

Also, the name attribute must not be specified for this component as it already evaluates to a predefined one.

This component is used to create bookmarkable URLs via standard outcome target components that take into account <o:pathParam> tags nested in the components. The path parameters will be rendered in the order they were declared for a view id that is defined as a multi view and if the view was not defined as a multi view then they won't be rendered at all. Additionally, declaring path parameters for a non-multi view will be logged as a warning and a faces warning message will be added for any stage different from Production.

In the following example the link to the multi view page will be rendered with two path parameters:

<h:link value="Link" outcome="multiview-supported-path">
    <o:pathParam value="first" />
    <o:pathParam value="second" />
</h:link>

The code above will be rendered as: <a id="..." name="..." href="/context-path/multiview-supported-path/first/second">Link</a>. The path parameters will be available via @Inject @Param(pathIndex=0) private String first; and @Inject @Param(pathIndex=1) private String second; the usual way.

requiredCheckboxValidator Validates whether checkbox is checked. See RequiredCheckboxValidator showcase.

resolveComponent ResolveComponent is a utility component via which a component can be looked up by its ID and a reference to it put in either the "facelet scope" (default) or the request scope.

resourceInclude This component includes the output from a resource located at the given path. This path can not extend outside of the current Servlet context. A resource is either a Servlet or a JSP page.

scriptParam

The <o:scriptParam> is a component that extends the standard <f:viewParam> with support for setting results of client-side evaluated JavaScript code in bean.

Usage

It's similar to the <f:viewParam>.

<f:metadata>
    <o:scriptParam script="new Date().getTimezoneOffset()" value="#{bean.clientTimeZoneOffset}" />
    <o:scriptParam script="window.screen.width" value="#{bean.clientScreenWidth}" />
    <o:scriptParam script="someFunctionName()" value="#{bean.resultOfSomeFunctionName}" />
</f:metadata>

You can use the render attribute to declare which components should be updated when a script parameter has been set.

<f:metadata>
    <o:scriptParam script="foo()" value="#{bean.resultOfFoo}" render="fooResult" />
</f:metadata>
...
<h:body>
    ...
    <h:panelGroup id="fooResult">
        <ui:fragment rendered="#{not empty bean.resultOfFoo}">
            The result of foo() script is: #{bean.resultOfFoo}
        </ui:fragment>
    </h:panelGroup>
    ...
</h:body>

Note that as it extends from the standard <f:viewParam>, its built-in conversion and validation functionality is also supported on this component. So, the following is also possible:

<f:metadata>
    <o:scriptParam script="window.navigator" value="#{bean.clientNavigator}" />
</f:metadata>

With a clientNavigator being an instance of jakarta.json.JsonObject:

private JsonObject clientNavigator;

And this converter:

package com.example;

import java.io.StringReader;
import jakarta.faces.component.UIComponent;
import jakarta.faces.context.FacesContext;
import jakarta.faces.convert.Converter;
import jakarta.faces.convert.ConverterException;
import jakarta.faces.convert.FacesConverter;
import jakarta.json.Json;
import jakarta.json.JsonObject;

@FacesConverter(forClass = JsonObject.class)
public class JsobObjectConverter implements Converter<JsonObject> {

    @Override
    public String getAsString(FacesContext context, UIComponent component, JsonObject modelValue) {
        if (modelValue == null) {
            return "";
        }

        return modelValue.toString();
    }

    @Override
    public JsonObject getAsObject(FacesContext context, UIComponent component, String submittedValue) {
        if (submittedValue == null || submittedValue.isEmpty()) {
            return null;
        }

        try {
            return Json.createReader(new StringReader(submittedValue)).readObject();
        }
        catch (Exception e) {
            throw new ConverterException("Not a valid JSON object", e);
        }
    }
}

selectItemGroups

The o:selectItemGroups is an extension of {@link UISelectItems} which allows you to iterate over a nested collection representing groups of select items. This is the {@link UIComponent} counterpart of jakarta.faces.model.SelectItemGroup. There is no equivalent (yet) in the standard JSF API. Currently the only way to represent {@link SelectItemGroup} in UI is to manually create and populate them in a backing bean which can end up to be quite verbose.

Below example assumes a List<Category> as value wherein Category in turn has a List<Product>.

<h:selectOneMenu value="#{bean.selectedProduct}" converter="omnifaces.SelectItemsConverter">
    <f:selectItem itemValue="#{null}" />
    <o:selectItemGroups value="#{bean.categories}" var="category" itemLabel="#{category.name}">
        <f:selectItems value="#{category.products}" var="product" itemLabel="#{product.name}" />
    </o:selectItemGroups>
</h:selectOneMenu>

selectItemsConverter Automatically converts based on toString() of UISelectItem(s) entries. See SelectItemsConverter showcase.

selectItemsIndexConverter Automatically converts based on index of UISelectItem(s) entries.See SelectItemsIndexConverter showcase.

sitemapUrl The <o:sitemapUrl> is a component which renders the given target URL or JSF view ID as a sitemap URL with support for adding additional query string parameters to the URL via nested <f:param> and <o:param>.

skipValidators

The <o:skipValidators> allows the developer to skip validators when executing a submit. This taghandler must be placed inside the component that invokes the submit, may be an UICommand (both ajaxified or not) as well as any ClientBehaviorHolder (ajax enabled) component.

Validation will happen, but no validator will be executed since they will be temporary detached from processed components. Conversion errors could still occur. Note that the model values will be updated for all processed components.

socket

o:socket opens an one-way (server to client) web socket based push conntection in client side which can be reached from server side via org.omnifaces.cdi.PushContext interface injected in any CDI/container managed artifact via org.omnifaces.cdi.Push annotation.

For detailed usage instructions, see org.omnifaces.cdi.push.Socket javadoc.

tagAttribute Declare a tagfile attribute. This should in nested tags shield same attributes set on parent tags. This also offers the possibility to declare a default value.

toCollectionConverter Automatically converts between String and Collection based on delimiter. See ToCollectionConverter showcase.

toLowerCaseConverter Automatically lower cases entire String. See ToLowerCaseConverter showcase.

toUpperCaseConverter Automatically upper cases entire String. See ToUpperCaseConverter showcase.

tree

The <o:tree> allows the developers to have full control over the markup of a tree hierarchy by declaring the appropriate JSF components or HTML elements in the markup. The <o:tree> does namely not render any HTML markup by itself.

The component value must point to a tree of data objects represented by a TreeModel instance, typically established via a ValueExpression. During iterative processing over the nodes of tree in the tree model, the object for the current node is exposed as a request attribute under the key specified by the var attribute. The node itself is exposed as a request attribute under the key specified by the varNode attribute.

The <o:tree> tag supports only child tags of type <o:treeNode>, representing parent tree nodes. There can be multiple <o:treeNode> tags, each representing a separate parent tree node level, so that different markup could be declared for each tree node level, if necessary. The <o:treeNode> tag in turn supports child tag <o:treeNodeItem> which represents each child of the current parent tree node. The <o:treeNodeItem> in turn supports child tag <o:treeInsertChildren> which represents the insertion point of the grand children.

Here is a basic usage example where each parent tree node level is treated the same way via a single <o:treeNode>:

<o:tree value="#{bean.treeModel}" var="item" varNode="node">
  <o:treeNode>
    <ul>
      <o:treeNodeItem>
        <li>
          #{node.index} #{item.someProperty}
          <o:treeInsertChildren />
        </li>
      </o:treeNodeItem>
    </ul>
  </o:treeNode>
</o:tree>

treeInsertChildren The <o:treeInsertChildren> represents the insertion point for the grand children. This is in turn further interpreted as <o:treeNode>.

treeNode

The <o:treeNode> represents the parent tree node. Within this component, the var attribute of the <o:tree> will expose the parent tree node. Each of its children is processed by <o:treeNodeItem> on which the var attribute of the <o:tree> in turn exposes each child of the parent tree node.

The optional level attribute can be used to specify for which tree node level as obtained by TreeModel#getLevel() the <o:treeNode> should be rendered. The root tree node has level 0. If the level attribute is unspecified, then the <o:treeNode> will be rendered for any tree node level which hasn't already a <o:treeNode level="x"> specified.

treeNodeItem

The <o:treeNodeItem> represents the child item of the parent tree note as represented by <o:treeNode>. Within this component, the var attribute of the parent <o:tree> component will expose the child tree node.

Within <o:treeNodeItem> you can use <o:treeInsertChildren> to declare the place where to recursively render the <o:treeNode> whereby the current child item is in turn interpreted as a parent tree node (i.e. where you'd like to insert the grand-children).

trimConverter Automatically trims entire String. See TrimConverter showcase.

url The <o:url> is a component which renders the given target URL or JSF view ID as a bookmarkable URL with support for adding additional query string parameters to the URL via nested <f:param> and <o:param>, and for exposing it into the request scope by the variable name as specified by the var attribute instead of rendering it.

validateAll

o:validateAll validates validates if ALL of the given UIInput components have been filled out. The default message is

{0}: Please fill out all of those fields

General usage of all multiple field validators

This validator must be placed inside the same UIForm as the UIInput components in question. The UIInput components must be referenced by a space separated collection of their client IDs in the components attribute. This validator can be placed anywhere in the form, but keep in mind that the components will be validated in the order as they appear in the form. So if this validator is been placed before all of the components, then it will be executed before any of the component's own validators. If this validator fails, then the component's own validators will not be fired. If this validator is been placed after all of the components, then it will be executed after any of the component's own validators. If any of them fails, then this validator will not be exeucted. It is not recommended to put this validator somewhere in between the referenced components as the resulting behaviour may be confusing. Put this validator either before or after all of the components, depending on how you would like to prioritize the validation.

<o:validateMultipleFields id="myId" components="foo bar baz" />
<h:message for="myId" />
<h:inputText id="foo" />
<h:inputText id="bar" />
<h:inputText id="baz" />

By default, in an invalidating case, all of the referenced components will be marked invalid and a faces message will be added on the client ID of this validator component. The default message can be changed by the message attribute. Any "{0}" placeholder in the message will be substituted with a comma separated string of labels of the referenced input components.

<o:validateMultipleFields components="foo bar baz" message="{0} are wrong!" />

You can use invalidateAll="false" to mark only those components which are actually invalid as invalid. In case of for example "input all" or "input all or none" validation, that would be only the fields which are left empty.

<o:validateMultipleFields components="foo bar baz" message="{0} are wrong!" invalidateAll="false" />

The faces message can also be shown for all of the referenced components using showMessageFor="@all".

<o:validateMultipleFields components="foo bar baz" message="This is wrong!" showMessageFor="@all" />
<h:inputText id="foo" />
<h:message for="foo" />
<h:inputText id="bar" />
<h:message for="bar" />
<h:inputText id="baz" />
<h:message for="baz" />

The faces message can also be shown for only the invalidated components using showMessageFor="@invalid".

<o:validateMultipleFields components="foo bar baz" message="This is wrong!" showMessageFor="@invalid" />

The faces message can also be shown as global message using showMessageFor="@global".

<o:validateMultipleFields components="foo bar baz" message="This is wrong!" showMessageFor="@global" />

The faces message can also be shown for specific components referenced by a space separated collection of their client IDs in showMessageFor attribute.

<o:validateMultipleFields components="foo bar baz" message="This is wrong!" showMessageFor="foo baz" />

The showMessageFor attribute defaults to @this.

The validator can be disabled by the disabled attribute. It accepts a request based EL expression.

<o:validateMultipleFields components="foo bar baz" disabled="#{param.validationDisabled}" />

There is a read-only validationFailed attribute which can be used to determine if the validation by this component has failed.

<o:validateMultipleFields id="myId" binding="#{myId}" components="foo bar baz" />
<h:panelGroup rendered="#{myId.validationFailed}">
    Validation has failed! <h:message for="myId" />
</h:panelGroup>

validateAllOrNone

o:validateAllOrNone validates validates if at least ALL of the given UIInput components have been filled out or that NONE of the given UIInput components have been filled out. The default message is

{0}: Please fill out all or none of those fields

For general usage instructions, refer validateAll tag documentation.

validateBean

The <o:validateBean> allows the developer to control bean validation groups on a per-UICommand or UIInput component basis. Usage example:

<h:commandButton>
    <o:validateBean groups="jakarta.validation.groups.Default,com.example.MyGroup"/>
</h:commandButton>

validateEqual

o:validateEqual validates if ALL of the given UIInput components have the same value. The default message is

{0}: Please fill out the same value for all of those fields

For general usage instructions, refer validateAll tag documentation. The invalidateAll attribute has no effect on this component and is therefore not listed.

validateMultiple

ValidateMultiple allows the developer to validate multiple fields by a custom validator method:

<o:validateMultiple id="myId" components="foo bar baz" validator="#{bean.validateValues}" />
<h:message for="myId" />
<h:inputText id="foo" />
<h:inputText id="bar" />
<h:inputText id="baz" />

public boolean validateValues(FacesContext context, List<UIInput> components, List<Object> values) {
    // ...
}

Or by a managed bean instance which implements the MultiFieldValidator interface:

<o:validateMultiple id="myId" components="foo bar baz" validator="#{validateValuesBean}" />
<h:message for="myId" />
<h:inputText id="foo" />
<h:inputText id="bar" />
<h:inputText id="baz" />

@ManagedBean
@RequestScoped
public class ValidateValuesBean implements MultiFieldValidator {
    @Override
    boolean validateValues(FacesContext context, List<UIInput> components, List<Object> values) {
        // ...
    }
}

validateOne

o:validateOne validates if ONLY ONE of the given UIInput components has been filled out. The default message is

{0}: Please fill out only one of those fields

For general usage instructions, refer validateAll tag documentation. The invalidateAll attribute has no effect on this component and is therefore not listed.

validateOneOrMore

o:validateOneOrMore validates if at least ONE of the given UIInput components has been filled out. The default message is

{0}: Please fill out at least one of those fields

For general usage instructions, refer validateAll tag documentation. The invalidateAll attribute has no effect on this component and is therefore not listed.

validateOneOrNone

o:validateOneOrNone validates if ONLY ONE of the given UIInput components has been filled out or that NONE of the given UIInput components have been filled out. The default message is

{0}: Please fill out only one or none of those fields

For general usage instructions, refer validateAll tag documentation. The invalidateAll attribute has no effect on this component and is therefore not listed.

validateOrder

ValidateOrder validates if the values of the given UIInput components as specified in the components attribute are in the order as specified by the type attribute which accepts the following values:

lt (default): from least to greatest, without duplicates.
lte: from least to greatest, allowing duplicates (equal values next to each other).
gt: from greatest to least, without duplicates.
gte: from greatest to least, allowing duplicates (equal values next to each other).

The default message is

{0}: Please fill out the values of all those fields in order

For general usage instructions, refer validateAll tag documentation. The invalidateAll attribute has no effect on this component and is therefore not listed.

This validator has the additional requirement that the to-be-validated values must implement Comparable. This validator throws an IllegalArgumentException when one or more of the values do not implement it.

validateUnique

o:validateUnique validates if ALL of the given UIInput components have an unique value. The default message is

{0}: Please fill out an unique value for all of those fields

For general usage instructions, refer validateAll tag documentation. The invalidateAll attribute has no effect on this component and is therefore not listed.

validateUniqueColumn

ValidateUniqueColumn validates if the given UIInput component in an UIData component has an unique value throughout all rows, also those not visible by pagination. This validator works directly on the data model and may therefore not work as expected if the data model does not represent all available rows of the UIData component (e.g. when there's means of lazy loading).

The default message is

{0}: Please fill out an unique value for the entire column. Duplicate found in row {1}

Usage example:

<h:dataTable value="#{bean.items}" var="item">
  <h:column>
    <h:inputText value="#{item.value}">
      <o:validateUniqueColumn />
    </h:inputText>
  </h:column>
</h:dataTable>

In an invalidating case, only the first row on which the value is actually changed (i.e. the value change event has been fired on the input component in the particular row) will be marked invalid and a faces message will be added on the client ID of the input component in the particular row. The default message can be changed by the message attribute. Any "{0}" placeholder in the message will be substituted with the label of the input component. Any "{1}" placeholder in the message will be substituted with the 1-based row index of the data model. Note that this does not take pagination into account and that this needs if necessary to be taken care of in the custom message yourself.

<o:validateUniqueColumn message="Duplicate value!" />

validator

The <o:validator> basically extends the <f:validator> tag family with the possibility to evaluate the value expression in all attributes on a per request basis instead of on a per view build time basis. This allows the developer to change the attributes on a per request basis, such as the disabled attribute.

<o:validator validatorId="someValidatorId" disabled="#{param.disableValidation}" />

Note that not all available attributes are listed. This depends on the validator you're specifying. When you specify for example the standard <f:validateLongRange> by validatorId="jakarta.faces.LongRange", then you'll be able to use all its attributes such as minimum and maximum as per its documentation, but then with the possibility to supply request based value expressions.

<o:validator validatorId="jakarta.faces.LongRange" minimum="#{item.minimum}" maximum="#{item.maximum}" />

viewAction

The <o:viewAction> is a component that extends the standard <f:viewAction> and changes the if attribute to be evaluated during INVOKE_APPLICATION phase instead of the APPLY_REQUEST_VALUES phase. This allows developers to let the if attribute check the converted and validated model values before performing the view action, which results in much more intuitive behavior.

In below example, the FooConverter may convert a non-null parameter to null without causing a validation or conversion error, and the intent is to redirect the current page to otherpage.xhtml when the converted result is null.

                    <f:viewParam name="foo" value="#{bean.foo}" converter="fooConverter" />
                    <f:viewAction action="otherpage" if="#{bean.foo eq null}" />

This is however not possible with standard <f:viewAction> as it evaluates the if attribute already before the conversion has taken place. This component solves that by postponing the evaluation of the if attribute to the INVOKE_APPLICATION phase.

<f:viewParam name="foo" value="#{bean.foo}" converter="fooConverter" /> <o:viewAction action="otherpage" if="#{bean.foo eq null}" />

Only when you set immediate="true", then it will behave the same as the standard <f:viewAction>.

Messaging

You can use the message attribute to add a global flash warning message.

                    <o:viewAction ... message="Please use a valid link from within the site" />

Note that the message will only be shown when the redirect has actually taken place. The support was added in OmniFaces 3.2.

viewParam

ViewParameter is a component that extends the standard UIViewParameter and provides a stateless mode of operation and fixes the issue wherein null model values are converted to empty string parameters in query string (e.g. when includeViewParams=true) and the (bean) validation never being triggered when the parameter is completely absent in query string, causing e.g. @NotNull to fail.

The standard UIViewParameter implementation calls the model setter again after postback. This is not always desired when being bound to a view scoped bean and can lead to performance problems when combined with an expensive converter. To solve this, this component by default stores the submitted value as a component property instead of in the model (and thus in the view state in case the binding is to a view scoped bean).

The standard UIViewParameter implementation calls the converter regardless of whether the evaluated model value is null or not. As converters by specification return an empty string in case of null value, this is being added to the query string as an empty parameter. This is not desired.

The standard UIViewParameter implementation uses an internal "is required" check when the submitted value is null, hereby completely bypassing the standard UIInput validation, including any bean validation annotations and even the PreValidateEvent and PostValidateEvent events. This is not desired.

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

viewParamValidationFailed

<o:viewParamValidationFailed> allows the developer to handle a view parameter validation failure with either a redirect or a HTTP error status, optionally with respectively a flash message or HTTP error message. This tag can be placed inside <f:metadata> or <f|o:viewParam>. When placed in <f|o:viewParam>, then it will be applied when the particular view parameter has a validation error as per UIViewParameter#isValid(). When placed in <f:metadata>, and no one view parameter has already handled the validation error via its own <o:viewParamValidationFailed>, then it will be applied when there's a general validation error as per FacesContext#isValidationFailed().

The sendRedirect attribute uses under the covers Faces#redirect(String, String...) to send the redirect, so the same rules as to scheme and leading slash apply here. The sendError attribute uses under the covers Faces#responseSendError(int, String) to send the error, so you can customize HTTP error pages via <error-page> entries in web.xml, otherwise the server-default one will be displayed instead. *

f:viewParam required="true" fail

As a precaution, the <f:viewParam required="true"> has in current Mojarra and MyFaces releases (as of now, Mojarra 2.2.7 and MyFaces 2.2.4) a design error. When the parameter is not specified in the query string, then it is retrieved as null which causes that an internal isRequired() check is performed instead of delegating the check to standard UIInput implementation. This has the consequence that PreValidateEvent and PostValidateEvent listeners are never invoked, which the <o:viewParamValidationFailed> is actually relying on. This is fixed in <o:viewParam. *

Examples

With the example below, when at least one view param is absent, then the client will be returned a HTTP 400 error.

                <f:metadata>
                    <o:viewParam name="foo" required="true" />
                    <o:viewParam name="bar" required="true" />
                    <o:viewParamValidationFailed sendError="400" />
                </f:metadata>

With the example below, only when the "foo" parameter is absent, then the client will be redirected to "login.xhtml". When the "bar" parameter is absent, nothing new will happen. The process will proceed "as usual". I.e. the validation error will end up as a faces message in the current view the usual way.

                <f:metadata>
                    <o:viewParam name="foo" required="true">
                        <o:viewParamValidationFailed sendRedirect="login.xhtml" />
                    </o:viewParam>
                    <o:viewParam name="bar" required="true" />
                </f:metadata>

With the example below, only when the "foo" parameter is absent, regardless of the "bar" or "baz" parameters, then the client will be returned a HTTP 401 error. When the "foo" parameter is present, but either "bar" or "baz" parameter is absent, then the client will be redirected to "search.xhtml".

                <f:metadata>
                    <o:viewParam name="foo" required="true">
                        <o:viewParamValidationFailed sendError="401" />
                    </o:viewParam>
                    <o:viewParam name="bar" required="true" />
                    <o:viewParam name="baz" required="true" />
                    <o:viewParamValidationFailed sendRedirect="search.xhtml" />
                </f:metadata>

In a nutshell: when there are multiple <o:viewParamValidationFailed> tags, then they will be applied in the same order as they are declared in the view. So, with the example above, the one nested in <f|o:viewParam> takes precedence over the one nested in <f:metadata>. *

Messaging

By default, the first occurring faces message on the parent component will be copied, or when there is none, then the first occurring global faces message will be copied. When sendRedirect is used, then it will be set as a global flash error message. When sendError is used, then it will be set as HTTP status message.

You can override this message by explicitly specifying the message attribute. This is applicable on both sendRedirect and sendError.

                <o:viewParamValidationFailed sendRedirect="search.xhtml" message="You need to perform a search." />
                ...
                <o:viewParamValidationFailed sendError="401" message="Authentication failed. You need to login." />

Design notes

You can technically nest multiple <o:viewParamValidationFailed> inside the same parent, but this is not the documented approach and the behavior is unspecified.

You can not change the HTTP status code of a redirect. This is not a JSF limitation, but a HTTP limitation. The status code of a redirect will always end up the one of the redirected response. If you intend to "redirect" with a different HTTP status code, then you should be using sendError instead and specify the desired page as <error-page> in web.xml.