Module org.omnifaces
Package org.omnifaces.component.messages

Class OmniMessages

java.lang.Object
jakarta.faces.component.UIComponent
jakarta.faces.component.UIComponentBase
jakarta.faces.component.UIMessages
jakarta.faces.component.html.HtmlMessages
org.omnifaces.component.messages.OmniMessages
All Implemented Interfaces:
PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener
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 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 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:

  • Field Details

    • COMPONENT_TYPE

      public static final String COMPONENT_TYPE
      The component type, which is "org.omnifaces.component.messages.OmniMessages".
      See Also:

  • Constructor Details

  • Method Details

    • 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 HtmlMessages
      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 varName)
      Sets the name of the request attribute which exposes the current faces message.
      Parameters:
      varName - 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.