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:
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":
We could do the same with the exception filter via its key, "exception_filter" or the resource filter via its key,
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: