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!)
The following tutorials are currently available:
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:
<menuBar>
<menu text="File">
<menuItem>
<action name="New">
... some action ...
</action>
</menuItem>
</menu>
... more menus/menu items
</menuBar>
As you can see, nested elements are automatically added to parent components (unlike Java, where you have to call parent.add(child) ).
For the table, you can see that it was added to the scrollPane using the "new" tag (from the jelly:core taglib):
<scrollPane>
<j:new className="org.apache.commons.jelly.swing.MyTableModel" var="tableModel"/>
<table model="${tableModel}"/>
</scrollPane>
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.
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
To start the JellyRunner type "maven jelly:runner" (View the demo source).
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).
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.
To run the demo type "maven demo:embed" (View the demo source).
The code that actually runs Jelly is the following.
OutputStream output = new FileOutputStream("demopage.html");
JellyContext context = new JellyContext();
context.setVariable("name",nameField.getText());
context.setVariable("background",colorField.getText());
context.setVariable("url",urlField.getText());
// Set the hobby list
Vector v = new Vector();
Enumeration enum= listModel.elements();
while (enum.hasMoreElements()) {
v.add(enum.nextElement());
}
context.setVariable("hobbies", v);
XMLOutput xmlOutput = XMLOutput.createXMLOutput(output);
context.runScript("src/test/org/apache/commons/jelly/demos/"+template), xmlOutput);
xmlOutput.flush();
The Jelly template looks like this:
<?xml version="1.0"?>
<j:jelly trim="false" xmlns:j="jelly:core" xmlns:x="jelly:xml" xmlns:html="jelly:html">
<html>
<head>
<title>${name}'s Page</title>
</head>
<body bgcolor="${background}" text="#FFFFFF">
<h1>${name}'s Homepage</h1>
<img src="${url}"/>
<h2>My Hobbies</h2>
<ul>
<j:forEach items="${hobbies}" var="i">
<li>${i}</li>
</j:forEach>
</ul>
</body>
</html>
</j: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).
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:
<html>
<body>
<h1>Output</h1>
<small>James Elson
<h2>I am a title!</h2>
<small>Twas a dark, rainy night...</small>
<p>dfjsdfjsdf</p>
<p>fdsfsdfhdsff gyuf uysgf ds</p>
</small>
</body>
</html>
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.
This demo demonstrates the use the handy parse tag in the HTML tag library
To run the demo type "maven demo:html" (View the demo source).
As you can see in the demo script, parsing an HTML file is simple:
<html:parse var="doc" html="index.html"/>
Once you have parsed the document you can treat it the same way as a parsed XML document, i.e. applying JSL transformations, querying the document with XPath expressions, and so on.