Reference Manual for Gracelets - 2.0.0.RC2

1.3 - Introduction : Getting Setup

To get started developing with Gracelets you need at least the following:

Of course if you already have Tomcat or something like JBoss 4.2.0 and your web app is configured to use Facelets and the JSF RI then all you need to get is log4j, commons code and the latest version of Gracelets from the URL above and the version of groovy mentioned above. It is necesary to put gracelets in your WEB-INF/lib directory of the WAR/Web Project you want to use gracelets in.

IMPORTANT NOTE: There is no longer any need to declare any faces-config.xml in order to use Gracelets. You may need to declare such for other parts of your application, but in regards to Gracelets, there is no need for any faces-config.xml.

Once you have the above available to your web app you only need to make minor changes to your web.xml:

Basic web.xml configuration

Here is a basic web.xml for Gracelets:

In your applications web.xml file, you need to setup the Gracelets Application Listener It is important to note that the Gracelets Application Listener is now a requirement for a complete Gracelets setup. You will also normally want to setup the GraceletFilter as shown below, which will provide the enablement of many new features being developed for Gracelets, which includes the already existing exception reporting feature that will give you important information even when the exception is not caught during runtime.

You also need to make sure .groovy is one of the extensions in the VIEW_MAPPINGS list as shown below. You may also want to protect your .groovy source files as shown below by adding a role and a security constraint as many do as well with .xhtml source files:

web.xml
Toggle Line Numbers
1 <?xml version="1.0" encoding="UTF-8"?> 2 <web-app xmlns="http://java.sun.com/xml/ns/javaee" 3 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 4 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" 5 version="2.5"> 6 7 <context-param> 8 <param-name>facelets.VIEW_MAPPINGS</param-name> 9 <param-value>.xhtml;.groovy</param-value> 10 </context-param> 11 12 <context-param> 13 <param-name>javax.faces.DEFAULT_SUFFIX</param-name> 14 <param-value>.xhtml</param-value> 15 </context-param> 16 17 <listener> 18 <listener-class>gracelets.api.servlet.ApplicationListener</listener-class> 19 </listener> 20 21 <servlet> 22 <servlet-name>FacesServlet</servlet-name> 23 <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> 24 <load-on-startup>1</load-on-startup> 25 </servlet> 26 27 <servlet-mapping> 28 <servlet-name>FacesServlet</servlet-name> 29 <url-pattern>.jsf</url-pattern> 30 </servlet-mapping> 31 32 <security-role><role-name>developer</role-name></security-role> 33 34 <filter> 35 <filter-name>GraceletFilter</filter-name> 36 <filter-class>gracelets.api.servlet.GraceletFilter</filter-class> 37 </filter> 38 39 <filter-mapping> 40 <filter-name>GraceletFilter</filter-name> 41 <url-pattern>/</url-pattern> 42 </filter-mapping> 43 44 <security-constraint> 45 <web-resource-collection> 46 <web-resource-name>Facelets</web-resource-name> 47 <url-pattern>.xhtml</url-pattern> 48 </web-resource-collection> 49 <auth-constraint> 50 <role-name>developer</role-name> 51 </auth-constraint> 52 </security-constraint> 53 54 <security-constraint> 55 <web-resource-collection> 56 <web-resource-name>Gracelets</web-resource-name> 57 <url-pattern>.groovy</url-pattern> 58 </web-resource-collection> 59 <auth-constraint> 60 <role-name>developer</role-name> 61 </auth-constraint> 62 </security-constraint> 63 64 </web-app>

GraceletFilter web.xml configuration

When using GraceletFilter you should set it up as above so that it is mapped to filter every request. This allows it to be able to provide features like directory views.

The GraceletFilter by default automatically enables three sub filters that you can disable via filter parameters. One is the ExceptionFilter, which allows you to get exception reporting even when the exception happens during the non-rendering phases of the JSF lifecycle. The second filter is the DirectoryHandlerFilter which allows JSF views (views that end in _directory.groovy) to handle sub paths (using a DIRECTORY_PATH request attribute) and thus become what can be called a directory view. The third one is the ResourceFilter that allows pages rendered in the browser to access gracelet resources.

Below we disable the directory handler filter via its key, "directory_filter":

web.xml fragment
Toggle Line Numbers
`1 <filter> 2 <filter-name>GraceletFilter</filter-name> 3 <filter-class>gracelets.api.servlet.GraceletFilter</filter-class> 4 <init-param> 5 <param-name>directory_filter</param-name> 6 <param-value>false</param-value> 7 </init-param> 8 </filter>`

We could do the same with the exception filter via its key, "exception_filter" or the resource filter via its key, "resource_filter".

The directory filter needs to know what JSF extension you want it to use. It defaults to .jsf, but you can configure it with the "directory_extension" init parameter. For example below we change it to .faces:

web.xml fragment
Toggle Line Numbers
`1 <filter> 2 <filter-name>GraceletFilter</filter-name> 3 <filter-class>gracelets.api.servlet.GraceletFilter</filter-class> 4 <init-param> 5 <param-name>directory_extension</param-name> 6 <param-value>faces</param-value> 7 </init-param> 8 </filter>`

Library Dependancies

The following is a list of jars, and their versions, that Gracelets 2.0.0.RC2 is developed with.

Maven Dependencies
Group Id	Artifact Id	Version
apache-codec	commons-codec	1.2
org.codehaus.groovy	groovy-all	1.5.7
javax.faces	jsf-api	1.2_13
javax.servlet	servlet-api	2.5
javax.el	el-api	1.0
com.sun.facelets	jsf-facelets	1.1.15.B1
org.slf4j	slf4j-api	1.5.8

^{Generated by Gracelets Documentation Generator - 08/27/2009 08:28PM CDT}