JSF 2 Templating with Facelets example

In web application, most pages are follow a similar web interface layout and styling, for example, same header and footer. In JSF 2.0, you can use Facelets tags to provide a standard web interface layout easily, in fact, it’s look similar with Apache Tiles framework.

In this example, it shows the use of 4 Facelets tags to build page from a template :

  1. ui:insert – Used in template file, it defines content that is going to replace by the file that load the template. The content can be replace with “ui:define” tag.
  2. ui:define – Defines content that is inserted into template with a matching “ui:insert” tag.
  3. ui:include – Similar to JSP’s “jsp:include”, includes content from another XHTML page.
  4. ui:composition – If used with “template” attribute, the specified template is loaded, and the children of this tag defines the template layout; Otherwise, it’s a group of elements, that can be inserted somewhere. In addition, JSF removes all tags “outside” of “ui:composition” tag.

1. Template Layout

In JSF 2.0, a template file is just a normal XHTML file, with few JSF facelets tags to define the template layout.

File : commonLayout.xhtml

<?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:head>
	<h:outputStylesheet name="common-style.css" library="css" />
    </h:head>
 
    <h:body>
 
	<div id="page">
 
	    <div id="header">
		<ui:insert name="header" >
		  <ui:include src="/template/common/commonHeader.xhtml" />
		</ui:insert>
	    </div>
 
	    <div id="content">
	  	<ui:insert name="content" >
	 	  <ui:include src="/template/common/commonContent.xhtml" />
	   	</ui:insert>
	    </div>
 
	    <div id="footer">
	    	<ui:insert name="footer" >
	    	  <ui:include src="/template/common/commonFooter.xhtml" />
	    	</ui:insert>
    	    </div>
 
        </div>
 
    </h:body>
</html>

In this template, it defines a standard web layout :

  1. Uses “h:outputStylesheet” tag to include a CSS file in head to styling the whole page layout.
  2. Uses “ui:insert” tag to define three replaceable sections : header, content and footer.
  3. Uses “ui:include” tag to provide a default content if no replacement is specified when the template is used.

2. Header, Content and Footer

Three default page content.

File : commonHeader.xhtml

<?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:ui="http://java.sun.com/jsf/facelets"
      >
    <body>
	    <ui:composition>
 
		<h1>This is default header</h1>
 
	    </ui:composition>
    </body>
</html>

File : commonContent.xhtml

<?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:ui="http://java.sun.com/jsf/facelets"
      >
    <body>
	    <ui:composition>
 
		<h1>This is default content</h1>
 
	    </ui:composition>
    </body>
</html>

File : commonFooter.xhtml

<?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:ui="http://java.sun.com/jsf/facelets"
      >
    <body>
	    <ui:composition>
 
		<h1>This is default footer</h1>
 
	    </ui:composition>
    </body>
</html>

When these pages are insert into the template file, all the tags outside of the “ui:composition” will be removed. For example,

File : commonHeader.xhtml

<?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:ui="http://java.sun.com/jsf/facelets"
      >
    <body>
	    ALL TAGS ABOVE THIS LINE WILL BE REMOVED BY JSF
	    <ui:composition>
 
		<h1>This is default header</h1>
 
	    </ui:composition>
	    ALL TAGS BELOW THIS LINE WILL BE REMOVED BY JSF
    </body>
</html>

JSF only takes following elements and insert into the template file

<ui:composition>
 
	<h1>This is default header</h1>
 
</ui:composition>

When insert into the “commonLayout” template , it became…

File : commonLayout.xhtml

	...
    <h:body>
 
	<div id="page">
 
	    <div id="header">
		<h1>This is default header</h1>
	    </div>
	...

3. Using Template

To make use of an existing template, eg. “commonLayout.xhtml“, you use “ui:composition” tag with a “template” attribute. See following two examples :

File : default.xhtml

<?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 template="template/common/commonLayout.xhtml">
 
    	</ui:composition>
 
    </h:body>
 
</html>

This JSF page load “commonLayout.xhtml” template and display all the default page content.

jsf2-facelets-template-example-1

File : page1.xhtml

<?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 template="/template/common/commonLayout.xhtml">
 
    		<ui:define name="content">
    			<h2>This is page1 content</h2>
    		</ui:define>
 
		<ui:define name="footer">
    			<h2>This is page1 Footer</h2>
    		</ui:define>
 
    	</ui:composition>
 
    </h:body>
 
</html>

This JSF page load a “commonLayout.xhtml” template and use “ui:define” tag to override the the “ui:insert” tag, which defined in the template file.

jsf2-facelets-template-example-2
Note
As long as the name of the “ui:define” tag is matched to the name of the “ui:insert” tag, which defined in template, the “ui:insert” content is replaced.

Download Source Code

Download It – JSF-2-Facelets-Template-Example.zip (12KB)

References

  1. Apache Tiles Framework
  2. JSF “ui:include” JavaDoc
  3. JSF “ui:insert” JavaDoc
  4. JSF “ui:define” JavaDoc
  5. JSF “ui:composition” JavaDoc
Tags :

About the Author

mkyong
Founder of Mkyong.com and HostingCompass.com, love Java and open source stuff. Follow him on Twitter, or befriend him on Facebook or Google Plus. If you like my tutorials, consider make a donation to these charities.

Comments