jMaki Applications


jMaki applications can range from the very simple to those that contain multiple jMaki widgets. This document describes the basic structure of a application and where to put widgets.

Basic jMaki Application Structure

All applications that use jMaki need to provide a resources directory. This directory contains all the "resources" that will be used by your jMaki application. In the resources directory you must provide the jmaki.js JavaScript client. The jmaki.js contains the JavaScript that manages the loading of jMaki widgets on the client and contains helper functions to facilitate widget communication. Under the resources directory you may chose to provide an optional config.json file. The config.json contains mappings for extensions, glue mappings for wiring widgets together, and theming information.

JSP / JSF Specific Requirements

For Java-based applications this is what the basic application containing one widget named "hello" will look like

/- web root
    |
    +-resources 
    |    |
    |    +-jmaki.js
    |    |
    |    +-config.json
    |    |
    |    +-hello
    |        |
    |        +-component.css
    |        |
    |        +-component.js
    |        |
    |        +-component.htm
    |
    |
    +-WEB-INF
         |
         +-lib
            |
            +-jmaki-comp.jar

The jmaki-comp.jar jar containing the jMaki server runtime code will also need to be placed in the /WEB-INF/lib directory.

PHP Specfic Requirements

/- web root
    |
    +-JMaki.php
    |
    +-Json.PHP
    |
    +-XMLHttpRequest.php
    |
    +-resources 
         |
         +-jmaki.js
         |
         +-config.json
         |
         +-hello
             |
             +-component.css
             |
             +-component.js
             |
             +-component.htm         

For PHP you will need to include the JMaki.php, XMLHttpProxy.php, and JSON.php along with any widgets you plan to use. The JMaki.php may be located at any level of your web application. Just keep in mind that the resources directory needs to be in the same directory as the JMaki.php.

Widget locations

jMaki provides a means of allowing component namespaces using directory structures. Sub-directories are used to provide the namespaces using a '.' notation as may be seen below.

A jMaki widget with the name "jmaki.foo" will need the following files along with the platform-specific resources:

/- web root
    |
    +-resources 
        |
        +-jmaki.js
        |
        +-config.json
        |
        +-jmaki
          |
          +-foo
             |
             +-component.css
             |
             +-component.js
             |
             +-component.htm
            

The widget resources for "jmaki.foo" were found in the /resources/jmaki/foo/ directory.

The location of all jMaki resources is the same regardless of whether you are using PHP or Java. A widget in a sense is a directory containing the files component.css, component.js, and component.htm files which make up a widget.

An application containing a jMaki widget with the name "jmaki.mywidget" will look like:

/- web root
    |
    +-resources 
         |
         +-jmaki.js
         |
         +-config.json
         |
         +-jmaki
            |
            +-mywidget
                |
                +-component.css
                |
                +-component.js
                |
                +-component.htm

Now that we have an idea of how applicaitons are built let's look a little bit more about how widgets locations are resolved.

Widget Resolution with jMaki

As mentioned above jMaki widgets are made up of three core files. The files that make up a widget include:

A widget can be specific to a directory or they may be shared across all sub-directories of the web application. When rendering the page containing a widget jMaki uses the following lookup mechanism to locate the files that make up the component.

When a jMaki widget with the name "dojo.fisheye" is encountered jMaki will:

First, look in the current directory for a directory with the name of 'dojo' which contains a directory called 'fisheye' and search it for the resource files that make up the widget.

/- web root
    |
    +- (page containing widget)
    |
    +-dojo
       |
       +-fisheye
           |
           +-component.css
           |
           +-component.js
           |
           +-component.htm

Second, if the resources are not found jMaki will search in the resources directory:

/- web root
    |    
    +-resources 
         |
         +-jmaki.js
         |
         +-config.json
         |
         +-dojo
            |
            +-fisheye
                |
                +-component.css
                |
                +-component.js
                |
                +-component.htm

Keeping resources in the resources directory allows for all pages to to use the same jMaki widgets. Files in the local directory over-ride files in the web root resources directory.

Third, if you are using Java Server Faces and the resources for a widget not located in the resources directory, the class path will be searched starting from /META-INF/resources.