Creating a custom JSF message component

Written on February 12, 2008 by Allan Lykke Christensen

The other day I was tasked with creating feedback messages for a JSF-based application as JavaScript alert dialogues. JSF already got a tag for displaying messages attached to components (<h:message /> and <h:messages />), however they are limited to render the text using a given cascading style sheet class for each level of severity.

This entry will show how to build a custom JSF message tag for rendering the messages as a JavaScript alert.

There are many excellent tutorials and blog entries out there describing JSF component development much better than I am capable of. So, I’ll just focus on what is needed to create this specific component. My instructions are based on NetBeans 6.0, but they don’t including anything that is not possible to do in other IDEs, so you should be able to translate the instructions into your own IDE.

We will keep the tag simple with one attribute, for, which will specify for which component the messages should be displayed. The signature of the tag will therefore be: <jc:alertMessage for="myForm" />.

1. Fire up NetBeans

2. Create a new Java Class Library Project (I’ve called mine jsf-components)

Before we continue let me briefly explain what we need:


Tag library descriptor declaring your tag and defining its attributes


Declares the tag in the faces application


Class representing the user interface component with properties for each attribute supported by the tag. It’s recommended to sub-class one of the existing components to avoid doing all the work yourself.


Class for rendering the content of the tag. This is the class where we will actual construct the HTML/Javascript code that is outputted to the browser.


Class representing the actual tag.

Now that we know what to do – lets get on with it.

3. Create the components package in the Source Packages

3a) Right click Source Packages
3b) Select ‘New’
3c) Select ‘Other’
3d) Select ‘Java’
3e) Select ‘Java Package’
3f) Click ‘Next’
3g) Enter components as the package name
3h) Click ‘Finish’

4. Create the tag library descriptor
4a) Right click Source Packages
4b) Select ‘New’
4c) Select ‘Other’
4d) Select ‘Web’
4e) Select ‘Tag Library Descriptor’
4f) Click ‘Next’
4g) Enter the following information:

  • TLD name: jsf-components
  • URI: http://jsf-components
  • Prefix: jc

4h) Click ‘Finish’

5. Add the javaee.jar from the GlassFish project (%GLASSFISH%/lib) to the library dependencies of the project.

6. Create the Java class for the UI component, AlertMessage subclassing the UIMessage component.

package components;

import javax.faces.component.UIMessage;

public class AlertMessage extends UIMessage {

private static final String MSG_COMPONENT_TYPE = "components.alertmessage";
private static final String MSG_COMPONENT_FAMILY = "javax.faces.Message";

public String getFamily() {

public String getRendererType() {

public String getFor() {
return super.getFor();

public void setFor(String forParam) {

7. Create the Java class for the tag, AlertMessageTag subclassing the UIComponentELTag tag.

package components;

import javax.el.ValueExpression;
import javax.faces.component.UIComponent;
import javax.faces.webapp.UIComponentELTag;
import javax.servlet.jsp.JspException;
import javax.servlet.jsp.PageContext;
import javax.servlet.jsp.tagext.Tag;

public class AlertMessageTag extends UIComponentELTag {

private ValueExpression forParam;

private static final String MSG_COMPONENT_TYPE = "components.alertmessage";

private static final String MSG_RENDERER_TYPE = "components.alertmessage";

public String getComponentType() {

public String getRendererType() {

protected void setProperties(UIComponent component) {
AlertMessage em = (AlertMessage) component;
em.setValueExpression("for", forParam);

public int doEndTag() throws JspException {
return super.doEndTag();

public int doStartTag() throws JspException {
return super.doStartTag();

public void setPageContext(PageContext ctx) {

public void setParent(Tag tag) {

public void setFor(ValueExpression forParam) {
this.forParam = forParam;

9. Create the Java class for rendering the tag, AlertMessageRenderer subclassing the JSF Renderer.

package components;

import java.util.Iterator;
import javax.faces.application.FacesMessage;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import javax.faces.context.ResponseWriter;
import javax.faces.render.Renderer;
import org.apache.commons.lang.StringEscapeUtils;

public class AlertMessageRenderer extends Renderer {

public void encodeBegin(FacesContext context, UIComponent component) throws IOException {
AlertMessage alertMessage = (AlertMessage) component;

// Locate the component for which to display messages
UIComponent forComponent = alertMessage.findComponent(alertMessage.getFor());

// If the component could not be found end processing
if (forComponent == null) {

// Iterate through messages for the component
Iterator iter = context.getMessages(forComponent.getClientId(context));
if (iter.hasNext()) {
ResponseWriter writer = context.getResponseWriter();

// Start the script tag
writer.startElement("script", alertMessage);
writer.writeAttribute("type", "text/javascript", null);

// Construct one big string of all messages
StringBuffer message = new StringBuffer();
while (iter.hasNext()) {
FacesMessage msg = (FacesMessage);
if (message.length() > 0) {
// Separate each message with the JavaScript escape code
// for newline


// Escape the constructed string to be outputable as a JavaScript
String displayMessage = StringEscapeUtils.escapeJavaScript(message.toString());

// Output the javascript code for displaying the alert dialogue
String jsAlert = "alert('" + displayMessage + "');";
writer.writeText(jsAlert.toCharArray(), 0, jsAlert.length());

// End the script tag

public void decode(FacesContext ctx, UIComponent component) {
if (ctx == null || component == null) {
throw new NullPointerException();

Notice that I’m using StringEscapeUtils.escapeJavaScript(String) from the Apache Commons Lang library to ensure the correct output of the JavaScript code.

10. Update the tag library descriptor to reflect the created component:

<?xml version="1.0" encoding="UTF-8"?>
<taglib version="2.0" xmlns="" xmlns:xsi="" xsi:schemaLocation=" web-jsptaglibrary_2_0.xsd">
The ID of the component whose attached FacesMessage object
(if present) should be diplayed by this component.

11. Create the faces configuration (META-INF/faces-config.xml) for the component:

<?xml version='1.0' encoding='UTF-8'?>
<faces-config version="1.2" xmlns="" xmlns:xsi="" xsi:schemaLocation="">

<description>Renderer for the alert message component.</description>

12. Build the class library

All you need to do now is to place the jsf-components.jar into your web application, declare the tag library (<%@taglib prefix="jc" uri="http://jsf-components" %>) on the pages where you want to use the tag (<jc:alertMessage for="componentId" />). Example:

<%@page contentType="text/html"%>
<%@page pageEncoding="UTF-8"%>
<%@taglib prefix="f" uri=""%>
<%@taglib prefix="h" uri=""%>
<%@taglib prefix="jc" uri="http://jsf-components" %>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Example of AlertMessage component</title>
<jc:AlertMessage for="numberField" />
<h:inputText id="numberField">
<f:validateLength minimum="5" maximum="10" />
<f:validateLongRange minimum="10000" maximum="222222" />
<h:commandButton value="Submit" action="reload" />

UPDATE (30. July 2008): Facelets Support

You can use the component with Facelets by providing a Facelets Tag Library descriptor. In this example I name the tag library descriptor mycomponents.taglib.xml and place in the WEB-INF/ directory.

The contents of the descriptor is:

<?xml version="1.0"?>
<!DOCTYPE facelet-taglib PUBLIC "-//Sun Microsystems, Inc.//DTD Facelet Taglib 1.0//EN" "">


Next you need to reference the descriptor in web.xml using the facelets.LIBRARIES context parameter:


Remember that if you have more than one Facelets Tag Library Descriptor, to separate them using semicolons (;)

If you enjoyed this post Subscribe to our feed