<?xml version="1.0"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at
  
       http://www.apache.org/licenses/LICENSE-2.0
  
  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->

<document>

 <properties>
  <title>Jelly Tutorial</title>
  <author email="vonwao@yahoo.com">Otto von Wachter</author>
 </properties>

<body>

<section name="Jelly Tutorial">

<p>
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.
</p>

<p>
If you don't have Maven installed, you should check out the
<a href="gettingstarted.html">Getting Started</a> guide first.
</p>

<p>
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).
</p>

<p>
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).
</p>

<p>
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!)
</p>

<p>
The following tutorials are currently available:
</p>
<ul>
<li>
<a href="#jellyswing">JellySwing</a>
</li>
<li>
<a href="#embeddingjelly">Embedding Jelly</a>
</li>
<li>
<a href="#jsl">Transforming XML with JSL</a>
</li>
<li>
<a href="#html">Parsing HTML</a>
</li>
</ul>
<br/>

<a name="jellyswing"/>
<section name="JellySwing">


<p>
The JellySwing demo shows how you can use Jelly (using the <a href="libs/swing/tags.html">JellySwing</a> library) to build the UI for a Swing java program.
</p>

<p>
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 &lt;action&gt; tag.
</p>

<p>
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.
</p>

<p>
To run the swing demo, go to directory jelly-tags/swing and  type "maven demo:swing"
(View the <a href="http://svn.apache.org/repos/asf/commons/proper/jelly/trunk/jelly-tags/swing/src/test/org/apache/commons/jelly/swing/example.jelly">demo script</a>). 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.
</p>

<p>
If you look at the <a href="http://svn.apache.org/repos/asf/commons/proper/jelly/trunk/jelly-tags/swing/src/test/org/apache/commons/jelly/swing/example.jelly">jelly code for this demo</a>, you will see
that building a UI is pretty simple. For example, a menu bar is simply:
</p>

<source>
    &lt;menuBar&gt;
      &lt;menu text="File"&gt;
        &lt;menuItem&gt;
          &lt;action name="New"&gt;
           ... some action ...
          &lt;/action&gt;
        &lt;/menuItem&gt;
      &lt;/menu&gt;
      ... more menus/menu items
    &lt;/menuBar&gt;
</source>

<p>
As you can see, nested elements are automatically added to parent components
(unlike Java, where you have to call parent.add(child) ).
</p>

<p>
For the table, you can see that it was added to the scrollPane using the
"new" tag (from the jelly:core taglib):
</p>

<source>
    &lt;scrollPane&gt;
      &lt;j:new className="org.apache.commons.jelly.swing.MyTableModel" var="tableModel"/&gt;
      &lt;table model="${tableModel}"/&gt;
    &lt;/scrollPane&gt;
</source>

<p>
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.
</p>


<subsection name="Jelly Runner">

<p>
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
</p>

<p>
To start the JellyRunner type "maven jelly:runner" (View the <a href="jelly-tags/swing/src/test/org/apache/commons/jelly/swing/run.jelly">demo source</a>).
</p>

</subsection>

<subsection name="Homepage Builder (JellySwing Edition)">

<p>
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 <a href="http://svn.apache.org/repos/asf/commons/proper/jelly/trunk/jelly-tags/swing/src/test/org/apache/commons/jelly/demos/homepageBuilder.jelly">demo source</a>).
</p>

<p>
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.
</p>

<p>
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).
</p>

</subsection>

<subsection name="Other Ideas for JellySwing">

<ul>
<li>
You could write a taglib to allow you to bind data to various models
(TreeModel, TableModel, etc) using Jelly.
</li>
<li>
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!
</li>
<li>
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.
</li>
</ul>

</subsection>

</section>

<a name="embeddingjelly"/>
<section name="Embedding Jelly">

<p>
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.
</p>

<p>
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.
</p>

<p>
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.
</p>

<p>
To run the demo type "maven demo:embed" (View the <a href="http://svn.apache.org/repos/asf/commons/proper/jelly/trunk/jelly-tags/swing/src/test/org/apache/commons/jelly/demos/HomepageBuilder.java">demo source</a>).
</p>

<p>
The code that actually runs Jelly is the following.
</p>

<source>
    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();
</source>

<p>
The Jelly template looks like this:
</p>

<source>
   &lt;?xml version="1.0"?&gt;
   &lt;j:jelly trim="false" xmlns:j="jelly:core" xmlns:x="jelly:xml" xmlns:html="jelly:html"&gt;
     &lt;html&gt;
       &lt;head&gt;
         &lt;title&gt;${name}'s Page&lt;/title&gt;
       &lt;/head&gt;
       &lt;body bgcolor="${background}" text="#FFFFFF"&gt;
         &lt;h1&gt;${name}'s Homepage&lt;/h1&gt;
         &lt;img src="${url}"/&gt;
         &lt;h2&gt;My Hobbies&lt;/h2&gt;
         &lt;ul&gt;
           &lt;j:forEach items="${hobbies}" var="i"&gt;
             &lt;li&gt;${i}&lt;/li&gt;
           &lt;/j:forEach&gt;
         &lt;/ul&gt;
       &lt;/body&gt;
     &lt;/html&gt;
   &lt;/j:jelly&gt;
</source>

<p>
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.
</p>

<p>
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).
</p>

</section>

<a name="jsl"/>

<section name="Transforming XML With JSL">

<p>
With the <a href="libs/jsl/tags.html">JSL tag library</a>, you can transform XML documents in an XSLT-like manner.
</p>

<p>
To run the demo type "maven demo:jsl" (View the <a href="http://svn.apache.org/repos/asf/commons/proper/jelly/trunk/jelly-tags/jsl/src/test/org/apache/commons/jelly/jsl/example.jelly">demo source</a>). The demo transforms the demo source into HTML and ouputs it to the command line, like this:
</p>

<source>
   &lt;html&gt;
     &lt;body&gt;
       &lt;h1&gt;Output&lt;/h1&gt;
       &lt;small&gt;James Elson
         &lt;h2&gt;I am a title!&lt;/h2&gt;
         &lt;small&gt;Twas a dark, rainy night...&lt;/small&gt;
         &lt;p&gt;dfjsdfjsdf&lt;/p&gt;
         &lt;p&gt;fdsfsdfhdsff gyuf uysgf ds&lt;/p&gt;
       &lt;/small&gt;
     &lt;/body&gt;
   &lt;/html&gt;
</source>

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

<p>
If you look at the <a href="libs/jsl/tags.html">JSL tag library</a> 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.
</p>

<p>
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.
</p>


</section>

<a name="html"/>
<section name="Parsing HTML">

<p>
This demo demonstrates the use the handy parse tag in the <A HREF="libs/html/tags.html">HTML tag library</A>
</p>

<p>
To run the demo type "maven demo:html" (View the <a href="http://svn.apache.org/repos/asf/commons/proper/jelly/trunk/jelly-tags/html/src/test/org/apache/commons/jelly/html/example.jelly">demo source</a>).
</p>

<p>
As you can see in the demo script, parsing an HTML file is simple:
</p>

<source>
    &lt;html:parse var="doc" html="index.html"/&gt;
</source>

<p>
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.
</p>

</section>

</section>

</body>

</document>