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

Class 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:
    MessagesRenderer

    • Field Detail

      • COMPONENT_TYPE

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

    • Method Detail

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