JSF Example

JSF Example Structure

To better learn MyFaces, I've copied the JSF example included with the Sakai distribution. It breaks down as follows:

example:
	maven.xml
	project.xml

example/src/bundle/org/sakaiproject/tool/example/bundle:
	Messages.metaprops
	Messages.properties
	Messages_ca.metaprops
	Messages_ca.properties
	Messages_de.properties
	Messages_es.properties
	Messages_fr.metaprops
	Messages_fr.properties
	Messages_fr_CA.metaprops
	Messages_fr_CA.properties
	Messages_ja.metaprops
	Messages_ja.properties
	Messages_nl.metaprops
	Messages_nl.properties
	Messages_zh_CN.metaprops
	Messages_zh_CN.properties

example/src/java/example:
	Clock.java
	ExampleBean.java
	Grade.java
	PagerBean.java
	SimplePropsBean.java
	ViewSourceServlet.java
	Wizard.java

example/src/webapp:
	alphaIndex.jsp
	anchorReference.jsp
	applet.jsp
	buttonBar.jsp
	buttonBarItem.jsp
	dataLine.jsp
	debug.jsp
	docProperties.jsp
	docSection.jsp
	docSectionTitle.jsp
	dynaDataTable.jsp
	dynaTable.jsp
	example_template.jsp
	flatList.jsp
	hideDivision.jsp
	index.jsp
	inputColor.jsp
	inputDate.jsp
	inputFileUpload.jsp
	inputRichText.jsp
	messageInstruction.jsp
	outputDate.jsp
	pager.jsp
	panelEdit.jsp
	panelTitle.jsp
	popup.jsp
	progressBar.jsp
	script.jsp
	selectCommand.jsp
	stylesheet.jsp
	timerBar.jsp
	title.jsp
	titleBar.jsp
	toolBar.jsp
	toolBarItem.jsp
	toolBarMessage.jsp
	toolBarSpacer.jsp
	view.jsp
	viewContent.jsp
	viewTitle.jsp

example/src/webapp/WEB-INF:
	faces-config.xml
	web.xml

example/src/webapp/css:
	sakaix.css

example/src/webapp/include:
	foot.inc
	head.inc

example/src/webapp/tools:
	sakai.sample.jsf.widgets-2.xml

Maven Project

The following dependencies are required for MyFaces:

groupId	artifactId	Version	Comment
sakaiproject	sakai	sakai.version	Brings in the plug-in.
servletapi	servletapi	2.4	Used for JsfTool, etc.
myfaces	myfaces-all	1.1.1	MyFaces JSF dependencies
sakaiproject	sakai-jsf-widgets	sakai.version	Sakai tag library
sakaiproject	sakai-jsf-widgets-myfaces	sakai.version	Adaptor to use tag library with MyFaces
commons-digester	commons-digester	1.6
commons-codec	commons-codec	1.3
jstl	jstl	1.1.2	Java Standard Tag Library
commons-beanutils	commons-beanutils	1.7.0
commons-el	commons-el	1.0	Expression Langauge: Provided by the servlet container by default.
commons-validator	commons-validator	1.3.0	New for myfaces 1.1.1 update
commons-lang	commons-lang	sakai.commons.lang.version	New for myfaces 1.1.1 update
oro	oro	2.0.8	A set of text-processing classes that provide Perl5 compatible regular expressions.

The below JSF-related depencencies should only be bundled in the webapp if it is being used OUTSIDE of Sakai. When deployed inside of Sakai, or using the Sakai maven plugin, these jars are deployed by Sakai automatically.

groupId	artifactId	Version	Comment
commons-fileupload	commons-fileupload	1.0	Apache Commons file upload used by inputFileUpload tag and associated filter.
commons-collections	commons-collections	3.1
commons-logging	commons-logging	1.0.4

Six other dependences are included, but commented out. These are all for the Sun Reference implementation of JSF.

The web.xml File

Three servlets are defined in the web.xml file:

Name	Class	Comment
sakai.sample.jsf.widgets-2	org.sakaiproject.jsf.util.JsfTool	The Sakai JSF tool.
Faces Servlet	javax.faces.webapp.FacesServlet	The standard Faces controller.
View Source Servlet	example.ViewSourceServlet	A servlet to view JSF sources.

The following servlet mappings are defined:

Name	Specification
Faces Servlet	*.faces
Faces Servlet	*.jsf
View Source Servlet	*.source

The following filter mappings are defined:

Name	Filter Class	Dispatch	Comment
sakai.request	org.sakaiproject.util.RequestFilter	REQUEST,FORWARD,INCLUDE	Standard Sakai requests.
extensionsFilter	org.apache.myfaces.component.html.util.ExtensionsFilter	REQUEST,FORWARD,INCLUDE	MyFaces custom file upload filter, usable with the Sakai JSF inputFileUpload tag! (commented out)

Two listeners are defined:

Listener Name	Comment
org.apache.myfaces.webapp.StartupServletContextListener	MyFaces context lisener.
org.sakaiproject.util.ToolListener	Sakai tool registration (commented out).

The following JSF configurations are made via context parameters:

Parameter Name	Value	Description
javax.faces.CONFIG_FILES	/WEB-INF/examples-config.xml	Comma separated list of URIs of (additional) faces config files. (e.g. /WEB-INF/my-config.xml) See JSF 1.0 PRD2, 10.3.2
javax.faces.STATE_SAVING_METHOD	server	State saving method: "client" or "server" (= default) See JSF Specification 2.5.2
org.apache.myfaces.ALLOW_JAVASCRIPT	true	This parameter tells MyFaces if javascript code should be allowed in the rendered HTML output. If javascript is allowed, command_link anchors will have javascript code that submits the corresponding form. If javascript is not allowed, the state saving info and nested parameters will be added as url parameters. Default: "true"
org.apache.myfaces.DETECT_JAVASCRIPT	false	This parameter tells MyFaces if javascript code should be allowed in the rendered HTML output. If javascript is allowed, command_link anchors will have javascript code that submits the corresponding form. If javascript is not allowed, the state saving info and nested parameters will be added as url parameters. Default: "false" Setting this param to true should be combined with STATE_SAVING_METHOD "server" for best results. This is an EXPERIMENTAL feature. You also have to enable the detector filter/filter mapping below to get JavaScript detection working.
org.apache.myfaces.PRETTY_HTML	true	If true, rendered HTML code will be formatted, so that it is "human readable". i.e. additional line separators and whitespace will be written, that do not influence the HTML code. Default: "true"
org.apache.myfaces.AUTO_SCROLL	true	If true, a javascript function will be rendered that is able to restore the former vertical scroll on every request. Convenient feature if you have pages with long lists and you do not want the browser page to always jump to the top if you trigger a link or button action that stays on the same page. Default: "false"

JSF Pages

The following JSF files are present:

index.jsp
alphaIndex.jsp
anchorReference.jsp
applet.jsp
buttonBar.jsp
buttonBarItem.jsp
dataLine.jsp
debug.jsp
docProperties.jsp
docSection.jsp
docSectionTitle.jsp
dynaDataTable.jsp
flatList.jsp
hideDivision.jsp
inputColor.jsp
inputDate.jsp
inputFileUpload.jsp
inputRichText.jsp
messageInstruction.jsp
outputDate.jsp
pager.jsp
panelEdit.jsp
panelTitle.jsp
popup.jsp
progressBar.jsp
script.jsp
selectCommand.jsp
stylesheet.jsp
timerBar.jsp
titleBar.jsp
toolBar.jsp
toolBarItem.jsp
toolBarMessage.jsp
toolBarSpacer.jsp
view.jsp
viewContent.jsp
viewTitle.jsp

The faces-config.xml File

The faces-config file is pretty simple as such things go. Three managed beans are referenced:

Bean Name	Bean Class	Description
pagerBean	example.PagerBean	Example backing bean for the pager widget
examplebean	example.ExampleBean	Example backing bean for multiple example pages
simpleprops	example.SimplePropsBean	Example simple backing bean for multiple example pages

and navigation rules for the pages listed above.

Of these, all a but index.jsp can be elminated for the purposes of a simple example.

Style Sheet Data

It's not clear why the example references a special style sheet, rather than using the standard Sakai style sheets
contained in the references module. If there are no references in the JSF files, this can likely be eliminated.

Headers and Footers

The header and footer files are intended to reduce labor when entering header and footer information. There is no data
in the footer file and the header contains:

<%-- Example - Rather than including these taglibs on every page,
     I can use a JSP include here for it.  --%>
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<%@ taglib uri="http://sakaiproject.org/jsf/sakai" prefix="sakai" %>

Code

The following code files are included in the examples:

Clock.java
ExampleBean.java
Grade.java
PagerBean.java
SimplePropsBean.java
ViewSourceServlet.java
Wizard.java

Of these, only the PagerBean, ExampleBean, and SimplePropsBean are managed via the faces-config.xml file (see above). In addition to these, the ViewSourceServlet is referenced from web.xml.