Creating a custom JSF message component

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:

META-INF/jsf-components.tld

Tag library descriptor declaring your tag and defining its attributes

META-INF/faces-config.xml

Declares the tag in the faces application

components/AlertMessage.java

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.

components/AlertMessageRenderer.java

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.

components/AlertMessageTag.java

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";

    @Override
    public String getFamily() {
        return MSG_COMPONENT_FAMILY;
    }

    @Override
    public String getRendererType() {
        return MSG_COMPONENT_TYPE;
    }

    @Override
    public String getFor() {
        return super.getFor();
    }

    @Override
    public void setFor(String forParam) {
        super.setFor(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";

    @Override
    public String getComponentType() {
        return MSG_COMPONENT_TYPE;
    }

    @Override
    public String getRendererType() {
        return MSG_RENDERER_TYPE;
    }

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

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

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

    @Override
    public void setPageContext(PageContext ctx) {
        super.setPageContext(ctx);
    }

    @Override
    public void setParent(Tag tag) {
        super.setParent(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.io.IOException;
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 {

    @Override
    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) {
            return;
        }

        // 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) iter.next();
                if (message.length() > 0) {
                    // Separate each message with the JavaScript escape code
                    // for newline
                    message.append("\n");
                }

                message.append(msg.getSummary());
            }

            // 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
            writer.endElement("script");
        }
    }

    @Override
    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="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee web-jsptaglibrary_2_0.xsd">
    <tlib-version>1.0</tlib-version>
    <short-name>jc</short-name>
    <uri>http://jsf-components</uri>
    <tag>
        <name>AlertMessage</name>
        <tag-class>components.AlertMessageTag</tag-class>
        <body-content>JSP</body-content>
        <attribute>
            <description>
                The ID of the component whose attached FacesMessage object 
                (if present) should be diplayed by this component.
            </description>
            <name>for</name>
            <required>true</required>
            <deferred-value/>
        </attribute>
    </tag>
</taglib>

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="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd">
    <component>
        <component-type>components.alertmessage</component-type>
        <component-class>components.AlertMessage</component-class>
    </component>
    
    <render-kit>
        <renderer>
            <description>Renderer for the alert message component.</description>
            <component-family>javax.faces.Message</component-family>
            <renderer-type>components.alertmessage</renderer-type>
            <renderer-class>components.AlertMessageRenderer</renderer-class>
        </renderer>
    </render-kit>
</faces-config>

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="http://java.sun.com/jsf/core"%>
<%@taglib prefix="h" uri="http://java.sun.com/jsf/html"%>
<%@taglib prefix="jc" uri="http://jsf-components" %>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        <title>Example of AlertMessage component</title>
    </head>
    <body>
        <f:view>
            <h:form>
                <jc:AlertMessage for="numberField" />
                <h:inputText id="numberField">
                    <f:validateLength minimum="5" maximum="10" />
                    <f:validateLongRange minimum="10000" maximum="222222" />
                </h:inputText>
                <h:commandButton value="Submit" action="reload" />
            </h:form>
        </f:view>
    </body>
</html>

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" "http://java.sun.com/dtd/facelet-taglib_1_0.dtd">

<facelet-taglib>
    <namespace>http://jsf-components</namespace>
    <tag>
        <tag-name>alertMessage</tag-name>
        <component>
            <component-type>components.alertmessage</component-type>
            <renderer-type>components.alertmessage</renderer-type>
        </component<
    </tag<  
</facelet-taglib<

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

<context-param>
    <param-name>facelets.LIBRARIES</param-name>
    <param-value>/WEB-INF/mycomponents.taglib.xml</param-value>
</context-param>

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