Friday, August 26, 2011

Richfaces CDK Tutorial - "Hello, World!"

I like the JBoss technology stack. The power of the technology is important factor, but sometime the well documented products are giving the competitive edge.

JBoss provide a powerful JSF component development kit (CDK), along their JSF component library (Richfaces), but in oppose to most of their products (such as the AS, Seam, Weld, Richfaces), Richfaces CDK is lacking of a clear documentation. Especially when talking about booting up a new tag library. I haven't found much resources in the net as well, so I decided to write a clear walk-through for using it, for a better web out there.

For those who are impenitent, you can download the working sample immediately from Github at

Lets start!

First, you'll need to create a Maven project. CDK project must be a Maven project, since it automatically generate code for you by a Maven plugin.
I created a parent project, which holds two modules - the tag library and a WAR project to demonstrate it.
Your directory tree should look like:
+-- tags
`-- example


The parent ("cdk") pom.xml should just hold the dependency and repository declarations. It should configure the CDK plugin (which will generate lots of code for you later on).


Next, we'll need to define the tags pom.xml. Mind that only here we are actually using the CDK Maven plugin (while in the parent pom we only set the way we are going to use it). We'll need the CDK annotation JAR, the JSF API and JavaEE web API jar. That's all (for our simple hello world, at least):


And last, we'll need a project to show our wonderful tag we'll produce. I'm deploying it into a JBoss AS 7, which is a JavaEE capable, so no other dependencies (such as JSF libraries) are required. If you're using thinner containers, you should add the needed dependencies to run a JSF application. I added the Maven deploy plugin to deploy the WAR into a JBoss AS 7. You can omit it, if you like.


Our WAR project wouldn't work without the web.xml, located at src/main/webapp/WEB-INF: (nothing fancy, just a standard JSF servlet declaration)


And we'll need a faces-config.xml file at /src/main/webapp/WEB-INF in order to declare its a JSF application. Since we're using JSF 2, we won't need anything declared in it:


Let's put two more files, the index.xhtml and index.jsp files, just to display our tag:


A simple redirection to the index.jsf file.

Ok. We've done with the setups. Now lets create a tag! We will create 3 files, which will be used by the CDK plugin to generate the rest of the code:, and


This file just declare the URI namespace and the package namespace for the plugin. You can read the file as an instruction to use the xmlns "", with a short name of "cdk", for all the annotated classes under the "me.yonatan.tags package". Those definitions will be placed at the taglib.xml file, which will be automatically generated for you.


This is an abstract class that extends the standard JSF UIComponentBase class. The CDK plugin will generate another class that will extend it, and implement automatically whatever needs to be implemented. You can think about this file as the interface of the tag. We'll define there its attributes, its tag name, and which class will render it.
Since our sample here is trivial, the class almost doesn't have any information or logic. In the next posts I'll show more complex usage of it.


The last file, which extends the JSF standard Renderer class. If AbstractHelloWorld was the interface, this is the implementation. This will produce the actual HTML/JavaScript that will produce our tag (in our case, a simple DIV element with "hello, world!" in it).

Well, that's it. Run you Jboss 7, Compile the project with mvn clean package, and go to http://localhost:8080/cdk-example/index.jsf. If you've done everything right (or just download the project from github), you'll see our little "hello, world!" message.

A glance in the project itself, under /target directory of the tags project will reveal generated code: another .java file named UIHelloWorld was created, and the .xml files cdk.taglib.xml and faces-config.xml were generated too during compilation. A quite peek in them will show you that lots of boilerplate code that was saved from you to write (and even more important, to maintain!)

Next time, we'll add more functionality to our component, using nifty JavaScript libraries.

The code -
Community documentation for CDK 4 -
JBoss how-to in their wiki -