3. Projects

In this document, we describing the Jitsu project system and show how to get started building a project.

Introduction

Jitsu includes a basic project system designed to make it easy to build Jitsu applications.

A Jitsu Project is a collection of files in a directory, together with a single "project.xml" file specifying how to build the project.

Jitsu project format

Jitsu project.xml files use a tiny subset of the NAnt Xml syntax. NAnt is a build tool derived from Ant, but written in C# for Mono and .NET.

At some point we will probably migrate to a more comprehensive build system, such as NAnt or Ant or MS Build. That involves writing a build task to execute the Jitsu page compiler - fairly straightforward, but it doesn't exist today.

Working with Projects using Puny

Jitsu ships with a tiny embedded web server called Puny. As a web server, Puny really is puny: it can serve simple files, but its a long way from a fully-fledged Apache or IIS. However, Puny's great feature is that it knows how to parse Jitsu project.xml files, watch for edits to files in a project directory, automatically run the Jitsu compiler when required, and show compile error messages in your browser. It's a great way to get started with Jitsu.

To launch Puny, just run jitsu.exe with no arguments (we'll assume you followed the instructions in the Download and Install document to install Jitsu as a command):

$ 
$ jitsu 

Jitsu install directory: C:\attap\jitsu
url: /jitsu/quicktours/
  => C:\attap\jitsu\htdocs\jitsu\quicktours\project.xml
url: /projects/basic/
  => C:\Documents and Settings\Jon\My Documents\JitsuProjects\basic\project.xml

quicktours: build
Simple: build
-- Build ok.
Puny Web Server, Copyright (C) 2005 Attap Inc.
Portions Copyright (C) 2004, 2005 Ryan Probasco.
Modified under the terms of the GNU GPL. No warranty.
----
Accepting requests on port 8080

Puny starts and listens on port 8080. When it starts up, it lists the base urls of all the projects it finds. In the listing above, for example, it shows:

url: /jitsu/quicktours/
  => C:\attap\jitsu\htdocs\jitsu\quicktours\project.xml

This indicates that the URL base /jitsu/quicktours/ maps to the indicated project. To open that project in the browser go to

A Basic Project

The very first time you launch the Puny Web Server, it creates a JitsuProjects directory in your Documents folder (the location is operating-system specific).

Inside the JitsuProjects directory should be a subfolder called basic. This contains a basic project with a simple data model and a single page with a label control binding to a data object. To view this project running, start Puny and visit:

Before editing files in the project, let's look at the project structure.

Project Layout

When the basic project is first setup, it contains three files: a project file (project.xml), a Jitsu Xml data file (data.xml), a single HTML source file (page1.src.html):

HTML Source Pages

Notice that the HTML source file is called "page1.src.html" - that is the convention used in Jitsu to indicate input HTML files that contain Jitsu markup. When you compile a project, the compiler generates the output filename by stripping out ".src." from any filenames it processes - generating "page1.html".

Although a little confusing at first, using this naming convention serves three purposes: (1) it clarifies which files contain source markup, (2) it enables the source and compiled version of a Jitsu HTML page to co-exist in the same directory (which is handy for referencing resources using relative urls), (3) keeping the ".html" file extension means existing HTML tools like Visual Studio, DreamWeaver etc. continue to work. (We tried using our own file extension, .xum, for a while, but that didn't work with our preferred HTML editor).

The Project File

The project.xml file looks like this:

<!-- jitsu project definitions -->
<project name="basic" default="build">
    <target name="build">
        <jitsu outdir="." appdirname="app"
                debug="true">
            <sources basedir="."> 
                <include name="*.src.html"/>            
                <include name="*.xml"/>            
            </sources>
        </jitsu>
    </target>
</project>

The core of this file is the "jitsu" tag, which specifies options to the jitsu page compiler.

Generated HTML Files

After Jitsu builds the project, the project directory looks like this:

For the page1.src.html input file, the compiler generated a page1.html output file. There's also an app directory, which we will discuss in a moment.

Going back to project.xml:

<!-- jitsu project definitions -->
<project name="helloworld" default="build">
    <target name="build">
        <jitsu outdir="." appdirname="app"
                debug="true">
            <sources basedir="."> 
                <include name="*.src.html"/>            
                <include name="*.xml"/>            
            </sources>
        </jitsu>
    </target>
</project>

Notice the outdir attribute in project.xml is ".", - this tells the page compiler to write page1.html to the same directory as the page1.src.html input file. That trick lets source and compiled files live in the same directory.

It is convenient for the source and compiled HTML files to co-exist in the same directory so that any references to relative URLs work for both files. However, if you prefer you can setup projects so that the sources are in one directory and the compiler outputs are written to a separate directory: you need to edit the outdir attribute and <sources> fileset as appropriate.

The "app" directory

As well as the page1.html output file, the compiler generated a collection of secondary script and resource files - all the secondary resources for a project are stored in a subdirectory of the output directory called "app" (you can override this directory name using the appdirname option).

The app subdirectory contains page1.html.js - this is the JavaScript companion to page1.html. There's also a data.js which - a compiled represention of the hellodata.xml datatype file.

Finally, the app subdirectory contains a collection of jitsu system files - all starting with the name "jitsu". These include the Jitsu runtime (jitsu.core.js) and control library (jitsu.controls.js).

Because we built this project with debug="true":

<!-- jitsu project definitions -->
<project name="helloworld" default="build">
    <target name="build">
        <jitsu outdir="." appdirname="app"
                debug="true">
            <sources basedir="."> 
                <include name="*.src.html"/>            
                <include name="*.xml"/>            
            </sources>
        </jitsu>
    </target>
</project>

The Bundler

In future releases we plan to add a "Bundler" to the Jitsu compiler. The bundler takes a collection of files and outputs them as a single .js or .css file, which can be faster to download than lots of small files. In debug builds, the bundler will be turned off - so that it is easier to navigate the project using debuggers like Venkman or Visual Studio.

Once a project is compiled, the output HTML files and app directory are "self contained" - the compiler copies all the files needed to run the app into the app directory.

Editing the Project

If you open page1.src.html in an HTML editor, you'll see it looks something like:

<html xmlns="http://www.w3.org/1999/xhtml" 
      xmlns:j="http://www.jitsu.org/schemas/2006">

    <body>
        A Basic Application:

        <j:App>
            <j:data>
                <!-- Load the DataSet from data.xml -->
                <j:DataSet id="ds1" src="file:data.xml#ds1"/>
            </j:data>
            
            <!-- Show the SimpleDataObject property as a label -->
            <h1><j:Label text="#bind(data.ds1.obj1.prop1)"/></h1>            
            
        </j:App>        
    </body>

</html>

Try replacing "Label" with "Button" and then reloading the project in a browser. The page should recompile. If you make any syntax errors, you should see those errors in a browser when you reload one of the project pages.

For more ideas of changs to make to the project, look at the Quick Tours.

Configuring Puny

You may want to have Puny find projects in directories outside the JitsuProjects directory.

Puny looks for projects in a list of directories specified in a config file. The first time you start Puny, it creates a user-specific config file, puny.conf.xml in your application data directory:

On Windows XP:
c:\Documents and Settings\Username\Application Data\Jitsu\puny.conf.xml

On Linux and Mac OS X:
~/.config/Jitsu/puny.conf.xml

Here's what the file contains by default:

    <?xml version="1.0" encoding="utf-8" ?>

    <puny>

        <!-- Add local HTTP directories below. -->
        <root directory="{DOCUMENTS}/JitsuProjects" urlpath="/projects/"/>
    </puny>

Within the <puny> element are a list of virtual root directories served by the Puny Web Server. The directory attribute must be a directory on your computer, and the urlpath attribute indicates where the files in that directory appear on the server's URL scheme.

The {DOCUMENTS} is a macro which is expanded to whatever the current user's documents directory is. You can also use the macro {HOME} which translates to your home directory (same as ~ on Unix computers), and {DESKTOP} which translates to the desktop directory..

You can add more roots if you require e.g.

    <?xml version="1.0" encoding="utf-8" ?>

    <puny>

        <!-- Add local HTTP directories below. -->
        <root directory="{DOCUMENTS}/JitsuProjects" urlpath="/projects/"/>
        <root directory="c:\myprojects\" urlpath="/foo/"/>
    </puny>

Now when you visit localhost:8080/foo/ Puny will serve files from c:\myprojects.

Puny searches any root directories you specify in the config file recursively looking for Jitsu projects.

The Jitsu.exe Command Line

See Download and Install for instructions on downloading Jitsu and making the jitsu command available.

The jitsu.exe executable can be run in three main ways:

1. Use jitsu on its own to launch the jitsu Puny Web Server running on the local machine, listening by default to port 8080.

$ jitsu 

2. Use jitsu <projectfile> to tell jitsu to build the specified project. This scans the project file for a jitsu build task, and executes the task if its found.

For example, here is how we manually build the quicktours on a Linux cluster:

$ jitsu /attap/jitsu/htdocs/jitsu/quicktours/project.xml
jitsu => /attap/jitsu/htdocs/jitsu/quicktours
"-outdir:/attap/jitsu/htdocs/jitsu/quicktours"
"-baseurl:/jitsu/quicktours"
"-appdirname:app"
"-debug:true"

3. You can also manually run the compiler with the specified inputs, outputs and options, e.g.

$ cd ~/myproject
$ jitsu -outdir:. -appdirname:app -debug:true *.src.xml *.xml

The command line options here have the same names and meanings as they do in XML build files. So the command line shown above is equivalent to writing the following in a project.xml file:

<jitsu outdir="." appdirname="app" debug="true">
    <sources basedir="."> 
        <include name="*.src.html"/>            
        <include name="*.xml"/>            
    </sources>
</jitsu>

The Xml attribute debug="true" is written on the command line as -debug:true.

If a command line option value has spaces, surround the whole command in quotes, e.g.

    $ jitsu "-outdir:c:\documents and settings\test" *.html

Jitsu Project Build Options

Here are the compiler-related options you can specify on a jitsu task within a project:

MyClass.prototype.myMethod = function MyClass_myMethod() { ... }

MyClass.prototype.myMethod = function() { ... }

Deploying Projects

After building a project, simply open one of the generated ".html" files in a web browser (either through a web server, or simply by double-clicking on it) to load and run the apps they contain.

You can also use a tool like FTP to copy the generated .html and app directories to a remote web server. You do not need the jitsu.exe compiler or any of the files in the jitsu compiler directory to run Jitsu apps.

In many cases Jitsu apps will run correctly even if they are loaded as files (by double-clicking on the file).

However, once you add active datasets to a project, then to see the app running correctly, you need to serve the pages from a web server which provides the appropriate active dataset services. See Active Datasets for more on connecting apps to data.