How To Create Your Own Java Server Faces Components

<div>Hello JSF Component</div>

<d:ticker>
<f:verbatim>Hello JSF Component</f:verbatim>
</d:ticker>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN"
"http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd">
  <taglib>
    <tlib-version>1.0</tlib-version>
    <jsp-version>1.2</jsp-version>
    <short-name>d</short-name>
    <uri>http://jsftutorials.com/</uri>
    <tag>
      <name>ticker</name>
      <tag-class>ticker.TickerTag</tag-class>
      <body-content>JSP</body-content>
    </tag>
  </taglib>

We have declared the new tag with the name ticker and defined ticker.TickerTag as a tag class. Open JavaSource folder; create a package ticker there and the class TickerTag there that contains the following code:

package ticker;
import javax.faces.component.UIComponent;
import javax.faces.webapp.UIComponentTag;
public class TickerTag extends UIComponentTag{
public void release() {
		// the super class method should be called
		super.release();
	}
	protected void setProperties(UIComponent component) {
		// the super class method should be called
		super.setProperties(component);
	}
	public String getComponentType() {
		return "ticker";
		}
	public String getRendererType() {
		// null means the component renders itself
		return null;
	}
}

The class TickerTag processes the tag attribute. Such a class name has the suffix Tag by a naming convention. The TickerTag class extends UIConponentTag and implements four methods.

The getComponentType() method returns the symbolic name of the component type. We will define the class for this type latter in the faces-config file.

The getRendererType() method returns the symbolic name of the renderer. If getRendererType() returns null, it means that the renderer name is not defined and the component will render it by itself.

The release() method releases any resources allocated during the execution of this tag handler. We will use this method to reset the attribute values. The release() method should call the release() method of the super class.

And the last (but not least) method, setProperties(UIComponent component), is used to pass attributes taken from the JSP page to the renderer. You can use the JSF EL (Java Server Faces Expression Language) in the value for the tag attribute. This is also resolved by the setProperties method. We will return back to this theme in step 4 of this tutorial.

Now let’s define the component class for the component type declared above. Open
WEB-INF/faces-config.xml and put the declaration there. The faces-config.xml should contain the following code:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
"http://java.sun.com/dtd/web-facesconfig_1_0.dtd">
  <faces-config>
    <component>
      <component-type>ticker</component-type>
      <component-class>ticker.UITicker</component-class>
    </component>
    <lifecycle/>
    <application>
      <locale-config/>
    </application>
    <factory/>
  </faces-config>

We have defined the ticker.UITicker class as a component class for the ticker type. By a naming convention, such a class starts with the UI prefix. The component class provides a rendering user interface, state saving and restoring, and processing of user input. Create the tickerUITicker class with the following content:

package ticker;
import java.io.IOException;
import javax.faces.component.UIOutput;
import javax.faces.context.FacesContext;
import javax.faces.context.ResponseWriter;
public class UITicker extends UIOutput {
	public void encodeBegin(FacesContext context) throws IOException {
		ResponseWriter writer = context.getResponseWriter();
		writer.startElement("div", this);
	}
	public void encodeEnd(FacesContext context) throws IOException {
		ResponseWriter writer = context.getResponseWriter();
		writer.endElement("div");
	}
}

Because our custom component does not provide for any user input, we extend the class from the UIOutput. The UITicker class implements two methods encodeBegin(FacesContext context) and encodeEnd(FacesContext context). The first method encodes the opening tag; the second one encodes the closing tag. However, if your tags do not contain a body, it is recommended to encode everything using only the encodeEnd(FacesContext context) method. Now let’s create the page where our custom tag will be used. Open the bannerpage.jsp page located inside the WebContent folder and add a taglib declaration and our tag with test output. The page should look like:

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<%@ taglib uri="http://jsftutorials.com/" prefix="d" %>
<html>
  <head>
    <title>Show Custom Component</title>
  </head>
  <body>
    <f:view>
      <d:ticker>
        <f:verbatim>Hello JSF Component</f:verbatim>
      </d:ticker>
    </f:view>
  </body>
</html>

There are two things important to mention here. The first thing concerns the URI attribute. Many people think that this attribute must be a reference to an existing URL, but this is not quite true. A URI is not the same as a URL. The target of this attribute is defining the unique string that will distinguish this particular taglib from the others.

The second important thing is using <f:verbatim> </f:verbatim> around the plain text. When the Java Server Faces Components tree is rendered, it contains only the Java Server Faces Components. So, any children in the hierarchy must be Java Server Faces components. If you run the first example, there might not be any difference, because <d:ticker> is a root node of the Java Server Faces Component hierarchy. However, in case you add <h:gridPanel>, for example, around it, you will find that the plain text without <f:verbatim> will be pushed out of the <div></div> in the rendered page.

At this point, our first step has been finished. We can compile, deploy, and run the result application. If you use Ant to do this job, run Ant so that the ticker.war file is copied to the servlet container to run.

If you’re using JSF Studio, click the Start Tomcat Server button on the toolbar, and then click the Run Web Application button. The default browser should be launched and show the result of page rendering.

You can see the Hello JSF Component text in the browser window. Because <div> itself does not provide any visual effect, you can recognize that the page is rendered as we expected only if you look at the source of the result page. It should contain the <div>Hello JSF Component</div> text. If so, the first step is done. You have already written you first JSF Component. Of course, it has very limited functionality, but we just laid the foundation. The component will be improved in the next step.

Before we go any further, let’s survey the relationships among the different Java Server Faces artifacts we are using here. The following picture shows this relationship:

Guidelines for Designing Reusable Custom Components Using JavaServer Faces Technology

Creating JSF Custom Components by Bill Dudney