JSF custom tag tutorial

In this tutorial we will show how to create JSF custom tags based on content defined in an XHTML page.

Creating custom JSF tags can be done either by means of Java classes implementing the UIComponentBase interface or by means of XHTML code fragments. In this tutorial we will show the latter option. Creating a custom JSF XHTML based tag can be quite useful if you want to reuse across your pages some templates such as forms or general settings.
Creating your custom tag requires just three simple steps:


Step # 1 Define your tag content
The following form.xhtml page contains (within an ui:composition section) a block of XHTML code we want to reuse across our pages:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:ui="http://java.sun.com/jsf/facelets">
<h:body>
    <ui:composition>
        <table>
            <tr>
                <td>Name:<h:inputText value="#{user.name}" />
                </td>
            </tr>
            <tr>
                <td>Surname:<h:inputText value="#{user.surname}" /></td>
            </tr>
            <tr>
                <h:commandButton type="submit" action="#{user.action}" value="#{buttonLabel}" />  
            </tr>
        </table>

    </ui:composition>
</h:body>
</html>

 

Please notice that this template XHTML page is using EL expressions both for referencing Managed Beans (The User Bean) and for custom values which can be added to the tags (The #{buttonLabel) expression which will be used in the tag to customize its look)

 

Save this page somewhere under the WEB-INF folder so that it can be found by the Web classloader. In our example we have saved it as WEB_INF/tags/form.xhtml

Step #2 Define your tag within a tag lib file:
Add the following custom.taglib.xml to your WEB-INF folder:

<facelet-taglib 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-facelettaglibrary_2_0.xsd"
    version="2.0">
    <namespace>http://www.mastertheboss.com/custom-taglib</namespace>

    <tag>
        <tag-name>form</tag-name>
        <source>tags/form.xhtml</source>
    </tag>
</facelet-taglib>

As you can see, we are referencing the source XHTML contained in tags/form.xhtml and associating it with the "form" tag name.

Step #3 Add a reference to your tag lib in web.xml

 

<context-param>
    <param-name>javax.faces.FACELETS_LIBRARIES</param-name>
    <param-value>/WEB-INF/custom.taglib.xml</param-value>
 </context-param>

(Please note that the older facelets.LIBRARIES property has been deprecated and might not work in some Java EE servers. So use the above javax.faces.FACELETS_LIBRARIES for JSF 2 compliant servers)

Now that everything is in place you can just reference your tag within your XHTML pages as shown:

<html xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:ct="http://www.mastertheboss.com/custom-taglib">

<h:body>           

</h:body>
    <ct:form buttonLabel="ClickMe" />
</html>

And here's your custom tag in action:

jsf custom tag tutorial

Download the code from this article.

Follow us on Twitter