| author | rougeronj |
| Wed, 10 Jun 2015 16:00:45 +0200 | |
| changeset 475 | e3537f6de112 |
| parent 440 | 2311be523b92 |
| child 493 | 6f2ab1a72f4a |
| permissions | -rw-r--r-- |
| 249 | 1 |
# Renkan - Client configuration |
2 |
||
|
398
57f8d344fde9
Correct button shift on hover that appeared after paperjs v 0.9.15
ymh <ymh.work@gmail.com>
parents:
265
diff
changeset
|
3 |
Renkan is a tool to simply build oriented graphs by creating nodes and drag'n'droping links, |
|
57f8d344fde9
Correct button shift on hover that appeared after paperjs v 0.9.15
ymh <ymh.work@gmail.com>
parents:
265
diff
changeset
|
4 |
pictures and html elements from web pages. Each node can have title, description, uri/url, color, |
| 249 | 5 |
image and specific size. Each node can have title, uri/url and color. |
6 |
||
7 |
||
8 |
## Embedding Renkan in a web page |
|
9 |
||
10 |
Whatever configuration you have, you need to import those javascript files **in that order**... |
|
11 |
||
| 439 | 12 |
```html |
13 |
<script src="[...]/jquery.min.js"></script> |
|
14 |
<script src="[...]/jquery.mousewheel.min.js"></script> |
|
15 |
<script src="[...]/underscore-min.js"></script> |
|
16 |
<script src="[...]/backbone.js"></script> |
|
17 |
<script src="[...]/backbone-relational.js"></script> |
|
18 |
<script src="[...]/paper.js"></script> |
|
19 |
<script src="[...]/renkan.js"></script> |
|
20 |
``` |
|
| 249 | 21 |
|
22 |
... and the renkan css file : |
|
23 |
||
| 439 | 24 |
```html |
25 |
<link rel="stylesheet" href="[...]/renkan.css" /> |
|
26 |
``` |
|
| 249 | 27 |
|
28 |
Finally, add the div in you DOM : |
|
29 |
||
| 439 | 30 |
```html |
31 |
<div id="renkan"></div> |
|
32 |
``` |
|
| 249 | 33 |
|
34 |
Your Renkan should be displayed. Now let's see more specifically the 2 displays possibilities : in body 100% or in a div with set width and height. |
|
35 |
||
| 251 | 36 |
N.B. : renkan.js is the concatenation of those js files : header.js main.js models.js defaults.js i18n.js paper-renderer.js full-json.js ldtjson-bin.js list-bin.js wikipedia-bin.js. |
|
398
57f8d344fde9
Correct button shift on hover that appeared after paperjs v 0.9.15
ymh <ymh.work@gmail.com>
parents:
265
diff
changeset
|
37 |
It is built with the script available in sbin/build/compil.sh. |
| 249 | 38 |
|
39 |
### In body 100% |
|
40 |
||
41 |
Nothing to add, the html is very simple : |
|
42 |
||
| 439 | 43 |
```html |
44 |
<body> |
|
45 |
<div id="renkan"></div> |
|
46 |
</body> |
|
47 |
``` |
|
| 249 | 48 |
|
49 |
### In a div |
|
50 |
||
|
398
57f8d344fde9
Correct button shift on hover that appeared after paperjs v 0.9.15
ymh <ymh.work@gmail.com>
parents:
265
diff
changeset
|
51 |
The renkan div has the css attributes position:absolute/top:0/left:0/bottom:0/right:0, |
| 250 | 52 |
so the parent div has to be in position:relative and define width and height. Here is a simple example including css and partial html : |
| 249 | 53 |
|
| 439 | 54 |
```html |
55 |
<head> |
|
56 |
<style type="text/css"> |
|
57 |
body{ |
|
58 |
margin: 0 auto; |
|
59 |
width: 960px; |
|
60 |
} |
|
61 |
.header, .footer { |
|
62 |
font-size: 14px; |
|
63 |
height: 40px; |
|
64 |
padding-top: 10px; |
|
65 |
} |
|
66 |
.rnk-container{ |
|
67 |
height: 500px; |
|
68 |
position: relative; |
|
69 |
width: 700px; |
|
70 |
} |
|
71 |
</style> |
|
72 |
</head> |
|
73 |
<body> |
|
74 |
<div class="header"> |
|
75 |
This is a header |
|
76 |
</div> |
|
77 |
<div class="rnk-container"> |
|
78 |
<div id="renkan"></div> |
|
79 |
</div> |
|
80 |
<div class="footer"> |
|
81 |
This is a footer |
|
82 |
</div> |
|
83 |
</body> |
|
84 |
``` |
|
| 249 | 85 |
|
86 |
## Embedding a read only Renkan |
|
87 |
||
88 |
To embed a read only Renkan, just add this script tag : |
|
89 |
||
| 439 | 90 |
```html |
91 |
<script type="text/javascript"> |
|
92 |
var _renkan; |
|
93 |
$(function() { |
|
94 |
_renkan = new Rkns.Renkan({ |
|
95 |
editor_mode: false, |
|
96 |
show_bins: false, |
|
| 249 | 97 |
}); |
| 439 | 98 |
Rkns.jsonIO(_renkan, { |
99 |
url: "any_local_or_jsonp_url" |
|
100 |
}); |
|
101 |
}); |
|
102 |
</script> |
|
103 |
``` |
|
| 249 | 104 |
|
105 |
||
106 |
## Embedding a writable Renkan |
|
107 |
||
108 |
### Simple mode : no bins on the left, just the canvas |
|
109 |
||
|
398
57f8d344fde9
Correct button shift on hover that appeared after paperjs v 0.9.15
ymh <ymh.work@gmail.com>
parents:
265
diff
changeset
|
110 |
To embed a simple writable Renkan, just add this script tag. In the client folder, "data/simple-persist.php" makes a very simple persistent url. |
| 249 | 111 |
The persistent url is supposed to give the json data on GET request at page load, and save datas at PUT request sent by the browser : |
112 |
||
| 439 | 113 |
```html |
114 |
<script type="text/javascript"> |
|
115 |
var _renkan; |
|
116 |
$(function() { |
|
117 |
_renkan = new Rkns.Renkan({ |
|
118 |
show_bins: false |
|
| 249 | 119 |
}); |
| 439 | 120 |
Rkns.jsonIO(_renkan, { |
121 |
url: "url_of_a_persistent_connection" |
|
122 |
}); |
|
123 |
}); |
|
124 |
</script> |
|
125 |
``` |
|
| 249 | 126 |
|
127 |
||
| 251 | 128 |
## Search and bins |
129 |
||
130 |
On the right of your renkan interface, you can add some search engine and data bins. |
|
131 |
||
|
398
57f8d344fde9
Correct button shift on hover that appeared after paperjs v 0.9.15
ymh <ymh.work@gmail.com>
parents:
265
diff
changeset
|
132 |
Search engine can be the current [IRI's Lignes de temps platform](http://ldt.iri.centrepompidou.fr/) and wikipedia in any available language. |
| 251 | 133 |
Here is an example of configuration : |
134 |
||
| 439 | 135 |
```js |
136 |
_renkan = new Rkns.Renkan({ |
|
137 |
search: [ |
|
138 |
{ |
|
139 |
type: "Ldt" |
|
140 |
}, |
|
141 |
{ |
|
142 |
type: "Wikipedia", |
|
143 |
lang: "fr" |
|
144 |
}, |
|
145 |
{ |
|
146 |
type: "Wikipedia", |
|
147 |
lang: "ja" |
|
148 |
} |
|
149 |
] |
|
150 |
}); |
|
151 |
Rkns.jsonIO(_renkan, { |
|
152 |
url: "data/simple-persist.php" |
|
153 |
}); |
|
154 |
``` |
|
155 |
||
156 |
You can also define data bins : annotations loaded from IRI's Lignes de temps projects, and any resources which can be drag and dropped into the renkan. |
|
157 |
Resources can be simple texts, links or objects with title, description, url and image. Here is an example of configuration : |
|
158 |
||
159 |
```js |
|
160 |
_renkan = new Rkns.Renkan({ |
|
161 |
search: [ |
|
162 |
... |
|
163 |
], |
|
164 |
bins: [ |
|
165 |
{ |
|
166 |
title: "To be or not to be on Lignes de Temps", |
|
167 |
type: "Ldt", |
|
168 |
ldt_type: "Project", |
|
169 |
project_id: "6af4019c-8283-11e2-9678-00145ea4a2be", |
|
170 |
ldt_platform: "http://ldt.iri.centrepompidou.fr/" |
|
171 |
}, |
|
172 |
{ |
|
173 |
type: "ResourceList", |
|
174 |
title: "Ressources", |
|
175 |
list: [ |
|
176 |
{ |
|
177 |
url: "http://www.google.com/", |
|
178 |
title: "Google", |
|
179 |
description: "Search engine", |
|
180 |
image: "http://www.google.fr/images/srpr/logo4w.png" |
|
181 |
}, |
|
182 |
"Polemic Tweet http://www.polemictweet.com", |
|
183 |
"Twitter http://www.twitter.com/" |
|
184 |
] |
|
185 |
} |
|
186 |
] |
|
187 |
}); |
|
188 |
Rkns.jsonIO(_renkan, { |
|
189 |
url: "data/simple-persist.php" |
|
190 |
}); |
|
191 |
``` |
|
192 |
||
193 |
||
194 |
If you embed the renkan in a div, the renkan container css should have overflow:hidden in order to hide bins when the user wants to. |
|
195 |
||
196 |
## More configuration |
|
197 |
||
198 |
You can configure several things : |
|
199 |
* the language of your interface, english (default) or french |
|
200 |
* you can fill your nodes with black color instead of transparent. |
|
201 |
* thanks to an external file, you can define properties for links between node. |
|
202 |
||
203 |
```js |
|
204 |
_renkan = new Rkns.Renkan({ |
|
205 |
... |
|
206 |
property_files: [ "data/properties.json" ], |
|
207 |
node_fill_color: true, |
|
208 |
language: "fr" |
|
209 |
}); |
|
210 |
``` |
|
211 |
||
212 |
Here is an example of properties file : |
|
213 |
||
214 |
```json |
|
215 |
[ |
|
216 |
{ |
|
217 |
"label": "Dublin Core Metadata", |
|
218 |
"base-uri": "http://purl.org/dc/elements/1.1/", |
|
219 |
"properties": [ |
|
220 |
{ |
|
221 |
"uri": "creator", |
|
222 |
"label": "created by" |
|
223 |
}, { |
|
224 |
"uri": "date", |
|
225 |
"label": "has date" |
|
226 |
}, { |
|
227 |
"uri": "subject", |
|
228 |
"label": "has subject" |
|
229 |
} |
|
230 |
] |
|
231 |
}, { |
|
232 |
"label": "SKOS Semantic relations", |
|
233 |
"base-uri": "http://www.w3.org/2004/02/skos/core#", |
|
234 |
"properties": [ |
|
235 |
{ |
|
236 |
"uri": "broader", |
|
237 |
"label": "has broader" |
|
238 |
}, { |
|
239 |
"uri": "narrower", |
|
240 |
"label": "has narrower" |
|
241 |
}, { |
|
242 |
"uri": "related", |
|
243 |
"label": "has related" |
|
244 |
} |
|
245 |
] |
|
246 |
} |
|
247 |
] |
|
248 |
``` |
|
249 |
||
250 |
||
251 |
Finally, here is an example of full configuration : |
|
252 |
||
253 |
```html |
|
254 |
<script type="text/javascript"> |
|
255 |
var _renkan; |
|
256 |
$(function() { |
|
257 |
_renkan = new Rkns.Renkan({ |
|
258 |
search: [ |
|
| 251 | 259 |
{ |
260 |
type: "Ldt" |
|
261 |
}, |
|
262 |
{ |
|
263 |
type: "Wikipedia", |
|
264 |
lang: "fr" |
|
265 |
}, |
|
266 |
{ |
|
267 |
type: "Wikipedia", |
|
268 |
lang: "ja" |
|
269 |
} |
|
| 439 | 270 |
], |
271 |
bins: [ |
|
272 |
{ |
|
273 |
title: "Projet Lignes de Temps", |
|
274 |
type: "Ldt", |
|
275 |
ldt_type: "Project", |
|
276 |
project_id: "6af4019c-8283-11e2-9678-00145ea4a2be", |
|
277 |
ldt_platform: "http://ldt.iri.centrepompidou.fr/" |
|
278 |
}, |
|
| 251 | 279 |
{ |
| 439 | 280 |
type: "ResourceList", |
281 |
title: "Ressources", |
|
282 |
list: [ |
|
283 |
{ |
|
284 |
url: "http://www.google.com/", |
|
285 |
title: "Google", |
|
286 |
description: "Search engine", |
|
287 |
image: "http://www.google.fr/images/srpr/logo4w.png" |
|
288 |
}, |
|
289 |
"Polemic Tweet http://www.polemictweet.com", |
|
290 |
"Twitter http://www.twitter.com/" |
|
291 |
] |
|
| 251 | 292 |
} |
| 439 | 293 |
], |
294 |
property_files: [ "data/properties.json" ], |
|
295 |
node_fill_color: false, |
|
296 |
language: "fr" |
|
| 251 | 297 |
}); |
| 439 | 298 |
Rkns.jsonIO(_renkan, { |
299 |
url: "data/simple-persist.php" |
|
300 |
}); |
|
301 |
}); |
|
302 |
</script> |
|
303 |
``` |
|
|
264
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
304 |
|
|
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
305 |
## Drop management |
|
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
306 |
|
|
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
307 |
You can override, partially or totally, the function that handle the drop event from an other web page. |
|
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
308 |
The current function catches drops from google results page, tweets, links, images and other things like svg paths. |
|
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
309 |
If you want to override totally the handler function, you can define a **drop\_handler** function that receives a \_data object |
|
398
57f8d344fde9
Correct button shift on hover that appeared after paperjs v 0.9.15
ymh <ymh.work@gmail.com>
parents:
265
diff
changeset
|
310 |
and returns a node object. A node object has title, description, image and uri properties. The \_data object is received from the |
|
264
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
311 |
browser's drop event. Here is an example of drop\_handler function : |
|
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
312 |
|
| 439 | 313 |
```js |
314 |
_renkan = new Rkns.Renkan({ |
|
315 |
... |
|
316 |
drop_handler: function(_data){ |
|
317 |
var newNode = {}; |
|
318 |
newNode.title = "Overridden title"; |
|
319 |
newNode.description = "Overridden description " + _data["text/plain"]; |
|
320 |
return newNode; |
|
321 |
} |
|
322 |
}); |
|
323 |
``` |
|
|
264
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
324 |
|
|
398
57f8d344fde9
Correct button shift on hover that appeared after paperjs v 0.9.15
ymh <ymh.work@gmail.com>
parents:
265
diff
changeset
|
325 |
You can also define a **drop\_enhancer** function that receives the already formed node object and \_data object. This function has to |
|
264
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
326 |
return the overriden node object. Here is an example of drop\_enhancer function : |
|
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
327 |
|
| 439 | 328 |
```js |
329 |
_renkan = new Rkns.Renkan({ |
|
330 |
... |
|
331 |
drop_enhancer: function(newNode, _data){ |
|
332 |
newNode.title = "Prefixed title : " + newNode.title; |
|
333 |
return newNode; |
|
334 |
} |
|
335 |
}); |
|
336 |
``` |
|
337 |
||
338 |
## Data and api |
|
339 |
||
340 |
### Data |
|
341 |
||
342 |
The data exchanged by Renkan is a json object ths following structure: |
|
343 |
(Warning: some fields are optionals, and ) |
|
344 |
||
345 |
```json |
|
346 |
{ |
|
347 |
"id": "f4d002b7-d4fd-486c-8898-6c6ceebc3354", |
|
348 |
"title": "Example of Renkan with movies", |
|
349 |
"description": "A long description", |
|
350 |
"created": "2013-03-18T11:32:40.253+01:00", |
|
351 |
"updated": "2014-02-04T15:12:56.619+01:00", |
|
352 |
"nodes": [ |
|
353 |
{ |
|
354 |
"id": "node-2013-05-08-72c911bafdf9932c-0001", |
|
355 |
"title": "Une femme mène l'enquête", |
|
356 |
"description": "La caméra suit la femme qui marche\nJeu avec la caméra qui se substitue au spectateur", |
|
357 |
"uri": "http://ldt.iri.centrepompidou.fr/ldtplatform/ldt/front/player/lyceehulst_3extraits/c8a61ee4-b33c-11e2-802c-00145ea4a2be#id=s_DCA8D184-EFC2-314B-0F6B-84043E8F9984", |
|
358 |
"color": null, |
|
359 |
"position": { |
|
360 |
"x": -547.0499881440252, |
|
361 |
"y": -221.5401229374163 |
|
362 |
}, |
|
363 |
"image": "http://ldt.iri.centrepompidou.fr/static/site/ldt/css/imgs/video_sequence.png", |
|
364 |
"size": 0, |
|
365 |
"project_id": "f4d002b7-d4fd-486c-8898-6c6ceebc3354", |
|
366 |
"created_by": "de68xf75y6hs5rgjhgghxbm217xk", |
|
367 |
"shape": "circle", |
|
368 |
"type": "...", |
|
369 |
"hidden": false |
|
370 |
}, |
|
|
264
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
371 |
... |
| 439 | 372 |
], |
373 |
"edges": [ |
|
374 |
{ |
|
375 |
"id": "edge-2013-05-08-72c911bafdf9932c-0002", |
|
376 |
"title": "", |
|
377 |
"description": "", |
|
378 |
"uri": "", |
|
379 |
"color": "#ff7f00", |
|
380 |
"from": "node-2013-04-30-a81adec6694db5f4-0032", |
|
381 |
"to": "node-2013-05-08-72c911bafdf9932c-0001", |
|
382 |
"project_id": "f4d002b7-d4fd-486c-8898-6c6ceebc3354", |
|
383 |
"created_by": "de68xf75y6hs5rgjhgghxbm217xk" |
|
384 |
}, |
|
385 |
... |
|
386 |
], |
|
387 |
"users": [ #optional |
|
388 |
{ |
|
389 |
"userId": "user-2015-05-05-72c911bafdf9932c-0001", |
|
390 |
"color": "#cc9866", |
|
391 |
"username": "user1", |
|
392 |
"anonymous": true |
|
393 |
}, |
|
394 |
... |
|
395 |
], |
|
396 |
"space_id": "17f968e4-2640-4319-aa61-b5b8b527ebb4", #Optional |
|
397 |
"views": [ #Optional |
|
398 |
{ |
|
399 |
"zoom_level": 0.8275032552816195, |
|
400 |
"offset_x": 832.0104075533723, |
|
401 |
"offset_y": 402.8917139487223 |
|
|
264
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
402 |
} |
| 439 | 403 |
] |
404 |
} |
|
405 |
``` |
|
406 |
||
| 440 | 407 |
This data is a direct json serialisation of the data model (cf `client/js/`). |
| 439 | 408 |
|
409 |
||
410 |
### IO module and server communications |
|
411 |
||
412 |
Currently 2 modules are defined to load and save data: |
|
413 |
- save-once: data is loaded by ajax at the page initialization and saved each time the save button is clicked (floppy disc icon) |
|
414 |
- full-json: data is loaded by ajax at the page initialization and saved each time the data is modified. |
|
415 |
||
416 |
The code of these 2 modules is rather simple and easy to adapt. the various examples in the `test` folder show how to configure them. |
|
417 |
Both these 2 modules communicate with the server with a single endpoint. The communication is made with JSON documents and is bidirectional: 'GET' to load the project, 'POST' to send back the modified project. |
|
418 |
the dev environement (see [dev](#dev)) offer a simple implementation of such an endpoint for testing support. The code of this endpoint is in the file `client/data/simple-persist.js`. |
|
|
264
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
419 |
|
| 439 | 420 |
|
421 |
## <a name="dev"></a>Dev |
|
422 |
||
423 |
Renkan offers a dev environment that uses [Grunt](http://gruntjs.com/) for running tasks and [Bower](http://bower.io/) for managing dependencies. |
|
424 |
||
425 |
### Setup |
|
426 |
||
427 |
The only prerequisite is to install [nodejs](https://nodejs.org/) or [iojs](https://iojs.org/en/index.html). Once installed, the complete dev environment can be obtained with the following commands: |
|
428 |
||
429 |
```sh |
|
430 |
$ npm i |
|
431 |
$ ./node_modules/.bin/bower install |
|
432 |
``` |
|
433 |
||
434 |
||
435 |
### Grunt tasks |
|
|
264
cc1b3aa8cada
drop handler and enhancer functions, and read me explains this.
cavaliet
parents:
253
diff
changeset
|
436 |
|
|
431
1387779706e5
update README file to reference the task available in grunt
rougeronj
parents:
403
diff
changeset
|
437 |
We offer a environment to develop without having to build all the project manually after each change. We define few grunt task to help us |
| 439 | 438 |
making it easier. You can launch them by running `./node_modules/.bin/grunt <task>`. |
439 |
||
440 |
* `dev`: will build the project but keep the temporary file like templates.js to let us test the application through the test files (see ['Tests'](#tests) part below). Then it will launch a small web server for testing and watch the modifications of the js/css/html to build the project again in case of any change. The test server runs on port 9001 on your local machine i.e. http://localhost:9001 . The folder served is the `client/` folder. |
|
441 |
||
|
431
1387779706e5
update README file to reference the task available in grunt
rougeronj
parents:
403
diff
changeset
|
442 |
Tasks for production : |
| 439 | 443 |
* `default`: will build the project and clean the temporary files (like templates.js) used during development and building. |
444 |
* `copy-server`: will copy the built project ut put to the server part of this project. |
|
445 |
||
446 |
||
447 |
## <a name="tests"></a>Tests |
|
| 253 | 448 |
|
449 |
Because of a simple php file enabling persistent connection, you can not test the writables examples by only opening them in your browser. |
|
450 |
A url like file:///path/to/folder/test-writable-\*.html will not work. |
|
| 439 | 451 |
You need to run a localhost server that executes php and go to a url like http://localhost:9001/test/test-writable-\*.html. (cf. [Dev](#dev) above) |
| 253 | 452 |
|
453 |
For read only examples, it appears that for security reasons urls like file:///path/to/folder/test-readonly-\*.html only work on Firefox. |
|
| 439 | 454 |
To see those examples with other browsers, you also need to run a localhost server and go to a url like http://localhost:9001/test/test-readonly-\*.html. (cf. [Dev](#dev) above) |