My JSF Books/Videos My JSF Tutorials OmniFaces/JSF PPTs
JSF 2.3 Tutorial
JSF Caching Tutorial
JSF Navigation Tutorial
JSF Scopes Tutorial
JSF Page Author Beginner's Guide
OmniFaces 2.3 Tutorial Examples
OmniFaces 2.2 Tutorial Examples
JSF Events Tutorial
OmniFaces Callbacks Usages
JSF State Tutorial
JSF and Design Patterns
JSF 2.3 New Features (2.3-m04)
Introduction to OmniFaces
25+ Reasons to use OmniFaces in JSF
OmniFaces Validators
OmniFaces Converters
JSF Design Patterns
Mastering OmniFaces
Reusable and less-verbose JSF code

My JSF Resources ...

Java EE Guardian
Member of JCG Program
Member MVB DZone
Blog curated on ZEEF
OmniFaces is an utility library for JSF, including PrimeFaces, RichFaces, ICEfaces ...

[OmniFaces Utilities] - Find the right JSF OmniFaces 2 utilities methods/functions

Search on blog

Petition by Java EE Guardians

Twitter

luni, 9 martie 2015

JSF 2.2 - <h:message> vs <h:messages>

The <h:message> and <h:messages> tags are used to display error messages when conversion or validation fails. More generally, in order to keep the end user informed about the success/failure of its actions (requests), JSF uses messages. There are four types of messages: Information, Warning, Error and Fatal, and each message can contain a summary and a detail (e.g. summary: Error!, detail: The provided address is not a valid e-mail!). Beside the JSF standard messages (standard error messages are provided with standard converters and standard validators in Messages.properties file - you can override these messages), JSF developers can write their own messages via FacesMessage:

FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_ERROR,
              "Error!", "The provided address is not a valid e-mail!");

Typically, the custom messages appear in custom converters and validators, but they also appear in managed beans or other JSF artifacts.
When multiple messages are associated with a client identifier (or with any specific component instance, if there is no client identifier), then the messages are added into a list of messages by using FacesContext.addMessage() method :

FacesContext context = FacesContext.getCurrentInstance();
//associated with any specific component instance (global)
context.addMessage(null, new FacesMessage(FacesMessage.SEVERITY_ERROR,
              "Error - global!", "The provided address is not a valid e-mail!"));
//associated with a client identifier (not global)
context.addMessage("clientId", new FacesMessage(FacesMessage.SEVERITY_ERROR,
              "Error - not global!", "The provided address is not a valid e-mail!"));

Note that client identifier is the component's clientId, NOT its id. Per example, in a table, each row has an unique clientId , but the same id, which means that the clientId allows us to attach a message to each row. Most commonly the clientId is composed as formId:componentId. This will attach the given message to:

<h:form id="formId">
 some component with ID, componentId
 <h:message for="componentId "> 
</h:form>

Now, the page author will use <h:message> and/or <h:messages> tags as placeholders for the messages. The <h:message> is used to render a single message for a specific component - the for attribute is mandatory and it points out the client identifier which benefits of this message. If more messages has been created for the same component, <h:message> shows only the first one:

<h:message for=" clientId" showSummary="true" showDetail="true"/>
Output: Error - not global! The provided address is not a valid e-mail!

By the other hand, <h:messages> is capable to display all messages in current page (including those displayed in a <h:message>). More technically, all messages stored in the faces context during the course of the JSF life cycle:

<h:messages showSummary="true" showDetail="true"/>
Output: Error - not global! The provided address is not a valid e-mail!
       Error - global! The provided address is not a valid e-mail!

Moreover, <h:messages> supports a flag attribute named, globalOnly which indicates that only global messages (that is, messages not associated with any client identifier) are to be displayed. Default value is false.

<h:messages globalOnly="true" showSummary="true" showDetail="true"/>
Output: Error - global! The provided address is not a valid e-mail!

Keep in mind that <h:messages> also support the for attribute, but this attribute is mutually exclusive with globalOnly and take precedence if used - <h:messages for="componentId"> can be used to show all messages attached to componentId. Starting with JSF 2.0, in Development stage, JSF  automatically attached a <h:messages> child to the current page. (the Mojarra 2.2 does this in RenderKitUtils.renderUnhandledMessages() method by creating an instance of the HtmlMessages component with id, javax_faces_developmentstage_messages). This is why you can see all messages without having an explicit <h:messages> or <h:message> in your page.

Typically, in validators, you will use something like this (maybe setting the component label is not so typical):
...
throw new ValidatorException(new FacesMessage(FacesMessage.SEVERITY_ERROR, "Component label", "Validation error message"));
...

While in a converter will be more like this:
...
throw new ConverterException(new FacesMessage(FacesMessage.SEVERITY_ERROR, "Component label", "converter error message"));
...

Notice that, by default, JSF validation/converter error messages are prepared with the clientId of the component. They are not global messages.
A nice trick that I'd like to share involves the tooltip attribute of the <h:message> (also present in <h:messages>). If you set this attribute to true, and the showSummary to true and showDetail to false, then the detail will be wrapped in a tooltip that will appear when the mouse hovers over the summary:

<h:messages for="clientId" tooltip="true" showDetail="false" showSummary="true" />

OmniFaces spice up JSF messages with <o:messages> which is a component that extends the standard <h:messages> with the following new features: multiple for components, display single message, HTML escaping, iteration markup control. Moreover, OmniFaces utilities methods for messages provide really cool features.

Niciun comentariu :

Trimiteți un comentariu

JSF BOOKS COLLECTION

Postări populare

OmniFaces/JSF Fans

Follow by Email

Visitors Starting 4 September 2015

Locations of Site Visitors