1 | .. _services-howtos: |
---|
2 | |
---|
3 | How To Use ZOO-Client |
---|
4 | ========================= |
---|
5 | |
---|
6 | :Authors: Nicolas Bozon, Luca Delucchi, Gérald Fenoy, Jeff McKenna |
---|
7 | :Last Updated: $Id: introduction.txt 562 2015-02-09 15:26:31Z knut $ |
---|
8 | |
---|
9 | ZOO-Client is a client-side Javascript API which ease the |
---|
10 | use and integration of WPS in your web applications. |
---|
11 | |
---|
12 | .. contents:: Table of Contents |
---|
13 | :depth: 3 |
---|
14 | :backlinks: top |
---|
15 | |
---|
16 | Requirements |
---|
17 | ---------------------- |
---|
18 | |
---|
19 | The ZOO-Client is depending on various Javscript libraries, they are |
---|
20 | axhaustively listed bellow: |
---|
21 | * `jQuery <http://www.jquery.com/>`__ |
---|
22 | * `x2js <https://code.google.com/p/x2js/>`__ |
---|
23 | * `requirejs <http://requirejs.org/>`__ |
---|
24 | * `Hogan.js <http://twitter.github.io/hogan.js/>`__ |
---|
25 | * `query-string <https://github.com/sindresorhus/query-string>`__ |
---|
26 | |
---|
27 | Compile mustache templates |
---|
28 | ************************** |
---|
29 | |
---|
30 | For being able to use the ZOO-Client API from your web appplication |
---|
31 | you will need to compile the mustache templates files located in the |
---|
32 | tpl directory. This compilation process imply that you have setup |
---|
33 | `node.js <http://nodejs.org/>`__ on your computer. |
---|
34 | |
---|
35 | :: |
---|
36 | |
---|
37 | sudo npm install hogan |
---|
38 | hulk zoo-client/lib/tpl/*mustache > \ |
---|
39 | zoo-client/lib/js/wps-client/payloads.js |
---|
40 | |
---|
41 | .. Note:: the Hogan version used to compile the template should be the |
---|
42 | same as the one used from your web application, in other case you |
---|
43 | may face compatibility issue. |
---|
44 | |
---|
45 | Build the API documentation |
---|
46 | *************************** |
---|
47 | |
---|
48 | You can build the ZOO-Client API documentation by using jsDoc, to |
---|
49 | build the docuementation use the following command: |
---|
50 | |
---|
51 | :: |
---|
52 | |
---|
53 | npm install jsdoc |
---|
54 | ~/node_modules/.bin/jsdoc zoo-client/lib/js/wps-client/* -p |
---|
55 | |
---|
56 | This will build the documentation in a directory named `out` in your |
---|
57 | current working directory. |
---|
58 | |
---|
59 | Create your first application |
---|
60 | ----------------------------- |
---|
61 | |
---|
62 | For this first application, we will suppose that you have setup a |
---|
63 | directory named `zoo-client-demo` accessible from your server by using |
---|
64 | `http://localhost/zoo-client-demo`. In this directory, you should have |
---|
65 | the following subdirectories: |
---|
66 | |
---|
67 | :: |
---|
68 | |
---|
69 | assets |
---|
70 | assets/js |
---|
71 | assets/js/lib |
---|
72 | assets/js/lib/hogan |
---|
73 | assets/js/lib/jquery |
---|
74 | assets/js/lib/query-string |
---|
75 | assets/js/lib/xml2json |
---|
76 | assets/js/lib/zoo |
---|
77 | assets/tpl |
---|
78 | |
---|
79 | You will need to copy your node_modules javascript files copied in the |
---|
80 | `hogan` and `query-string` directories. First, you wil need to install |
---|
81 | query-string. |
---|
82 | |
---|
83 | :: |
---|
84 | |
---|
85 | npm install query-string |
---|
86 | |
---|
87 | Then you will copy `query-string.js` and `hogan-3.0.2.js` files in |
---|
88 | your `zoo-client-demo` web directory. Those files are located in your |
---|
89 | `~/node_modules` directory. |
---|
90 | |
---|
91 | For other libraries, you will need to download them from their |
---|
92 | official web sites and uncompress them in the corresponding |
---|
93 | directories. |
---|
94 | |
---|
95 | Loading the modules from your web application |
---|
96 | ********************************************* |
---|
97 | |
---|
98 | Before using the ZOO-Client, you will first have to include the |
---|
99 | javascript files from your web page. With the use of requirejs you |
---|
100 | will need only one line in your HTML page to include everything at |
---|
101 | once. This line will look like the following: |
---|
102 | |
---|
103 | :: |
---|
104 | |
---|
105 | <script data-main="assets/js/first" src="assets/js/lib/require.js"></script> |
---|
106 | |
---|
107 | In this example, we suppose that you have created a `first.js` file |
---|
108 | in the `assets/js` directory containing your main application |
---|
109 | code. First, you define there the required JavaScript libraries and |
---|
110 | potentially their configuration, then you can add any relevant code. |
---|
111 | |
---|
112 | .. code-block:: javascript |
---|
113 | :linenos: |
---|
114 | |
---|
115 | requirejs.config({ |
---|
116 | baseUrl: 'assets/js', |
---|
117 | paths: { |
---|
118 | jquery: 'lib/jquery/jquery-1.11.0.min', |
---|
119 | hogan: 'lib/hogan/hogan-3.0.2', |
---|
120 | xml2json: 'lib/xml2json/xml2json.min', |
---|
121 | queryString: 'lib/query-string/query-string', |
---|
122 | wpsPayloads: 'lib/zoo/payloads', |
---|
123 | wpsPayload: 'lib/zoo/wps-payload', |
---|
124 | utils: 'lib/zoo/utils', |
---|
125 | zoo: 'lib/zoo/zoo', |
---|
126 | domReady: 'lib/domReady', |
---|
127 | app: 'first-app', |
---|
128 | }, |
---|
129 | shim: { |
---|
130 | wpsPayloads: { |
---|
131 | deps: ['hogan'], |
---|
132 | }, |
---|
133 | wpsPayload: { |
---|
134 | deps: ['wpsPayloads'], |
---|
135 | exports: 'wpsPayload', |
---|
136 | }, |
---|
137 | hogan: { |
---|
138 | exports: 'Hogan', |
---|
139 | }, |
---|
140 | xml2json: { |
---|
141 | exports: "X2JS", |
---|
142 | }, |
---|
143 | queryString: { |
---|
144 | exports: 'queryString', |
---|
145 | }, |
---|
146 | }, |
---|
147 | }); |
---|
148 | |
---|
149 | requirejs.config({ |
---|
150 | config: { |
---|
151 | app: { |
---|
152 | url: '/cgi-bin/zoo_loader.cgi', |
---|
153 | delay: 2000, |
---|
154 | } |
---|
155 | } |
---|
156 | }); |
---|
157 | |
---|
158 | require(['domReady', 'app'], function(domReady, app) { |
---|
159 | domReady(function() { |
---|
160 | app.initialize(); |
---|
161 | }); |
---|
162 | }); |
---|
163 | |
---|
164 | On line 2, you define the url where your files are located on the web |
---|
165 | server, in `assets/js`. From line 3 to 14, you define the JavaScript |
---|
166 | files to be loaded. From line 15 to 21, you configure the dependencies |
---|
167 | and exported symbols. From line 35 to 42, you configure your main |
---|
168 | application. |
---|
169 | |
---|
170 | In this application, we use the `domReady |
---|
171 | <http://github.com/requirejs/domReady>`__ module to call the |
---|
172 | `initialize` function defined in the `app` module, which is defined in |
---|
173 | the `first-app.js` file as defined on line 13. |
---|
174 | |
---|
175 | |
---|
176 | |
---|
177 | .. code-block:: javascript |
---|
178 | :linenos: |
---|
179 | |
---|
180 | define([ |
---|
181 | 'module','zoo','wpsPayload' |
---|
182 | ], function(module, ZooProcess, wpsPayload) { |
---|
183 | |
---|
184 | var myZooObject = new ZooProcess({ |
---|
185 | url: module.config().url, |
---|
186 | delay: module.config().delay, |
---|
187 | }); |
---|
188 | |
---|
189 | var initialize = function() { |
---|
190 | self = this; |
---|
191 | myZooObject.getCapabilities({ |
---|
192 | type: 'POST', |
---|
193 | success: function(data){ |
---|
194 | console.log(data); |
---|
195 | } |
---|
196 | }); |
---|
197 | |
---|
198 | myZooObject.describeProcess({ |
---|
199 | type: 'POST', |
---|
200 | identifier: "all", |
---|
201 | success: function(data){ |
---|
202 | console.log(data); |
---|
203 | } |
---|
204 | }); |
---|
205 | |
---|
206 | myZooObject.execute({ |
---|
207 | identifier: "Buffer", |
---|
208 | dataInputs: [{"identifier":"InputPolygon","href":"XXX","mimeType":"text/xml"}], |
---|
209 | dataOutputs: [{"identifier":"Result","mimeType":"application/json","type":"raw"}], |
---|
210 | type: 'POST', |
---|
211 | success: function(data) { |
---|
212 | console.log(data); |
---|
213 | }, |
---|
214 | error: function(data){ |
---|
215 | console.log(data); |
---|
216 | } |
---|
217 | }); |
---|
218 | } |
---|
219 | |
---|
220 | // Return public methods |
---|
221 | return { |
---|
222 | initialize: initialize |
---|
223 | }; |
---|
224 | |
---|
225 | }); |
---|
226 | |
---|
227 | On line 5 you create a "global" `ZooProcess` instance named |
---|
228 | `myZooObject`, you set the `url` and `delay` to the values defined in |
---|
229 | `first.js` on line 35. From line 10 to 40, you define a simple |
---|
230 | `initialize` function which will invoke the `getCapabilities` (line |
---|
231 | 12 to 18), `describeProcess` (from line 20 to 26) and `execute` (from |
---|
232 | line 28 to 39) methods. For each you define a callback function which |
---|
233 | will simply display the resulting data in the browser's console. |
---|
234 | |
---|
235 | |
---|