Reference Manual for Gracelets - 2.0.0.RC2

1.1 - Introduction : What is Gracelets

Gracelets is the fusion of two mainstream technologies, Groovy + Facelets/JSF. It allows Groovy scripts to be used instead of XHTML/JSP views, Facelet tag libraries and JSF component libraries. Gracelets has also been described as a DSL (Domain-Specific Langage) for JSF/Facelets.

Gracelets has the goal of facilitating development of web based applications using the Java Server Faces framework. It allows one to use many Groovy language features (like closures) as complements and/or replacements for some JSF/Facelets features (like EL) that can become very cumbersome and restrictive in many scenarios.

If you are familiar with JSF/Facelets and Groovy you can skip the rest of this article and continue on to the next section.

It is beyond the scope of this manual to describe in detail JSF, Facelets and Groovy. Thus if you do not know much about any or all of these great technologies please follow the links above where they are first mentioned to begin learning about them.

That said, with the following we will attempt to demonstrate some of the benefits of using Gracelets when using these technologies. JSF/Facelets provide a powerful component-based and templating technology. Groovy simplifies programming in the Java language by providing advanced features which allow one to practically accomplish the same task without as much boiler-plate code as in regular Java and allowing java code to be hot-reloadable and more loosely coupled with the surounding framework. As you can imagine, combining these technologies provides for many productive possibilities resulting in less time coding, more options for prototyping and testing and a greatly facilitated component development and templating complementing JSF/Facelets.

A few examples will illustrate this.

Views & Controllers

Gracelets automatically resolves using the Unified EL when resolving variables in gracelet scripts. Also Gracelets adds a controller solution to the mix allowing one to developer reloadable controllers and easily reference them in gracelet views. This variable resolution makes development alot easier since you do not have to link in libraries in order to use different backing beans in your JSF application. You do not have to use @In-jection or @Out-jection in order to interact with the EL environment, including when referencing component frameworks like Seam.

The reloadable controllers allow you to develop a controller and fix bugs without having to redeploy your web application. Below we see how you would define a backing bean/controller in basic JSF and then using Gracelets and then how you could use either one of them inside a Gracelets View.

JSF Backing Bean

faces-config.xml

In normal JSF we have yet another xml artifact which is necesary in order to for the backing bean to get resolved in the JSF application EL. Next we define the java class that will serve as the backing bean.

JSF Backing Bean/Controller

Above we define a JSF backing bean which is referenced in the faces-config.xml. An obvious draw-back is the xml file management for each and every backing bean and that if we make changes to the backing bean we will then have to redeploy our web application.

Gracelets Controller

Gracelet Controller Definition

Here we use a groovy script (reloadable and all) to define our controller. It is also automatically detected by the Gracelets system (when put in the WEB-INF/gracelet/controller directory and it's name must end en Controller.groovy). We can outject and inject simply by assiging to or referencing non-declared variables and we have the power of groovy, like not having to declare common getter/setting methods.

Gracelet View using Controller

Gracelet View

Here, whether its a Gracelet Controller or a JSF backing bean or any other type of JSF controller the view can use them. We also have the power of closures, instead of EL, which gives us the ability to use any valid java/groovy code inside the closure.

Templating

In JSF/Facelets you would normally do templating by one of two means. You could write a simple view in the same directory as your root web application and then use Facelets <u:composition template="/path/to/template.xhtml"/> tag. Or you could create a tag library. The template file is nice, but it would only be usable by your single application and all the files that use it have to use a somewhat hard coded path. The tag library option allows you to abstract your templates, but you have to manage an xml file and import a namespace into each and every view that uses it.

Above we define a Gracelet Component Library. This library can contain an array of easy to define yet powerful components and templates. Here we are simply defining a reusable template. We also define a namespace and an alias. The alias allows us to use the components in this library without memorizing a long namespace and having to define it in all of the views that use it.

Gracelet View using Gracelet Library

Above we use the alias to reference the gracelet library we defined. We can put this Gracelet library in a jar, as a compiled groovy-java class and the like. It is also reloadable, if we modify the library any views that rely on it will be rebuilt on the next web request after the change. This also allows our views to not have to declare so much to start using the templates and is less connected to the location of the template itself. These benefits are in addition to the fact that we are using groovy and all the power behind it.

Component Development

Any JSF component developer knows that you must manage alot of xml artifacts and that like controllers, you many times have to redeploy your entire app as you make changes and fix bugs. The following shows what is involved in defining in the normal JSF/Facelets fashion a button component that uses the html 'button' tag instead of the 'input' button tag. Then after it shows how easy it is to define it in a Gracelet Component Library.

JSF/Facelet Library Example

JSF Renderer in Java

Here we create a Renderer class implementation that will render an html "button" tag and handle event propagation when the button is clicked.

faces-config.xml Renderer entry

Here we configure our faces-config.xml file with a 'renderer' entry to define our renderer.

Facelets tag config

Now we do the final part of our renderer setup telling facelets that when the 'button' tag is used with this library namespace it should create a faces Command component and use our renderer-id referencing the renderer we created above.

Simplified Gracelets Component Example

Gracelet Button Component

Here, in a single file, and in less than half of the Java code needed we define the button renderer and command component, assign it the button tag name and it is automatically available with this library. We have the power of groovy and we can change the component and see the changes implemented without having to redeploy the application.

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