Facelets tutorial. Using composition components

In the previous Facelets Tutorial we have shown a simple facelet example that demonstrates the use of templates to promote code reuse. In this tutorial we will show how to create composition components to create extensible components.

A composite component is a special type of template that acts as a component.

In practive, a composite component consists of a collection of markup tags and other existing components. This reusable, user-created component has a customized, defined functionality and can have validators, converters, and listeners attached to it like any other component.

Recall our templateClient.xhtml from the previous Facelets Tutorial. Let's suppose we want to insert into the Content section a picure and a PanelGrid with a variable number of columns/rows.

Let's build first our customized component, by creating a page named panel.xhtml:

<!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:ui="http://java.sun.com/jsf/facelets"
 xmlns:h="http://java.sun.com/jsf/html"
 xmlns:c="http://java.sun.com/jsp/jstl/core"
 xmlns:f="http://java.sun.com/jsf/core">
 
 <h:graphicImage value="#{resource['images:wave.med.gif']}"/>     

 <h:panelGrid columns="${cols}" border="1" >
 <f:facet name="header">
   <h:outputText value="${title}"/>
  </f:facet>
  <c:forEach var="field" items="${data}">
   <h:outputText value="#{field}"/>
  </c:forEach>
 </h:panelGrid>
</html>

This page, renders an image and a panelGrid. The relevant portion of the codes are the parameters of this page which are:

cols: the number of columns in the panel

title: the title of the panel

data: the collection containing the data.

Now you must register this composite component in an xml file much the same way you did in the past for JSP custom tags

<facelet-taglib>
  <namespace>http://www.mastertheboss.com/jsf</namespace>
  <tag>
    <tag-name>mypanel</tag-name>
    <source>../panel.xhtml</source>
  </tag>
 </facelet-taglib>

Now save this file in the WEB-INF folder of your Web application as sampletaglib.xml.

The last configuration step, will be adding in your faces-config.xml a parameter which defines where facelets libraries are located (in our example, under WEB-INF/sampletaglib.xml).

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

That's all. Now if you want to reference your composite tag in your facelets, just declare the xml namespace in the html section (in this example we will reference it as "i"):

<!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:ui="http://java.sun.com/jsf/facelets"
 xmlns:h="http://java.sun.com/jsf/html"
 xmlns:c="http://java.sun.com/jsp/jstl/core"
 xmlns:i="http://www.mastertheboss.com/jsf">
 
 <h:body>
  <ui:composition template="./template.xhtml">

    <ui:define name="content">
      <i:mypanel cols="3" title="Title of the panel" data="#{personBean.fields}" />
    </ui:define>
  </ui:composition>
 </h:body>

</html>

Notice we have bound the parameters cols, title and data which we have declared in our pane.xhtml template page.

Finally, we need to define the class PersonBean, which is tagged using JSF 2 annotations

package sample;

@ManagedBean(name="personBean")
@RequestScoped

public class PersonBean {
 
 private ArrayList fields = new ArrayList();
 
 public PersonBean() {
  fields.add(new String("Column1"));
  fields.add(new String("Column2"));
  fields.add(new String("Column3"));
 }
 
  public ArrayList getFields(){
   return fields;
  }
}

The composite component when rendered will generate something like this:

Title of the panel
Column1	Column2	Column3

References: http://download.oracle.com/javaee/6/tutorial/doc/giqzr.html

MASTERTHEBOSS.COM

JBoss and Java EE tutorials

The AS7 book!

JBoss Tuning

JBoss 5 book

Poll

Facelets tutorial. Using composition components