<anyxmlelement xmlns:o="http://omnifaces.org/ui"/>
Info | Value |
---|---|
ID (tag prefix) | o |
URI | http://omnifaces.org/ui |
Tag | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
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
The
Here is a basic usage example where each parent tree node level is treated the same way via a single
<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> |
||||||||||
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 |
||||||||||
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 |
||||||||||
treeInsertChildren |
The <o:treeInsertChildren> represents the insertion point for the grand children. This is in turn
further interpreted as <o:treeNode> .
|
||||||||||
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. | ||||||||||
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 |
||||||||||
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> |
||||||||||
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 label.error { color: #f00; } input.error, select.error, textarea.error { background-color: #fee; }
You can override the default error style class by the <o:highlight styleClass="invalid" />
You can disable the default focus on the first invalid input element setting the <o:highlight styleClass="invalid" focus="false" /> |
||||||||||
conditionalComment |
o:conditionalComment is an <!--[if lte IE 7]> <link rel="stylesheet" href="ie6-ie7.css" /> <![endif]--> However, Facelets renders them HTML-escaped and if <h:outputText value="<!--[if lte IE 7]><link rel="stylesheet" href="ie6-ie7.css" /><![endif]-->" 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 |
||||||||||
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 <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 <o:validateMultipleFields components="foo bar baz" message="{0} are wrong!" />
You can use <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 <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 <o:validateMultipleFields components="foo bar baz" message="This is wrong!" showMessageFor="@invalid" />
The faces message can also be shown as global message using <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 <o:validateMultipleFields components="foo bar baz" message="This is wrong!" showMessageFor="foo baz" />
The
The validator can be disabled by the <o:validateMultipleFields components="foo bar baz" disabled="#{param.validationDisabled}" />
There is a read-only <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 |
||||||||||
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 |
||||||||||
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 |
||||||||||
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 |
||||||||||
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 |
||||||||||
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 |
||||||||||
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:
{0}: Please fill out the values of all those fields in order
For general usage instructions, refer
This validator has the additional requirement that the to-be-validated values must implement |
||||||||||
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 <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) { // ... } } |
||||||||||
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 <o:validator validatorId="jakarta.faces.LongRange" minimum="#{item.minimum}" maximum="#{item.maximum}" /> |
||||||||||
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 <o:converter converterId="jakarta.faces.DateTime" pattern="#{item.pattern}" locale="#{item.locale}" /> |
||||||||||
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.
|
||||||||||
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
The standard UIViewParameter implementation uses an internal "is required" check when the submitted value is
You can use it the same way as |
||||||||||
scriptParam |
The Usage
It's similar to the <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 <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: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); } } } |
||||||||||
hashParam |
The
The "hash query string" is the part in URL after the 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 <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
You can use the <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 <f:metadata> <o:hashParam name="foo" value="#{bean.foo}" /> <o:hashParam name="bar" value="#{bean.bar}" default="kaz" /> </f:metadata>
When |
||||||||||
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 <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:viewParam name="foo" value="#{bean.foo}" converter="fooConverter" /> <o:viewAction action="otherpage" if="#{bean.foo eq null}" /> |
||||||||||
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. | ||||||||||
moveComponent | MoveComponent is a utility component via which a components and behaviors can be moved to a target component at various ways. | ||||||||||
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 <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 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. |
||||||||||
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. | ||||||||||
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. |
||||||||||
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. |
||||||||||
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).
|
||||||||||
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.
|
||||||||||
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> .
|
||||||||||
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> .
|
||||||||||
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 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 providerA custom caching provider can be set by using the <context-param> <param-name>org.omnifaces.CACHE_PROVIDER</param-name> <param-value>com.example.MyProvider</param-value> </context-param>
The default provider, Global settingsFor 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
|
||||||||||
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
The direct parent of this component MUST be
The intended use of this is to explicitly cache a value expression that is used by one of the component children of |
||||||||||
importConstants |
The 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 The resolved constants are by reference stored in the cache to improve retrieving performance. |
||||||||||
importFunctions |
The <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 Note that the colon The resolved functions are by reference stored in the cache to improve retrieving performance. |
||||||||||
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 The locale of the resource bundle is obtained as specified in {@link Faces#getLocale()}. Usage
You can use it the same way as |
||||||||||
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. |
||||||||||
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. |
||||||||||
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. |
||||||||||
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> |
||||||||||
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
<o:validateUniqueColumn message="Duplicate value!" /> |
||||||||||
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 <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> |
||||||||||
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 f:viewParam required="true" fail
As a precaution, the ExamplesWith 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 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
You can override this message by explicitly specifying the <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
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 |
||||||||||
commandScript |
CommandScript is an extension to
The
Basic usage example of <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 <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 |
||||||||||
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 <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. |
||||||||||
messages |
The <o:messages> is a component that extends the standard <h:messages> with
the following new features:
Design notice: the component class is named |
||||||||||
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 |
||||||||||
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 <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> |
||||||||||
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
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 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
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.
|
Output generated by Vdldoc View Declaration Language Documentation Generator.