About composite-component

“Composite Component” is a JSF 2.0 / Facelets specific term for reuseable UI components which are declared using pure XML rather than Java. The composite component XML declaration tags are available under the namespace http://java.sun.com/jsf/composite. Since JSF 2.2, the namespacehttp://xmlns.jcp.org/jsf/composite can be used instead.

Creating composite components

Prepare directory structure

First create a directory resources in the public webcontent (there where the WEB-INF directory and all regular Facelets files also are).

WebContent
 |-- WEB-INF
 |    `-- lib
 |-- resources   <--- code="" test.xhtml="">

JSF 2.2 and later allows to change the resources directory by specifying a parameter namedjavax.faces.WEBAPP_RESOURCES_DIRECTORY in the web.xml file. It may be reasonable to change the directory to, for example, /WEB-INF/resources, since files under /WEB-INF are not readable via HTTP.

In the resources directory, create a directory exclusively for composite components. The directory name ends up as the extra path in the composite component namespace URI. You're free to choose the name. We'll take mycomponents as an example.

WebContent
 |-- WEB-INF
 |    `-- lib
 |-- resources
 |    `-- mycomponents   <--- code="" test.xhtml="">

This way the composite components in this directory are available in all templates by the following namespace:

 xmlns:my="http://java.sun.com/jsf/composite/mycomponents">

The prefix my is free to your choice. The http://java.sun.com/jsf/composite/ part is mandatory. The mycomponents part should be just the same as the directory name.

As a Hello World composite component example, we'll create composite component which shows a simple rating score with stars. We need to create a new XHTML file. The filename becomes the composite component tag name. You're free to choose the name. Let's call it rating.xhtml.

WebContent
 |-- WEB-INF
 |    `-- lib
 |-- resources
 |    `-- mycomponents
 |         `-- rating.xhtml   <--- code="" test.xhtml="">

This way the composite component is available in all templates as follows:

 />

Create composite component

Here's how a basic composite component template look like. Put this in rating.xhtml.

    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:cc="http://java.sun.com/jsf/composite"
>
    
        
    

We'd like to define the following attributes:

• score, integer, required. The star score.
• maxScore, integer, optional, default 100. The maximum possible score.
• totalStars, integer, optional, default 10. The total amount of stars to display.

Now, here's how the final implementation look like. Note that the attributes are available by #{cc.attrs.attributename}.

 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:cc="http://java.sun.com/jsf/composite"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:c="http://java.sun.com/jsp/jstl/core"
    xmlns:fn="http://java.sun.com/jsp/jstl/functions"
>
    
         name="score" type="java.lang.Integer" required="true" />
         name="maxScore" type="java.lang.Integer" default="100" />
         name="totalStars" type="java.lang.Integer" default="10" />
    

var="filled" value="#{fn:substringBefore(cc.attrs.score / (cc.attrs.maxScore / cc.attrs.totalStars), '.')}" /> style="font-size: 1.5em;"> begin="1" end="#{cc.attrs.totalStars}" varStatus="loop"> value="★" rendered="#{loop.index le filled}" /> value="☆" rendered="#{loop.index gt filled}" />

Here's how you can use it in test.xhtml:

 lang="en"
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html" 
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:my="http://java.sun.com/jsf/composite/mycomponents"
>
    
        
    

score="60" />
/> score="5" maxScore="10" />
/> score="80" totalStars="5" />
/>

Here's how the result should look like (only if your browser supports the Unicode star fonts; you're free to replace them by real images or even introduce a half star, which unfortunately isn't available in Unicode):

★★★★★★☆☆☆☆

★★★★★☆☆☆☆☆

★★★★☆

Create backing component

The above implementation has one disadvantage due to use the use of JSTL  : as JSTL runs during view build time instead of view render time, the above implementation cannot be used inside a repeating component such as  or . We would like to use an instead, but it doesn't support begin and end attributes. So we'd like to attach some Java code so that it converts the totalStars to a blank object array of exactly that size so that it can be used in the value attribute. Ideally, this would be done using an EL function, but for learning/wiki purposes we'll use a so-called "backing component" instead.

To create such a backing component, we need to create a class which extends UINamingContainer. Here's a basic template:

package com.example;

import javax.faces.component.FacesComponent;
import javax.faces.component.UINamingContainer;

@FacesComponent("myCompositeComponent")
public class MyCompositeComponent extends UINamingContainer {

    // ...

}

Note the value of the @FacesComponent attribute. It's the one which you should specify in thecomponentType attribute of the  tag:

 componentType="myCompositeComponent">

This way an instance of the backing component will be used behind the #{cc} variable instead. This offers you the possibility to define getter and action methods like value="#{cc.items}", action="#{cc.doSomething}" and so on. All of the  attribues are available in the backing component by the inherited UIComponent#getAttributes() method which provides easy access to the attributes.

For our rating composite component, the backing component implementation should look like this:

package com.example;

import javax.faces.component.FacesComponent;
import javax.faces.component.UINamingContainer;

@FacesComponent("ratingComponent")
public class RatingComponent extends UINamingContainer {

    public Object[] getItems() {
        Object totalStars = getAttributes().get("totalStars");
        int size = Integer.valueOf(String.valueOf(totalStars));
        return new Object[size];
    }

}

And here's how the rating.xhtml should now look like:

 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:cc="http://java.sun.com/jsf/composite"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:c="http://java.sun.com/jsp/jstl/core"
    xmlns:fn="http://java.sun.com/jsp/jstl/functions"
>
     componentType="ratingComponent">
         name="score" type="java.lang.Integer" required="true" />
         name="maxScore" type="java.lang.Integer" default="100" />
         name="totalStars" type="java.lang.Integer" default="10" />
    
    
         var="filled" value="#{fn:substringBefore(cc.attrs.score / (cc.attrs.maxScore / cc.attrs.totalStars), '.')}" />
         style="font-size: 1.5em;">
             value="#{cc.items}" varStatus="loop">
                 value="★" rendered="#{loop.index lt filled}" />            
                 value="☆" rendered="#{loop.index ge filled}" />            
            
        
    

Note the value="#{cc.items}" in the above example. It basically calls getItems() method on the instance of the backing component. Also note that we got rid of JSTL , so the above will work properly inside a repeating JSF component such as ,  and so on.

 value="#{bean.products}" var="product">
    #{product.name}

score="#{product.rating}" />

Online resources:

• Java EE 6 tutorial - Facelets - Composite Components
• Java EE 6 tutorial - Advanced Composite Components
•  tag documentation
• Mkyong.com - Composite Components in JSF 2.0
• The BalusC Code - Composite component with multiple input fields
• When to use composite components?

Related tag info pages:

• JSF tag info page
• Facelets tag info page

history | show excerpt | excerpt history