SeamFramework.orgCommunity Documentation
While JSF already has the concept of adding FacesMessage objects to the FacesContext in order for those messages to be
displayed to the user when the view is rendered, Seam Faces takes this concept one step farther with the Messages API provided by the
Seam International module. Messages are template-based, and can be added directly via the code, or templates can be loaded from resource
bundles using a BundleKey.
Consistent with the CDI programming model, the Messages API is provided via bean injection. To add a new message to be displayed to the user,
inject org.jboss.seam.international.status.Messages and call one of the Message factory methods. As mentioned earlier,
factory methods accept either a plain-text template, or a BundleKey, specifying the name of the resource bundle to use, and
the name of the key to use as a message template.
@Named
public class Example
{
@Inject
Messages messages;
public String action()
{
messages.info("This is an {0} message, and will be displayed to {1}.", "INFO", "the user");
return null;
}
}
Adds the message: "This is an INFO message, and will be displayed to the user."
Notice how {0}, {1} ... {N} are replaced with the given parameters, and may be used more than once in a given template. In the case where a
BundleKey is used to look up a message template, default text may be provided in case the resource cannot be loaded; default
text uses the same parameters supplied for the bundle template. If no default text is supplied, a String representation of the
BundleKey and its parameters will be displayed instead.
public String action()
{
messages.warn(new BundleKey("org.jboss.seam.faces.exampleBundle", "messageKey"), "unique");
return null;
}
classpath:/org/jboss/seam/faces/exampleBundle.properties
messageKey=This {0} parameter is not so {0}, see?Adds the message: "This unique parameter is not so unique, see?"
It's great when messages are added to the internal buffer, but it doesn't do much good unless the user actually sees them. In order to display
messages, simply use the <h:messages /> tag from JSF. Any pending messages will be displayed on the page just like normal
FacesMessages.
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:s="http://jboss.org/seam/faces"
xmlns:ui="http://java.sun.com/jsf/facelets">
<h1>Welcome to Seam Faces!</h1>
<p>All Messages and FacesMessages will be displayed below:</p>
<h:messages />
</html>
Messages added to the internal buffer via the Messages API are stored in a central location during each request, and may be displayed
by any view-technology that supports the Messages API. Seam Faces provides an integration that makes all of this automatic for you as a developer,
and in addition, messages will automatically survive JSF navigation and redirects, as long as the redirect URL was encoded using
ExternalContext.encodeRedirectURL(...). If you are using JSF-compliant navigation, all of this is handled for you.