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="javax.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="javax.faces.DateTime" pattern="#{item.pattern}" locale="#{item.locale}" />
				

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

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://java.sun.com/jsf/facelets"
	xmlns:h="http://java.sun.com/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()}

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.

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.

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.

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.

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.

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

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.

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.

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