org.omnifaces.component.messages

Class OmniMessages

java.lang.Object

javax.faces.component.UIComponent

javax.faces.component.UIComponentBase

javax.faces.component.UIMessages

javax.faces.component.html.HtmlMessages

org.omnifaces.component.messages.OmniMessages

All Implemented Interfaces:

EventListener, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder

public class OmniMessages
extends HtmlMessages

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.

Since:

1.5

Author:

Bauke Scholtz

See Also:

MessagesRenderer

Field Summary

Fields

Modifier and Type	Field and Description
static String	COMPONENT_TYPE The standard component type.

Fields inherited from class javax.faces.component.UIMessages

COMPONENT_FAMILY

Fields inherited from class javax.faces.component.UIComponent

ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY

Constructor Summary

Constructors

Constructor and Description
OmniMessages() Construct a new OmniMessages component whereby the renderer type is set to MessagesRenderer.RENDERER_TYPE.

Method Summary

Modifier and Type	Method and Description
String	getMessage() Returns the single INFO message to be shown instead when this component has any faces message.
String	getVar() Returns the name of the request attribute which exposes the current faces message.
boolean	isEscape() Returns whether the message detail and summary should be HTML-escaped.
void	setEscape(boolean escape) Sets whether the message detail and summary should be HTML-escaped.
void	setMessage(String message) Sets the single INFO message to be shown instead when this component has any faces message.
void	setValueExpression(String name, ValueExpression binding) An override which checks if this isn't been invoked on var attribute.
void	setVar(String var) Sets the name of the request attribute which exposes the current faces message.

Methods inherited from class javax.faces.component.html.HtmlMessages

getDir, getErrorClass, getErrorStyle, getFatalClass, getFatalStyle, getInfoClass, getInfoStyle, getLang, getLayout, getRole, getStyle, getStyleClass, getTitle, getWarnClass, getWarnStyle, isTooltip, setDir, setErrorClass, setErrorStyle, setFatalClass, setFatalStyle, setInfoClass, setInfoStyle, setLang, setLayout, setRole, setStyle, setStyleClass, setTitle, setTooltip, setWarnClass, setWarnStyle

Methods inherited from class javax.faces.component.UIMessages

getFamily, getFor, isGlobalOnly, isRedisplay, isShowDetail, isShowSummary, setFor, setGlobalOnly, setRedisplay, setShowDetail, setShowSummary

Methods inherited from class javax.faces.component.UIComponentBase

addClientBehavior, addFacesListener, broadcast, clearInitialState, decode, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getListenersForEventClass, getParent, getPassThroughAttributes, getRenderer, getRendererType, getRendersChildren, getValueBinding, invokeOnComponent, isRendered, isTransient, markInitialState, processDecodes, processRestoreState, processSaveState, processUpdates, processValidators, queueEvent, removeFacesListener, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding, subscribeToEvent, unsubscribeFromEvent

Methods inherited from class javax.faces.component.UIComponent

encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, visitTree

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COMPONENT_TYPE

public static final String COMPONENT_TYPE

The standard component type.

See Also:

Constant Field Values

Constructor Detail

OmniMessages

public OmniMessages()

Construct a new OmniMessages component whereby the renderer type is set to MessagesRenderer.RENDERER_TYPE.

Method Detail

setValueExpression

public void setValueExpression(String name,
                               ValueExpression binding)

An override which checks if this isn't been invoked on var attribute. Finally it delegates to the super method.

Overrides:

setValueExpression in class UIComponent

Throws:

IllegalArgumentException - When this value expression is been set on var attribute.

getVar

public String getVar()

Returns the name of the request attribute which exposes the current faces message.

Returns:

The name of the request attribute which exposes the current faces message.

setVar

public void setVar(String var)

Sets the name of the request attribute which exposes the current faces message.

Parameters:

var - The name of the request attribute which exposes the current faces message.

getMessage

public String getMessage()

Returns the single INFO message to be shown instead when this component has any faces message.

Returns:

The single INFO message to be shown instead when this component has any faces message.

Since:

1.6

setMessage

public void setMessage(String message)

Sets the single INFO message to be shown instead when this component has any faces message.

Parameters:

message - The single INFO message to be shown instead when this component has any faces message.

Since:

1.6

isEscape

public boolean isEscape()

Returns whether the message detail and summary should be HTML-escaped. Defaults to true.

Returns:

Whether the message detail and summary should be HTML-escaped.

setEscape

public void setEscape(boolean escape)

Sets whether the message detail and summary should be HTML-escaped.

Parameters:

escape - Whether the message detail and summary should be HTML-escaped.