o

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.

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

<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" />
				

{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>
				

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

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

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

<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) {
		// ...
	}
}
				

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}" />
				

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>

private JsonObject clientNavigator;

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);
        }
    }
}

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.
 				
		

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 https://github.com/ben-manes/concurrentlinkedhashmap in case a maximum cache capacity is set, or on a plain ConcurrentMap 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:

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.

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.

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.

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

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>
				

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>
				

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>
				

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>
				

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
				

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.

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>