How To Use ZOO-Client

Authors:Nicolas Bozon, Luca Delucchi, Gérald Fenoy, Jeff McKenna
Last Updated:$Id: introduction.txt 562 2015-02-09 15:26:31Z djay $

ZOO-Client is a client-side Javascript API which ease the use and integration of WPS in your web applications.

Requirements

The ZOO-Client is depending on various Javscript libraries, they are axhaustively listed bellow:

Compile mustache templates

For being able to use the ZOO-Client API from your web appplication you will need to compile the mustache templates files located in the tpl directory. This compilation process imply that you have setup node.js on your computer.

sudo npm install hogan
hulk zoo-client/lib/tpl/*mustache > \
    zoo-client/lib/js/wps-client/payloads.js

Note

the Hogan version used to compile the template should be the same as the one used from your web application, in other case you may face compatibility issue.

Build the API documentation

You can build the ZOO-Client API documentation by using jsDoc, to build the docuementation use the following command:

npm install jsdoc
~/node_modules/.bin/jsdoc zoo-client/lib/js/wps-client/* -p

This will build the documentation in a directory named out in your current working directory.

Create your first application

For this first application, we will suppose that you have setup a directory named zoo-client-demo accessible from your server by using http://localhost/zoo-client-demo. In this directory, you should have the following subdirectories:

assets
assets/js
assets/js/lib
assets/js/lib/hogan
assets/js/lib/jquery
assets/js/lib/query-string
assets/js/lib/xml2json
assets/js/lib/zoo
assets/tpl

You will need to copy your node_modules javascript files copied in the hogan and query-string directories. First, you wil need to install query-string.

npm install query-string

Then you will copy query-string.js and hogan-3.0.2.js files in your zoo-client-demo web directory. Those files are located in your ~/node_modules directory.

For other libraries, you will need to download them from their official web sites and uncompress them in the corresponding directories.

Loading the modules from your web application

Before using the ZOO-Client, you will first have to include the javascript files from your web page. With the use of requirejs you will need only one line in your HTML page to include everything at once. This line will look like the following:

<script data-main="assets/js/first" src="assets/js/lib/require.js"></script>

In this example, we suppose that you have created a first.js file in the assets/js directory containing your main application code. First, you define there the required JavaScript libraries and potentially their configuration, then you can add any relevant code.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
requirejs.config({
    baseUrl: 'assets/js',
    paths: {
        jquery: 'lib/jquery/jquery-1.11.0.min',
        hogan: 'lib/hogan/hogan-3.0.2',
        xml2json: 'lib/xml2json/xml2json.min',
        queryString: 'lib/query-string/query-string',
        wpsPayloads: 'lib/zoo/payloads',
        wpsPayload: 'lib/zoo/wps-payload',
        utils: 'lib/zoo/utils',
        zoo: 'lib/zoo/zoo',
        domReady: 'lib/domReady',
        app: 'first-app',
    },
    shim: {
        wpsPayloads: {
            deps: ['hogan'],
        },
        wpsPayload: {
            deps: ['wpsPayloads'],
            exports: 'wpsPayload',
        },
        hogan: {
            exports: 'Hogan',
        },
        xml2json: {
          exports: "X2JS",
        },
        queryString: {
            exports: 'queryString',
        },
    },
});

requirejs.config({
    config: {
        app: {
            url: '/cgi-bin/zoo_loader.cgi',
            delay: 2000,
        }
    }
});

require(['domReady', 'app'], function(domReady, app) {
    domReady(function() {
        app.initialize();
    });
});

On line 2, you define the url where your files are located on the web server, in assets/js. From line 3 to 14, you define the JavaScript files to be loaded. From line 15 to 21, you configure the dependencies and exported symbols. From line 35 to 42, you configure your main application.

In this application, we use the domReady module to call the initialize function defined in the app module, which is defined in the first-app.js file as defined on line 13.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
define([
    'module','zoo','wpsPayload'
], function(module, ZooProcess, wpsPayload) {

    var myZooObject = new ZooProcess({
        url: module.config().url,
        delay: module.config().delay,
    });

    var initialize = function() {
        self = this;
        myZooObject.getCapabilities({
           type: 'POST',
             success: function(data){
                     console.log(data);
            }
        });

        myZooObject.describeProcess({
            type: 'POST',
            identifier: "all",
            success: function(data){
                console.log(data);
            }
        });

       myZooObject.execute({
           identifier: "Buffer",
           dataInputs: [{"identifier":"InputPolygon","href":"XXX","mimeType":"text/xml"}],
           dataOutputs: [{"identifier":"Result","mimeType":"application/json","type":"raw"}],
           type: 'POST',
           success: function(data) {
                console.log(data);
           },
           error: function(data){
                console.log(data);
           }
        });
    }

    // Return public methods
    return {
        initialize: initialize
    };

});

On line 5 you create a “global” ZooProcess instance named myZooObject, you set the url and delay to the values defined in first.js on line 35. From line 10 to 40, you define a simple initialize function which will invoke the getCapabilities (line 12 to 18), describeProcess (from line 20 to 26) and execute (from line 28 to 39) methods. For each you define a callback function which will simply display the resulting data in the browser’s console.