Thursday, April 16, 2009

Custom Tags

<< Previous        Next>>

Creating a Custom tags in Facelets

Like JSF, Facelets is also easily extensible, by allowing us to create and modify Tags, Converters, Validators etc. Here we are going to see how to create a simple  Custom Tag in facelets. There are different ways you can create a Custom Tags in JSF. The one we are going to try now, don't even need a single line of Java code. This tag is going to use an external view file, like sideMenu.xhtml, the one we created in the previous Facelet Tutorial. This source file will be complied in to the Facelet from where this tag is invoked. 

All the Custom Tags in Facelets should be declared in a Facelets taglib. A Facelets tag library is a collection of custom tags identified by an XML namespace.

Create a Facelets tag library

Create a folder "facelets" in WebContent/WEB-INF folder of JSFFaceletsExample application. Right-mouse click on the WebContent/WEB-INF/facelets folder, select New->XML  to launch the XML File wizard. Type the file name mytags.taglib.xml and click 'Next'.

Select the option 'Create XML file from a DTD file' and click 'Next'.

Select the option 'Select XML Catalog entry' and select the 'XML Catalog', which says DTD Facelet Taglib 1.0 and click 'Next'.

Click 'Finish'.

The following is an example of the tag library:

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

This facelets Tutorial Tag library only defines one tag but all of the tags being used in the application should be defined in the same tag library file. Note the namespace element that is declared before the tag element, it will be used in the facelets page.

We have decided to call the tag library namespace and will need to declare this namespace in any pages where we are using the custom component. After the namespace definition, we can find the tag element that defines our brand new tag. The tag-name element refers to the name we want to give to the tag, which in our case is menu. The source element contain the relative path to the tag file (menu.xhtml). The next step is to declare the taglib in web.xml. 

Declare the Facelets custom taglib in web.xml

In order to use the taglib, you have to make Facelets aware of its existence by declaring it in the web.xml file. Declare a Facelets tag library in a <context-param> element (facelets.LIBRARIES)  in the web. xml file. This will tell Facelets the that tag library exists so it can use the taglib.

The following code shows how it should be declared in web.xml

Creating the source file
We have already declare the source file menu.xhtml in the taglib. Now it is time to create one. This file is not different from the sideMenu.xhtml from the previous Facelets tutorial.

Create a folder "tags" in WebContent/WEB-INF folder of JSFFaceletsExample application. Now we need to create a  page called, menu.xhtml in the WebContent/WEB-INF/tags folder of the application. Right-mouse click on the WebContent/WEB-INF/tags folder, select New->HTML Page to launch the HTML Page wizard. Type the file name menu.xhtml and click 'Finish'. The page will be opened in the Web Page Editor.
Modify the page as follows:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html xmlns=""
    <c:forEach var="menu" items="#{menus}">
         <a href="#{menu.url}">#{menu.label}</a><br/>

Using the Tag in a Facelets page

Once the taglib file has been created and defined in the tag library,  its ready to be used. To use the Custom tag in a facelets view file (home.xhtml), declare it as an XML namespace, shown below:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html xmlns=""
xmlns:rs="" >
<ui:composition template="WEB-INF/templates/insertTemplate.xhtml">
  <ui:define name="sidemenu">
          <rs:menu menus="#{menuBackingBean.menus}"/>
  <ui:define name="content">
           This is an example of a simple Facelets template.<br/>
           Here Header and Footer  appears from template.(insertTemplate.xhtml)<br/>
           Side Menu appears from menu.xhtml
           This section appears from templateClient.(home.xhtml)

Run your webapplication

To run your web application, right click on home.xhtml, click- >run as -> run on server.
Select the server type ,Apache Tomacat v6.0 Server.Click Fininsh.

Open a web browser and type the url : http://localhost:8080/JSFFaceletsExample/home.xhtml

Your page will be rendered like this: