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

  • http://localhost:8080/jitsu/quicktours/

  • 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:

  • http://localhost:8080/projects/basic/page1.html

  • 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 Jitsu inspector files (jitsu.inspector.js, jitsu.inspector.css, etc) are also included. in the build. If you compile the project with debug="false", then only the core Jitsu files are generated:

    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:

    Option NameDescription
    outdir

    The path to the file system output directory where the compiled results are placed.

    This path is relative to the project's "basedir" attribute - which in turn is relative to the directory the project.xml file is in. (default is ".")

    appdirname

    The name of a subdirectory in the output directory where all secondary resources are placed (default is "app").

    Use "" (empty string) if you want the secondary files to end up in the same directory as the output directory, rather than a subidrectory.

    baseurl

    If set, this URL is prepended to all URLs generated by the page compiler.

    This can be useful for specifying an absolute output URL for the compiled pages.

    If the baseurl starts with a "/" it is relative to the web server's root. So if you use a baseurl of "/test" and an appdirname of "app" then the generated page will load the jitsu runtime from the URL "/test/app/jitsu.core.js".

    debug

    Setting debug to "true" turns on all the jitsu debugging options. When debug="true", the project is compiled with code within "#if DEBUG ... #endif" blocks enabled.

    In addition, setting debug to true also turns on the whitespace, comments, functionnames, and diagnostics options (unless values for those options are explicitly mentioned on the command line or in the project file, in which case the specified values are used).

    diagnostics

    If diagnostics is "true", then code in #if DIAGNOSTICS ... #endif is included in the output, and the Jitsu Inspector is included in the build. The Diagnostics class is effected by this option.

    Note it is legal to build a project with debug="false" and diagnostics="true" - you can use the Jitsu Inspector and the Diagnostics methods even if all the other debug options are turned off.

    whitespace If whitespace is "true", generated files include whitespace and are pretty-printed, making it easier to debug them. Setting this to "false" causes the compiler to strip whitespace from the output, reducing file size.
    comments If this is "true", and if whitespace is true, then generated files include comments. Otherwise, the compiler strips out comments from the output files.
    functionnames If functionnames is "true", then generated function are given names. e.g.
    MyClass.prototype.myMethod = function MyClass_myMethod() { ... }

    If this is "false", then function names are stripped out of anonymous functions, e.g.

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

    Function names are useful during debugging with Internet Explorer.

    crunchmode

    The crunchmode option controls how the compiler crunches JavaScript variable names.

    If crunchmode is "off", the cruncher leaves JavaScript variable names as-is in the generated code.

    If crunchmode is "shortnames", the cruncher uses the shortest possible variable names for each JavaScript variable - replacing variable names with one to three letter names.

    If crunchmode is "longnames", the cruncher appends a "_" suffix to every variable name that will be effected by crunchmode=shortnames. This lets you debug crunched code.

    If crunchmode is "safenames", the cruncher uses the same approach as "shortnames" but in addition adds a single letter prefix "W" to all generated names - helping to ensure that generated names don't clash with other non-crunched JavaScript code.

    lint

    The lint option controls whether the compiler will use the JScript compiler to output compile time errors and warnings to the console. This is particularly useful for finding undeclared and mispelled variables.

    If lint is "off", no linting will be performed.

    if lint is "errors", only errors will be output to the console.

    If lint is "warnings", errors and warnings will be output to the console (some of the warnings may be conservative, so expect a fair amount of output).

    serializetemplates If this is "true", the compiler will convert all output template functions into serialized versions of themselves. This is an optimization that will increase the speed with which templates are created, and hence the performance of a page.

    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.