Notes on Facelets

searchcoilSoftware and s/w Development

Aug 15, 2012 (5 years and 7 days ago)

559 views

Page
1

of
14

Notes on
Facelets

Created 04/17/08

Updated 05/05/08
,
Updated 05/16/08
, Updated 07/09/08
, Updated 07/13/08
, Updated 08/16/08
, Updated 08/20/08

Updated 12/06/08
, Updated 03/16/09

Facelets

Facelets
, a view definition f
ramework,

appears to be a very amorphous
technology
, perhaps because it is so recent,
and so “invisible”. In the same way that JSP’s can be viewed as a way of generating servlets, a Facelet
s

page can be
viewed as a way of generating a JavaServer Faces
component tree for use by the JSF engine
. I
n this respect, it is
like

a more
-
friendly version of JSF, with the following advantages:




Improves JSF performance by 30% to 50%,
by
bypassing the JSP engine. While there is a benefit during
the first processing of the page (i.e., no conversion into a se
rvlet), there is also a on
-
going benefit, as the
JSP environment carries out its own processing of EL expressions as well as the JSF engine performing
this. Sometimes there could be conflicts. This will be resolved in future versions of JSP (such as 2.1+
) but
these will not be available until JBoss 5.x, for instance. Hence, if you are using JBoss 4.x, you should
avoid JSP altogether and use Facelets instead.



You
can use any HTML tags in a Facelets page. It eliminates the need

to enclose XHTML tags and f
ree
text in the <f:verbatim> tags.



Provides nice debugging support in the browser.



Facelets provides some additional tags to use in your pages, including an iteration tag.



Facelets provides a template framework.


What is a Facelet?


A "Facelet" is a reusab
le section of content or a sub
-
tree of components on a JSF page that can itself be
composed of other Facelets.


In this sense, a Facelet is a composite view element that can easily be
combined with other Facelets to build a JSF view that will be rendered t
o the user.


One description
of Facelets
reads as follows:


The web community is eagerly seeking a framework like Tapestry, backed by JavaServer Faces as the
industry standard.

While JavaServer Faces and JSP are meant to be aligned,

Facelets steps outsid
e of the
JSP spec and provides a highly performant, JSF
-
centric view technology.

Anyone who has created a JSP
page will be able to do the same with Facelets.

The difference is under the hood where all the burden of the
JSP Vendor API is removed to more g
reatly enhance JSF performance and provide easy plug
-
and
-
go
development.

Even though Facelets is being developed open source under Sun's guidance, it can work with
any JSF 1.2 compliant implementation or MyFaces.


Another description can be paraphrased a
s:


The mismatch between JSF and JavaServer Pages technology is a serious problem in JSF development.

The issue is how to integrate JSP's dynamic content into JSF's component
-
based model.

JSP is singularly
focused on generating dynamic output, whereas JS
F requires JSP to coordinate building a component
model.

The disjunct occurs because that task is beyond the original intention of JSP.


Most JSF developers simply learn to navigate such problems on an ad
-
hoc basis, but that's kind of like
duct
-
taping a p
illow to a hammer so it won't hurt coming down on your head.

Facelets is a much more
comprehensive solution: a templating language that is geared toward the JSF component model.


Facelets has several compelling features:



Composition components (like inclu
de files, or a

macro processor)



Templating
facilities
(like Tiles)

Page
2

of
14



Use of JSTL

1.2



Designer
-
friendly page development



Support for c
reation of c
omponent libraries


Note that the Facelets compilation process is much faster than the JSP compilation process

because no Java
bytecode is actually generated and compiled behind the scenes when you first visit your page.


While one of the examples that we will study is a Tiles facility, o
ne of the biggest mistakes you can make is to
assume that Facelets is merely
a replacement for Tiles.

Facelets is much more than that:

it's a new way of thinking
about JSF.


It allows you to take a regular HTML file, and mark the elements with Facelet attributes to cause the engine to
create the JSF component that corresponds to
that HTML tag. This way the file can be created in standard HTML
creation tools, such as Dreamweaver. For this reason the Facelets files are typically given an extension of .xhtml,
rather than .jsp.


Also like JSP, Facelets

appears to be something can be

used in several different ways, some good and some not so
good, and will probably become a primary tool. Remember that there were no JSP
-
specific books during the 1999
to 2001 gestation period of JSP, yet by 2005 there were many.


It may be that Facelets

gets better and becomes better explained over the next few years.

Facelets appears to now be
a project within Sun as part of GlassFish.

Resources

Until the Aranda and Wadia book came out, there were no
printed
books

specifically on
Facelets
.
Instead, th
e
primary resource for information has been web pages.
However,
Facelets

is discussed in the Geary
-
Hor
stmann book
on JavaServer Faces
. Part of C
hapter 13 is
about

Facelets
.


“Facelets Essential: G
uide to JavaServer Faces View Definition Framework”, by Br
uno Aranda and Zubin Wadia,

APress,
April

2008, 84 pages. List price $19.99, Amazon price $17.99, used from $15.00. Rated 3 stars on
Amazon. This is a short book, and is considered to not be adding all that much besides an introduction to the
already av
ailable materials. Skip it.


“Facelets”, by Robert Swarr. O’Reilly Safari e
-
book

in the “Short Cuts” series
, published
February

2007. 100
pages. Avai
lable for $9.99 on Safari.com. Not rated. This is not really a book as much as it is set of reference

notes.


The project home is
https://facelets.dev.java.net/
.

This site is largely a wik
i that contains
examples, downloads, and
discussion.


Within the wiki, there is

developer documentation at:

https://facelets.dev.java.net/nonav/docs/dev/docbook.html


There is a tutorial at
http://www.netbeans.org/kb/55/quickstart
-
facelets
-
in
-
netbeans.html
, but this is very NetBeans
focused.

Current
Version

The current version is 1.1.14, rele
ased on April 15, 2008. This i
s a minor point release beyond the prior release,
which was over a year ago. There is
a 1.2 version
that has been
under development since 2006 or 2007.

Preparing for Using Facelets

First of all, we must focus on XHTML as a file format, which means that:


Page
3

of
14



All tags must be closed



All tags must
be properl
y nest
ed



All tags and attributes must be lower case



All attribute values must be enclosed in quotes

(single or double)



There must be o
ne root XML element



Since Facelets is based on Unicode numeric entities, you
need to convert the Latin character entities to
Unicode numeric code points. For instance: &nbsp; becomes &#160;



XML namespaces must be specified

for all taglibs, using the “xmlns
=” construct rather than the JSP
-
specific taglib construct


Within MyEclipse

and other IDE’s
, these conditions are verified by th
e validation code in the editing tools.

Concepts

Facelets can be best understood as a tag and element
-
tree based process
ing

eng
ine, that will r
ip through an XHTML
file and generat
e the input

to the JavaServer F
aces component processor, while also interpreting a number of special
tags
,
which control functions
such as file including, region nesting, region content subst
itu
tion, etc.

Some of the
special
tags

will “wrap” other content around a specified set of content.

Since an XHTML fi
le is by definition a
valid tree

of starting and ending tags, most of the behavior

of

the Facelets engine can be described in terms of what
happens at

the start, middle, and closing of a subtree.


While the Facelets engine is processing

the input for a page
, run
-
time expressions are available using the Expression
Language.

These allow for conditional processing and inclusion based on run
-
time variables
.

Processing Lifecycle

Under the JavaServer Faces specification, there are some preliminary steps that must be covered when building
views. This section will cover that process and its lifecycle in relation to Facelets.


1.

A request comes in to JavaServer F
aces for a new view (or page).

The
FaceletViewHandler

simply
creates a new
UIViewRoot

for this new view.

2.

Since this is a new view being requested, we immediately render our view.

Before rendering, Facelets
needs to populate the view with components. At t
his time, the
FaceletFactory

is used to build a
Facelet

that will act as build instructions for the desired view. The
UIViewRoot

is applied to the
Facelet

and the view is populated for rendering.

3.

The
UIViewRoot

(view) is then asked to render itself back to

the response.

4.

The user sees a completed web page and the state of the view is automatically stored for the next request.
Note, all the inlined text and other transient components will not be stored, only 'crucial' component
information such as input compo
nents and form data.

5.

The user clicks a button, causing a second request to come back to JavaServer Faces. This time, the view is
restored from the previously stored state. Keep in mind, the view at this point only has the 'crucial'
components available fro
m the previous request.

6.

This restored view is passed through the JavaServer Faces lifecycle and eventually we will either generate a
new view for another page, or re
-
render your current view if there were validation problems or no action
was fired.

7.

In the
case of re
-
rendering the view, the partial view that was restored is now rendered again. Before it's
rendered, the same
Facelet

is used to re
-
populate the full view with inlined text and transient
components.

8.

The
UIViewRoot

(view) is then asked to render i
tself back to the response.

9.

Repeat this process until another (new) view is requested.


The first take
-
away from those steps is that the same
Facelet

can be used multiple times with the same view.
Basically, the process of building the view (a.k.a componen
t tree) can go through many cycles of populating,
rendering, trimming for state saving, then restored again
--

repeat.


Page
4

of
14

There is a fundamental difference in the behavior of the Facelets ui:include tag and the JSP static or dynamic
includes.

Unlike the sta
tic JSP include, which is included at compile time, the Facelets include operates at runtime.
Unlike the JSP dynamic include, which appends to the response when it is invoked, the included view adds on to a
component tree that is written out only after the

tree is completely constructed.

Mapping HTML to JSF Components

There doesn’t appear to be built
-
in mapping between HTML tags and JSF components, so you specify the JSF
component name as the value of the “jsfc” attribute.


This implies that when we are con
verting old pages from HTML to JSF, rather than rewriting all of them, it would
be more effective to put in the jsfc markings.

Using the
Expression Language

Facelets utilizes the new EL Specification and will continue to support it in future revisions.

Th
is may include extra
language extensions such as method invocation and inlined sets, for example.


With the new EL Specification, the use of
#{...}

and
${...}

are both supported and Facelets makes no
distinction between the two.

The short of it is that y
ou can freely interchange the two with whatever is most familiar
to what you're working on.

Both syntaxes will be handled the same way and share the same lifecycles and features.


Inlining Text


Text and expressions can exist anywhere in the document.

T
his means you can have an example like below, and
have Facelets correctly evaluate it at render time.


<span>Your Basket has #
{basket.lineCount} Items</span>


EL Lifecycle


Facelets provides a unique lifecycle to EL.

When building a
UIComponent

tree, all

EL expressions are re
-
built
based on the state of the current
FaceletContext
.

These expressions are either stored on things like
UIComponents

or stored in the component tree as text.

When it is

time to render, then these expressions are
evaluated as the

second phase.

This offers the truest form of variable/state management in relation to tree building
within JavaServer Faces.

This is also a feature that is not supported within JSP for inlined text.

Example
s

of Using Facelets

Changing HTML to JSF

This
might be considered the most direct use of Facelets. In

this case, we use the jsfc attribute on
a set of
HTML
elements
.


<form jsfc="h:form" id="login">


<input type="text" jsfc="h:inputText"


id="lastName"


value="#{personBackingBean.person
Name.lastName}"/>


<input type="submit" jsfc="h:commandButton"


id="submit"


action="success" value="Submit"/>

</form>


When you run this souped
-
up XHTML page through Facelets, it swaps the markup for the
JSF
component
s of the
specified type.

In this case
you
would get an h:form, an h:inputText, and a h:commandButton, while the input file
would still be viewable in Dreamweaver.


Page
5

of
14

What about cases where the mapping between the tags isn’t one to one? It seems like this a
pproach works best
when the elements to be mapped are buttons, links, and inputs, but more complex layouts would be a challenge.


After several rounds of testing, we found the following limitations to the HTML to JSF mapping:



There is no way to add jsfc at
tributes to elements of a table and create a JSF h:dataTable configuration



If you try to convert a <a>text</a> link into an h:commandLink by placing the jsfc attribute on the <a> tag,
the result is a commandLink but the href of the <a> tag doesn’t become p
art of the commandLink.

This
same problem was true even when “action=” was specified on the <a> tag.


So in practice we found that the Facelets goal of converting HTML web pages was not particularly feasible.

Instead,
the approach taken in Wicket seemed
to be a better one, in which you don’t annotate with the JSF component class,
you annotate with an id of a Java class that provides behavior and extends or overrides information in the HTML
element.

Using the Repeat Tag in Facelets to Produce a Menu

The fo
llowing example iterates over the modules of the configuration, which are accessible through the
mainDispatcher. The repeat tag provides an iteration construct similar to the JSTL iterate tag. In this case, we
generate an h:commandLink for each module in

the iteration, which produces a label and a link on the screen. The
visual appearance is controlled by the <div> and <span> elements, so that other visual layouts can also
be
produced.


<div>


<ui:repeat value="#{mainDispatcher.modules}" var="module">



<span style="margin: 0px 8px;">

<h:commandLink action="#{mainDispatcher.action}" value="#{module.label}">



<f:param name="name" value="#{module.name}" />


</h:commandLink>


</span>


</ui:repeat>

</div>

Conditional Elements

In JSF, the primary way to
have a page change its layout or displayed content is to use the “render” attribute on the
JSF component, which can take an EL expression to determine if the component should be rendered.


Facelets goes one step further and allows you to conditionally incl
ude or not include the JSF in the first place, by
using JSTL conditional logic tags around the components or Facelets tags. For instance, consider the following:


<html xmlns="http://www.w3.org/1999/xhtml"


xmlns:c="http://java.sun.com/jstl/core"



xmlns:ui="http://java.sun.com/jsf/facelets"


xmlns:h="http://java.sun.com/jsf/html"


xmlns:f="http://java.sun.com/jsf/core" xml:lang="en" lang="en">



<h:form>


<c:if test="#{post.itemCount < 5}">



<h:commandLink action="#{post.crea
tePost}" value="New Post" />


</c:if>


<br/>


<hr/>


<h:dataTable value="#{post.posts}" var="item" border="1">




… details omitted …




</h:dataTable>


<h:form>

</html>




Page
6

of
14

In this example, yo
u cannot create new posts after 5 posts have been made. Note that the conditional tag has the “c”
namespace prefix, which refers to
http://java.sun.com/jstl/core
. While this example could have been done with

the
“rendered” attribute, the next example is more complex.


You can combine JSTL’s conditional logic expressions with the Facelets control tags, such as ui:include. In the
example below, the ‘include’ is made only if the ‘tabBean’ is not empty.


<c:if t
est="#{tabBean.notEmpty}">


<ui:include src="#{tabBean.component}">


<ui:param name="bean" value="#{tabBean.componentBean}"/>


</ui:include>

</c:if>


Since ui:include does not support a "rendered" attribute, this would be the only approach to use.

Exa
mple of Including a
nother File

This is a simple example of embedding one file into another:


<ui:include src=”footer.xhtml”>


Where footer.xhtml is:


<p>
Copyright (C) Jeffrey Risberg
</p>

Decoration Example

In this case, the contents of another file can be
used as a “macro” that is inserted “around” a
specified block of text.


<ui:decorate template
=”border.xhtml”>


<ui:define name=”body” />



This is a line of text


</ui:define>

</ui:decorate>


Where border.xhtml is:


<
table

xmlns:ui="http://java.sun.com
/jsf/facelets"
>


<tr><td bgcolor
=”red”>&#160
;</td></tr>


<tr><td><ui:insert name=”body”

/>
</td></tr>


<tr><td bgcolor=”red”>&#160
;</td></tr>

<
/
table>


This shows several important aspects of Facelets, first of all the use of numeric entities, also the s
pecification of the
“ui:” namespace. Without these the processing will generate an error.


A slightly more
X
HTML
-
appropriate

example would be the following for border.xhtml:


<html xmlns:ui="http://java.sun.com/jsf/facelets">

<body>



<ui:composition>



<
table>



<tr><td bgcolor="red">&#160;</td></tr>



<tr><td><ui:insert name="body" /></td></tr>



<tr><td bgcolor="red">&#160;</td></tr>



</table>



</ui:composition>

</body>

</html>


Page
7

of
14

This could be processed by Dreamweaver because it has the full html

and body tags, and to cause these to not be
generated in the output, the
ui:composition

tag specifies that all elements outside of it will be ignored.
Otherwise these would be placed into the source, and the browser would have to ignore it. We will see
how the
ui:composition

tag is used in templating, below.

Templating Example

This is p
erhaps the most common way to use Facelets.

The templating facility is similar to that provided in Struts or
Tiles, but is better tied in to the expression language.


Her
e is the file
l
ayout.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">

<head>


<t
itle><ui:insert name="title">Default Title</ui:insert></title>


<link rel="stylesheet" type="text/css" href="./css/main.css"/>

</head>


<body>

<div id="header">


<ui:insert name="header">



<ui:include src="header.xhtml"/>


</ui:insert>

</div>


<
div id="left">


<ui:insert name="navigation" >


<ui:include src="navigation.xhtml"/>


</ui:insert>

</div>


<div id="center">


<br />


<span class="titleText"> <ui:insert name="title" /> </span>


<hr />


<ui:insert name="content">



<div>


<ui:
include src="content.xhtml"/>


</div>


</ui:insert>

</div>


<div id="right">


<ui:insert name="news">


<ui:include src="news.xhtml"/>


</ui:insert>

</div>


<div id="footer">


<ui:insert name="footer">


<ui:include src="footer.xhtml"/>


</
ui:insert>

</div>

</body>

</html>


The portions that get filled in here are the
ui:insert

regions. Each has a region name. If there is defined content
under that region name it will be emitted in the place of the
ui:insert

subtree. If there is no define
d content under
that region name, the Facelets engine will proceed to the
ui:include

subtree. That will fetch the contents of a file
if present.


Here is a file that uses the above:


Page
8

of
14

<!DOCTYPE html PUBLIC "
-
//W3C//DTD XHTML 1.0 Transitional//EN"


"h
ttp://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:f="http://java.sun.com/jsf/core">


<ui:compositi
on template="/WEB
-
INF/layout/layout.xhtml">


<ui:define name="title">CD Form</ui:define>


<ui:define name="content">



<h:form id="cdForm">



<h:inputHidden id="cdid" value="#{CDManagerBean.cd.id}" />




<h:outputLabel for="title" styleClass="label" valu
e="Title" />




<h:inputText id="title" value="#{CDManagerBean.cd.title}"





required="true" />




<h:message for="title" styleClass="errorText" />



<br />




<!
--

button that when clicked will cause the addCD method to get invoked.
--
>



<h:commandButto
n id="submitAdd" action="#{CDManagerBean.addCD}"




value="Add CD" rendered="#{not CDManagerBean.editMode}" />




<h:commandButton id="submitUpdate" action="#{CDManagerBean.updateCD}"




value="Update CD" rendered="#{CDManagerBean.editMode}" />


</h:form>


</ui:define>

</ui:composition>

</html>


Note the reference to
ui:composition

and
ui:define
.

The composition tag declares this page t
o be one which
is assembled fro
m

a layout, and the
ui:define

tag provides the content for one of the regions of assembly.

The
composition tag also indicates that no content outside the tag should be preserved.

Component Example

This example shows how a UI component such as a menu could be defined in a Facelets file, and then used in other
files.


<ui:component binding="#{ba
ckingBean.menu}">


<ul id="mainMenu">


<c:forEach var="link" items="#{menuOptions[role]}">


<c:choose>



<c:when test="#{link.id == page}">



<li class="current"><a href="#{link.uri}">#{link.text}</a></li>



</c:when>



<c:otherwise>



<li><a href="#{
link.uri}">#{link.text}</a></li>



</c:otherwise>


</c:choose>


</c:forEach>


</ul>

</ui:component>


The above file is the definition file, and it contains the co
mponent tag. This also defines

what binding is present, so
that information can be passed
in from the invoking file.

Configuring the Facelets L
ibrary

Parameters include:

Page
9

of
14



DEVELOPMENT


default is false
. This should be set to true for non
-
productions. Enables the generation
of debug messages.



SKIP_COMMENTS


default is false
. This should be se
t to true for production sites.

Project Setup

t
o Use Facelets

Change the web.xml file as follows:

<web
-
app>





<!
--

Use Documents Saved as *.xhtml
--
>



<context
-
param>


<param
-
name>javax.faces.DEFAULT_SUFFIX</param
-
name>


<param
-
value>.xhtml</par
am
-
value>


</context
-
param>




<!
--

Special Debug Output for Development
--
>


<context
-
param>


<param
-
name>facelets.DEVELOPMENT</param
-
name>


<param
-
value>true</param
-
value>


</context
-
param>



<!

Control the emitting of comments

--
>


<context
-
param>


<param
-
name>facelets.SKIP_COMMENTS
</param
-
name>


<param
-
value>true</param
-
value>


</context
-
param>





<!
--

Optional JSF
-
RI Parameters to Help Debug
--
>


<context
-
param>


<param
-
name>com.sun.faces.validateXml</param
-
name>


<param
-
v
alue>true</param
-
value>


</context
-
param>


<context
-
param>


<param
-
name>com.sun.faces.verifyObjects</param
-
name>


<param
-
value>true</param
-
value>


</context
-
param>





<!
--

Faces Servlet
--
>


<servlet>


<servlet
-
name>Faces Servlet</servlet
-
n
ame>


<servlet
-
class>javax.faces.webapp.FacesServlet</servlet
-
class>


<load
-
on
-
startup>1</load
-
on
-
startup>


</servlet>





<!
--

Faces Servlet Mapping
--
>


<servlet
-
mapping>


<servlet
-
name>Faces Servlet</servlet
-
name>


<url
-
pattern>*.jsf</ur
l
-
pattern>


</servlet
-
mapping>

</web
-
app>



This has the effect of enabling
.xhtml files to be treated as
valid JSF file
s
. It also defines other settings that are also
applicable to JSF.


Change the faces
-
config.xml file as follows:


<faces
-
config>




<application>


<view
-
handler>


com.sun.facelets.FaceletViewHandler


</view
-
handler>


</application>

</faces
-
config>

Page
10

of
14

Support for Facelets in MyEclipse

There is an option within MyEclipse to add Facelets support
to a project
when adding JSF
capabilities, or to add
Facelets after the fact.

This is quite important and useful, as it helps makes sure that the
project’s
configuration files
are correctly changed, as well as the libraries on the build path.


It also creates a servlet mapping called

“*.faces” to request Facelets and JSF engine processing. Te files themselves
are start ending in .xhtml.


When creating a page, you can specify that i
t will use the
Facelets

template
,

rather than any other templates such as
a JSF template.

This will giv
e you page that has all of the namespace definitions set up.


The JSF designer has been extended as of MyEclipse
5.5

to support Facelets, as part of the Visual JSF Designer
.

Some documentation seems to call this the MyEclipse JSF/Facelets Designer, but th
at name doesn’t appear in
MyEclipse itself.


All Facelets/XHTML pages need to be opened with the non
-
default MyEclipse

Visual JSF

Designer.


By default all
XHTML pages are opened in the MyEclipse Visual XHTML Designer.


This is just a generic XHTML designe
r and
doesn't have any specific support for Facelets development.


Instead open Facelets/XHTML pages by using the
open
-
with menu to select the MyEclipse
Visual JSF

Designer.


After opening the file using this method once, all
subsequent openings of that fi
le will use the MyEclipse
Visual JSF

designer automatically.


The MyEclipse

Visual JSF

Designer features include a
Drag
-
and
-
Drop

palette, split view source/design, and related
toolbar.


The palette has JSF HTML and Core library support as well as the subs
et of JSTL supported by Facelets.

The palette doesn’t have entries for the Facelets tags, however.


The MyEclipse Visual JSF

Designer offers Code
Assist for all Facelets, JSF, JSTL tags.


Make sure that you have
the proper namespace added

to your <html> t
ag to enable Code Assist.


Code
Assist is available for Facelets, JSF, JSTL taglibs and also all associated tag attributes.

Reference Guide to Facelets

Tags

These have been organized with
our most
-
used
tags first.

ui:include

The UI Include tag is a server
-
side include tag for Facelets.

It simply includes the document pointed to by the "src"
attribute as part of the current JSF page.

The included document should use a component or composition tag to trim
unnecessary markup, or it may simply contain a fragm
ent of XHTML or XML to be included.

ui:decorate

The UI Decorate tag is a templating tag that
can be used to provide decoration such as a border around some other
content. The decorate tag takes a “template” attribute to specify the decoration file. You use

child

ui:de
fine tags to
pass named content to the associated template.

See ui:insert for more information.

ui:insert

The UI Insert tag is the basic tag for getting text replacement in the output. It takes an attribute which is the named
content to look
up and emit at this point in the processing.

If you set this attribute same as defined in
a
ui:d
efine

tag then that content within
the
ui:
define

tag will be included.

If it doesn't match then the content specified
within
opening and closing tag of the
ui
:
insert

tag will be displayed
, as a fall
-
back.

ui:define

The
UI
Define tag is a templating tag that defines named content to be inserted into a template.


The name attribute
value must match that of a
ui:insert

tag in the target template for the named cont
ent to be included

Page
11

of
14

ui:composition

The UI Composition tag calls for processing similar to the UI Decoration tag (meaning that it takes a “template

attribute and a set of child
ui:define

children, but it also causes all content outside of it to be ignored b
y the
Facelets view handler. This essentially makes the template specified become the top
-
level content of the output.

ui:component

The UI Component tag is used to define a reusable
definition component.
The component tag behaves much like the
compositio
n tag (used without the template attribute).


The difference is that it inserts a new UIComponent into the
component tree that is the root of all components within it.


The essential difference between a ui:composition and a
ui:component is that multiple c
ompositions can be combined to form a single component tree, but each
ui:component forms an independent component tree.

Also, the ui:component tag supports the binding attribute,
which can be used to reference the component tag as a property in a
JSF

back
ing bean
.

ui:fragment

The

UI
Fragment

tag has the same behavior

as ui:component
, except it is non
-
trimming
.

ui:param

The UI Param tag is used to pass objects as named variables between Facelets.

With the
param

tag, you can pass
objects as variables instea
d of just fragments of content.

You can use the
param

tag wherever a
define

tag is
used within
composition

or
decorate

tags, in addition to passing objects to an
include

tag.


For instance, in the following example:


<ui:include src="/WEB
-
INF/siteNav.xhtm
l">


<ui:param name="user" value="#{currentUser}"/>


<ui:param name="page" value="home"/>

</ui:include>


The variable “user” will be the current user object, and the variable “page” will be the string “home”.

ui:remove

The UI Remove tag is used to sp
ecify tags or blocks of content that should be removed from your page by the
Facelets view handler at compile time.

This tag has no attributes.

You can use this tag within the "jsfc" attribute to
indicate that a particular tag should be removed fro
m the
rendered page

[This does not appear correct


using tags
within an attribute is not something that XML typically does].


This gives you some flexibility to display content and to work with markup in your design environment that will be
omitted once the pag
e is actually viewed by your users.

FaceletsTools will not display any markup that is wrapped
with a
ui:remove

tag in Dreamweaver's design view, but it will display markup containing the "jsfc" variant of this
tag
.

ui:debug

The UI Debug tag allows you to
display helpful information about the JSF component tree and scoped variables in
your browser when you test your JSF pages.

The hotkey attribute specifies a key combination (CTRL + SHIFT + D
is the default value) to display the popup window containing the

information.

The UI Debug tag can be enabled or
disabled by setting the rendered attribute.

Appendix: Example of Application
using Facelets

In this section, we are reviewing the MyBlogFacelets program that is provided with MyEclipse. It implements a
si
mple blog application.


Page
12

of
14

This program has the following xhtml files:



list.xhtml


this lists all of the current blog postings.



new.xhtml


this handles submission of a new blog posting.



template.xhtml


located in the template subdirectory


The data model i
s:



Post.java



has an id, title, contents, and post date


The backing beans are:



EntityManagerHelper.java



provides a wrapper around the typical entityManager



PostDAO.java



carries out all of the CRUD operations on a Post object


The program is using the

TopLink library for ORM rather than Hibernate, but it could be done just as well with
Hibernate.


The total set of objects is described in the diagram below:



The application screens are as follows:

Page
13

of
14


The source file is as follows:


<?xml version="1.0" encoding="UTF
-
8"?>

<!DOCTYPE html PUBLIC "
-
//W3C//DTD XHTML 1.0 Transitional//EN"
"http://ww
w.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:f="http://java.sun.com/jsf/core" xml:lang="en" lang="en">




<f:loa
dBundle basename="messages" var="msg" />




<ui:composition template="/templates/simple.xhtml">


<ui:define name="pageTitle">#{msg.pageTitle}</ui:define>


<ui:define name="pageError">


<h:messages errorStyle="color: red" infoStyle="color: green" layout="t
able"/>


</ui:define>


<ui:define name="pageHeader">#{msg.postListHeader}</ui:define>


<ui:define name="body">


<h:form>


<h:commandLink action="#{post.createPost}" value="New Post"/>


<hr/>


<h:dataTable value='#{post.po
sts}' var='item'


border="1" cellpadding="2" cellspacing="0">


<h:column>


<f:facet name="header"><h:outputText value="Id"/></f:facet>


<h:outputText value="#{item.id}"/>








</h:c
olumn>


<h:column>


<f:facet name="header"><h:outputText value="Title"/></f:facet>


<h:outputText value="#{item.title}"/>


</h:column>


<h:column>


<f:facet name="header"><h:outputT
ext value="Content"/></f:facet>


<h:outputText value="#{item.content}"/>


</h:column>


<h:column>


<f:facet name="header"><h:outputText value="Post Time"/></f:facet>




<h:outputText value="#{it
em.posttime}"/>


</h:column>


</h:dataTable>


<hr/>


</h:form>


</ui:define>




<ui:define name="pageFooter">



<a href="/MyBlogFacelets/index.jsp">Back to index</a>


</ui:define>


</ui:composition>

</html>


In this c
ase, the expression language is being used to get the
information from the “P
ost


backing bean.

Does this
happen in the JSF code or in the Facelets code?

Page
14

of
14

Appendix:

Extending the ViewHandler

The ViewHandler is the Facelets engine.


Extensibility is one of

JSF's greatest strengths.

JSF achieves its extensibility by using default implementations of
pluggable classes to deliver its core functionality.

These classes include implementations of
ActionListener
,
NavigationHandler
,
VariableResolver
,
PropertyResol
ver
,
ViewHandler
, and
StateManager
.

They are surprisingly simple to extend because JSF allows you to decorate the default
implementation.



If the custom pluggable class contains a constructor that takes an argument of the class that it extends, JSF uses

that
constructor and passes in the previously registered implementation.

You can decorate the behavior of the default
implementation with custom logic and delegate to the default implementation.

Additionally, all components
delegate generating client ou
tput to a
Renderer

class, which also is easily replaced by a custom implementation.

If none of the existing components meet your application needs, you can either extend an existing one or develop a
custom component.

In short, just about everything in JS
F can be extended or replaced with a modest effort.


Facelets itself is an example of the extensibility of
JSF. I
t is integrated into JSF as a custom
ViewHandler
.



There are
three

ways to extend Facelets:



Write custom tags



Change th
e behavior of the bui
lt
-
in tags



Change the integration with the EL facilities.