Project Documentation

Commons

Jelly Tutorial

The best way to get acquainted with Jelly, and get an idea what it can be
used for, is to see it in action. So you want to get started as quickly as
possible? Luckily for you Jelly comes with several demos that can be run
from the command line using Maven.

If you don't have Maven installed, you should check out the
Getting Started guide first.

The goal of the tutorial is to guide you through running some of the Jelly
demos and give you some ideas of other potential uses of Jelly (and
hopefully make your first experience with Jelly enjoyable and fun).

Once you have tried a few of demos, you can explore Jelly further by writing
some Jelly scripts on your own, or by modifying some of the demos provided.
You may also want to define your own Jelly taglib, and in some cases
you may want to know how to embed Jelly into your own Java program (tutorials
on how to do these things are in the works).

To see a list of the Jelly demos that you can run, type "maven -g" in the
Jelly root directory (there should be a project.xml file there). Among the
other maven goals, you will see the the demos available under the "demo"
goal (incidentally, Maven is a project automation tool that uses Jelly as
its xml processing engine, and Jelly in turn uses Maven as its build tool.
Neat!)

JellySwing

The JellySwing demo shows how you can use Jelly (using the JellySwing library) to build the UI for a Swing java program.

Why would you want to do this? If you have ever written a large Swing
application, you will probably agree that coding a GUI in java can be a tedious task.
Jelly allows you to define the View (in an MVC approach)
in XML and bind it to a Model and Controller written in Java. Or you can
define actions (Controller) directly in Jelly by using the <action> tag.

Jelly is also a great way for a designer to prototype a UI and avoid the
learning curve of Java. In fact, a designer could develop a full-featured
application using a rich set of functions and beans exposed via jelly tags.

To run the swing demo, go to directory jelly-tags/swing and type "maven demo:swing"
(View the demo script). You should see a window open with
some swing components. You can test the actions by selecting a menu item or
pressing the button. The actions in this demo simply output a message to the
console. A more practical action could be to invoke a bean, call a script
that opens another window, etc.

If you look at the jelly code for this demo, you will see
that building a UI is pretty simple. For example, a menu bar is simply:

The nice thing about this is that any component (or model in this case) that
is not available in the JellySwing taglib or is too complex to express using
Jelly, can be written in java and added by this method.

Jelly Runner

The Jelly Runner is a JellySwing interface that lets you run other Jelly scripts. Just select a file in the file dialog and click the Run Script button

Homepage Builder (JellySwing Edition)

This is a good chance to use the Jelly Runner. Find HomepageBuilder.jelly, which is located in /src/test/org/apache/commons/jelly/demos/ (View the demo source).

As you can see, the HomepageBuilder is a (mini) fully-functional swing application, and it's entirely written in Jelly! This example uses Jelly on two levels: 1) For the actual application/UI and 2) As a templating engine to build homepages.This shows how you can use different taglibs together to build sophisticated applications.

See the section on Embedding Jelly to find out more about the Homepage Builder demo. This is also a good way to compare a Java implementation (HomepageBuilder.java) with a Jelly implementation (HomepageBuilder.jelly).

Other Ideas for JellySwing

You could write a taglib to allow you to bind data to various models
(TreeModel, TableModel, etc) using Jelly.

You could allow the end user of an application to easily customize (or localize) the UI, and even add
custom actions from a library of possible actions!

You could you use JellySwing implement a "thin client", so that the entire UI of an application
can be downloaded from a web server at runtime. In some applications, this would provide a lot of flexibility.

Embedding Jelly

There are cases where you may want to execute Jelly scripts from within a java program (as opposed to doing it from Maven or the command line). This tutorial presents a simple example of a program that does this.

This example is another "Home Page Builder". Previously, we used JellySwing to create the Home Page Builder. This time we will create the Swing controls in Java and only use Jelly to output the HTML.

When you run the program, it will open a window where you can choose a template, and specify a few paramters. Then you simply click on "build page" and voila, your home page is generated by Jelly.

As you can see, it's pretty straighforward to call a Jelly script programatically. First you need a context to run the script in. You can think of the context as the "environment" in which the script runs. The script can use and modify variables in the context however it wishes. Then you need an XML output stream where the output of the script will be sent. In some cases, like this one, the XML output is the essential product of the script. In other cases, it may just be a "byproduct" of running the script, used for logging, etc. This is the case when you are running a maven build, for example.

After you have explored this demo and its implementation, you may want to compare it with the same example implemented using the JellySwing library, above (if you haven't already done so).

Transforming XML With JSL

With the JSL tag library, you can transform XML documents in an XSLT-like manner.

To run the demo type "maven demo:jsl" (View the demo source). The demo transforms the demo source into HTML and ouputs it to the command line, like this:

Of course, this HTML could just as easly be going to a file or out to a browser in a HTTP response.

If you look at the JSL tag library documentation, you'll see that the JSL taglib consists of a mere four tags: style, template, stylesheet, and applyTemplates. Since many of the standard XSLT tags are already part of other Jelly taglibs, such as forEach and choose, these are the only others we really need. Moreover, much of the power of XSLT comes with using XPath expressions, which are natively supported by Jelly.

There are many good books and tutorials on XSLT, and since the concepts are the same, I won't waste Jelly documentation space and time on this subject.