--- a/client/README.md Wed Apr 29 20:00:40 2015 +0200
+++ b/client/README.md Tue May 05 17:08:53 2015 +0200
@@ -9,21 +9,27 @@
Whatever configuration you have, you need to import those javascript files **in that order**...
- <script src="[...]/jquery.min.js"></script>
- <script src="[...]/jquery.mousewheel.min.js"></script>
- <script src="[...]/underscore-min.js"></script>
- <script src="[...]/backbone.js"></script>
- <script src="[...]/backbone-relational.js"></script>
- <script src="[...]/paper.js"></script>
- <script src="[...]/renkan.js"></script>
+```html
+<script src="[...]/jquery.min.js"></script>
+<script src="[...]/jquery.mousewheel.min.js"></script>
+<script src="[...]/underscore-min.js"></script>
+<script src="[...]/backbone.js"></script>
+<script src="[...]/backbone-relational.js"></script>
+<script src="[...]/paper.js"></script>
+<script src="[...]/renkan.js"></script>
+```
... and the renkan css file :
- <link rel="stylesheet" href="[...]/renkan.css" />
+```html
+<link rel="stylesheet" href="[...]/renkan.css" />
+```
Finally, add the div in you DOM :
- <div id="renkan"></div>
+```html
+<div id="renkan"></div>
+```
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.
@@ -34,64 +40,67 @@
Nothing to add, the html is very simple :
- <body>
- <div id="renkan"></div>
- </body>
-
+```html
+<body>
+ <div id="renkan"></div>
+</body>
+```
### In a div
The renkan div has the css attributes position:absolute/top:0/left:0/bottom:0/right:0,
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 :
- <head>
- <style type="text/css">
- body{
- margin: 0 auto;
- width: 960px;
- }
- .header, .footer {
- font-size: 14px;
- height: 40px;
- padding-top: 10px;
- }
- .rnk-container{
- height: 500px;
- position: relative;
- width: 700px;
- }
- </style>
- </head>
- <body>
- <div class="header">
- This is a header
- </div>
- <div class="rnk-container">
- <div id="renkan"></div>
- </div>
- <div class="footer">
- This is a footer
- </div>
- </body>
-
+```html
+<head>
+ <style type="text/css">
+ body{
+ margin: 0 auto;
+ width: 960px;
+ }
+ .header, .footer {
+ font-size: 14px;
+ height: 40px;
+ padding-top: 10px;
+ }
+ .rnk-container{
+ height: 500px;
+ position: relative;
+ width: 700px;
+ }
+ </style>
+</head>
+<body>
+ <div class="header">
+ This is a header
+ </div>
+ <div class="rnk-container">
+ <div id="renkan"></div>
+ </div>
+ <div class="footer">
+ This is a footer
+ </div>
+</body>
+```
## Embedding a read only Renkan
To embed a read only Renkan, just add this script tag :
- <script type="text/javascript">
- var _renkan;
- $(function() {
- _renkan = new Rkns.Renkan({
- editor_mode: false,
- show_bins: false,
- });
- Rkns.jsonIO(_renkan, {
- url: "any_local_or_jsonp_url"
- });
+```html
+<script type="text/javascript">
+ var _renkan;
+ $(function() {
+ _renkan = new Rkns.Renkan({
+ editor_mode: false,
+ show_bins: false,
});
- </script>
-
+ Rkns.jsonIO(_renkan, {
+ url: "any_local_or_jsonp_url"
+ });
+ });
+</script>
+```
## Embedding a writable Renkan
@@ -101,17 +110,19 @@
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.
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 :
- <script type="text/javascript">
- var _renkan;
- $(function() {
- _renkan = new Rkns.Renkan({
- show_bins: false
- });
- Rkns.jsonIO(_renkan, {
- url: "url_of_a_persistent_connection"
- });
+```html
+<script type="text/javascript">
+ var _renkan;
+ $(function() {
+ _renkan = new Rkns.Renkan({
+ show_bins: false
});
- </script>
+ Rkns.jsonIO(_renkan, {
+ url: "url_of_a_persistent_connection"
+ });
+ });
+</script>
+```
## Search and bins
@@ -121,8 +132,130 @@
Search engine can be the current [IRI's Lignes de temps platform](http://ldt.iri.centrepompidou.fr/) and wikipedia in any available language.
Here is an example of configuration :
- _renkan = new Rkns.Renkan({
- search: [
+```js
+_renkan = new Rkns.Renkan({
+ search: [
+ {
+ type: "Ldt"
+ },
+ {
+ type: "Wikipedia",
+ lang: "fr"
+ },
+ {
+ type: "Wikipedia",
+ lang: "ja"
+ }
+ ]
+});
+Rkns.jsonIO(_renkan, {
+ url: "data/simple-persist.php"
+});
+```
+
+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.
+Resources can be simple texts, links or objects with title, description, url and image. Here is an example of configuration :
+
+```js
+_renkan = new Rkns.Renkan({
+ search: [
+ ...
+ ],
+ bins: [
+ {
+ title: "To be or not to be on Lignes de Temps",
+ type: "Ldt",
+ ldt_type: "Project",
+ project_id: "6af4019c-8283-11e2-9678-00145ea4a2be",
+ ldt_platform: "http://ldt.iri.centrepompidou.fr/"
+ },
+ {
+ type: "ResourceList",
+ title: "Ressources",
+ list: [
+ {
+ url: "http://www.google.com/",
+ title: "Google",
+ description: "Search engine",
+ image: "http://www.google.fr/images/srpr/logo4w.png"
+ },
+ "Polemic Tweet http://www.polemictweet.com",
+ "Twitter http://www.twitter.com/"
+ ]
+ }
+ ]
+});
+Rkns.jsonIO(_renkan, {
+ url: "data/simple-persist.php"
+});
+```
+
+
+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.
+
+## More configuration
+
+You can configure several things :
+* the language of your interface, english (default) or french
+* you can fill your nodes with black color instead of transparent.
+* thanks to an external file, you can define properties for links between node.
+
+```js
+_renkan = new Rkns.Renkan({
+ ...
+ property_files: [ "data/properties.json" ],
+ node_fill_color: true,
+ language: "fr"
+});
+```
+
+Here is an example of properties file :
+
+```json
+[
+ {
+ "label": "Dublin Core Metadata",
+ "base-uri": "http://purl.org/dc/elements/1.1/",
+ "properties": [
+ {
+ "uri": "creator",
+ "label": "created by"
+ }, {
+ "uri": "date",
+ "label": "has date"
+ }, {
+ "uri": "subject",
+ "label": "has subject"
+ }
+ ]
+ }, {
+ "label": "SKOS Semantic relations",
+ "base-uri": "http://www.w3.org/2004/02/skos/core#",
+ "properties": [
+ {
+ "uri": "broader",
+ "label": "has broader"
+ }, {
+ "uri": "narrower",
+ "label": "has narrower"
+ }, {
+ "uri": "related",
+ "label": "has related"
+ }
+ ]
+ }
+]
+```
+
+
+Finally, here is an example of full configuration :
+
+```html
+<script type="text/javascript">
+ var _renkan;
+ $(function() {
+ _renkan = new Rkns.Renkan({
+ search: [
{
type: "Ldt"
},
@@ -134,154 +267,40 @@
type: "Wikipedia",
lang: "ja"
}
- ]
- });
- Rkns.jsonIO(_renkan, {
- url: "data/simple-persist.php"
- });
-
-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.
-Resources can be simple texts, links or objects with title, description, url and image. Here is an example of configuration :
-
- _renkan = new Rkns.Renkan({
- search: [
- ...
- ],
- bins: [
- {
- title: "To be or not to be on Lignes de Temps",
- type: "Ldt",
- ldt_type: "Project",
- project_id: "6af4019c-8283-11e2-9678-00145ea4a2be",
- ldt_platform: "http://ldt.iri.centrepompidou.fr/"
- },
- {
- type: "ResourceList",
- title: "Ressources",
- list: [
- {
- url: "http://www.google.com/",
- title: "Google",
- description: "Search engine",
- image: "http://www.google.fr/images/srpr/logo4w.png"
- },
- "Polemic Tweet http://www.polemictweet.com",
- "Twitter http://www.twitter.com/"
- ]
- }
- ]
- });
- Rkns.jsonIO(_renkan, {
- url: "data/simple-persist.php"
- });
-
-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.
-
-## More configuration
-
-You can configure several things :
-* the language of your interface, english (default) or french
-* you can fill your nodes with black color instead of transparent.
-* thanks to an external file, you can define properties for links between node.
-
-
- _renkan = new Rkns.Renkan({
- ...
- property_files: [ "data/properties.json" ],
- node_fill_color: true,
- language: "fr"
- });
-
-Here is an example of properties file :
-
- [
- {
- "label": "Dublin Core Metadata",
- "base-uri": "http://purl.org/dc/elements/1.1/",
- "properties": [
+ ],
+ bins: [
+ {
+ title: "Projet Lignes de Temps",
+ type: "Ldt",
+ ldt_type: "Project",
+ project_id: "6af4019c-8283-11e2-9678-00145ea4a2be",
+ ldt_platform: "http://ldt.iri.centrepompidou.fr/"
+ },
{
- "uri": "creator",
- "label": "created by"
- }, {
- "uri": "date",
- "label": "has date"
- }, {
- "uri": "subject",
- "label": "has subject"
- }
- ]
- }, {
- "label": "SKOS Semantic relations",
- "base-uri": "http://www.w3.org/2004/02/skos/core#",
- "properties": [
- {
- "uri": "broader",
- "label": "has broader"
- }, {
- "uri": "narrower",
- "label": "has narrower"
- }, {
- "uri": "related",
- "label": "has related"
+ type: "ResourceList",
+ title: "Ressources",
+ list: [
+ {
+ url: "http://www.google.com/",
+ title: "Google",
+ description: "Search engine",
+ image: "http://www.google.fr/images/srpr/logo4w.png"
+ },
+ "Polemic Tweet http://www.polemictweet.com",
+ "Twitter http://www.twitter.com/"
+ ]
}
- ]
- }
- ]
-
-
-
-Finally, here is an example of full configuration :
-
- <script type="text/javascript">
- var _renkan;
- $(function() {
- _renkan = new Rkns.Renkan({
- search: [
- {
- type: "Ldt"
- },
- {
- type: "Wikipedia",
- lang: "fr"
- },
- {
- type: "Wikipedia",
- lang: "ja"
- }
- ],
- bins: [
- {
- title: "Projet Lignes de Temps",
- type: "Ldt",
- ldt_type: "Project",
- project_id: "6af4019c-8283-11e2-9678-00145ea4a2be",
- ldt_platform: "http://ldt.iri.centrepompidou.fr/"
- },
- {
- type: "ResourceList",
- title: "Ressources",
- list: [
- {
- url: "http://www.google.com/",
- title: "Google",
- description: "Search engine",
- image: "http://www.google.fr/images/srpr/logo4w.png"
- },
- "Polemic Tweet http://www.polemictweet.com",
- "Twitter http://www.twitter.com/"
- ]
- }
- ],
- property_files: [ "data/properties.json" ],
- node_fill_color: false,
- language: "fr"
- });
- Rkns.jsonIO(_renkan, {
- url: "data/simple-persist.php"
- });
+ ],
+ property_files: [ "data/properties.json" ],
+ node_fill_color: false,
+ language: "fr"
});
- </script>
-
+ Rkns.jsonIO(_renkan, {
+ url: "data/simple-persist.php"
+ });
+ });
+</script>
+```
## Drop management
@@ -291,45 +310,145 @@
and returns a node object. A node object has title, description, image and uri properties. The \_data object is received from the
browser's drop event. Here is an example of drop\_handler function :
- _renkan = new Rkns.Renkan({
- ...
- drop_handler: function(_data){
- var newNode = {};
- newNode.title = "Overridden title";
- newNode.description = "Overridden description " + _data["text/plain"];
- return newNode;
- }
- });
-
+```js
+_renkan = new Rkns.Renkan({
+ ...
+ drop_handler: function(_data){
+ var newNode = {};
+ newNode.title = "Overridden title";
+ newNode.description = "Overridden description " + _data["text/plain"];
+ return newNode;
+ }
+});
+```
You can also define a **drop\_enhancer** function that receives the already formed node object and \_data object. This function has to
return the overriden node object. Here is an example of drop\_enhancer function :
- _renkan = new Rkns.Renkan({
+```js
+_renkan = new Rkns.Renkan({
+ ...
+ drop_enhancer: function(newNode, _data){
+ newNode.title = "Prefixed title : " + newNode.title;
+ return newNode;
+ }
+});
+```
+
+## Data and api
+
+### Data
+
+The data exchanged by Renkan is a json object ths following structure:
+(Warning: some fields are optionals, and )
+
+```json
+{
+ "id": "f4d002b7-d4fd-486c-8898-6c6ceebc3354",
+ "title": "Example of Renkan with movies",
+ "description": "A long description",
+ "created": "2013-03-18T11:32:40.253+01:00",
+ "updated": "2014-02-04T15:12:56.619+01:00",
+ "nodes": [
+ {
+ "id": "node-2013-05-08-72c911bafdf9932c-0001",
+ "title": "Une femme mène l'enquête",
+ "description": "La caméra suit la femme qui marche\nJeu avec la caméra qui se substitue au spectateur",
+ "uri": "http://ldt.iri.centrepompidou.fr/ldtplatform/ldt/front/player/lyceehulst_3extraits/c8a61ee4-b33c-11e2-802c-00145ea4a2be#id=s_DCA8D184-EFC2-314B-0F6B-84043E8F9984",
+ "color": null,
+ "position": {
+ "x": -547.0499881440252,
+ "y": -221.5401229374163
+ },
+ "image": "http://ldt.iri.centrepompidou.fr/static/site/ldt/css/imgs/video_sequence.png",
+ "size": 0,
+ "project_id": "f4d002b7-d4fd-486c-8898-6c6ceebc3354",
+ "created_by": "de68xf75y6hs5rgjhgghxbm217xk",
+ "shape": "circle",
+ "type": "...",
+ "hidden": false
+ },
...
- drop_enhancer: function(newNode, _data){
- newNode.title = "Prefixed title : " + newNode.title;
- return newNode;
+ ],
+ "edges": [
+ {
+ "id": "edge-2013-05-08-72c911bafdf9932c-0002",
+ "title": "",
+ "description": "",
+ "uri": "",
+ "color": "#ff7f00",
+ "from": "node-2013-04-30-a81adec6694db5f4-0032",
+ "to": "node-2013-05-08-72c911bafdf9932c-0001",
+ "project_id": "f4d002b7-d4fd-486c-8898-6c6ceebc3354",
+ "created_by": "de68xf75y6hs5rgjhgghxbm217xk"
+ },
+ ...
+ ],
+ "users": [ #optional
+ {
+ "userId": "user-2015-05-05-72c911bafdf9932c-0001",
+ "color": "#cc9866",
+ "username": "user1",
+ "anonymous": true
+ },
+ ...
+ ],
+ "space_id": "17f968e4-2640-4319-aa61-b5b8b527ebb4", #Optional
+ "views": [ #Optional
+ {
+ "zoom_level": 0.8275032552816195,
+ "offset_x": 832.0104075533723,
+ "offset_y": 402.8917139487223
}
- });
+ ]
+}
+```
+
+Tjis data is a direct json serialisation of the data model (cf `client/js/`)
+
+
+### IO module and server communications
+
+Currently 2 modules are defined to load and save data:
+ - save-once: data is loaded by ajax at the page initialization and saved each time the save button is clicked (floppy disc icon)
+ - full-json: data is loaded by ajax at the page initialization and saved each time the data is modified.
+
+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.
+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.
+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`.
-## Dev
+
+## <a name="dev"></a>Dev
+
+Renkan offers a dev environment that uses [Grunt](http://gruntjs.com/) for running tasks and [Bower](http://bower.io/) for managing dependencies.
+
+### Setup
+
+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:
+
+```sh
+$ npm i
+$ ./node_modules/.bin/bower install
+```
+
+
+### Grunt tasks
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
-making it easier. You can launch them by running './node_modules/.bin/grunt task'.
-* 'dev': will build th project but let the temporary file like templates.js to let us test the application through the test files
-(see 'Tests' part below). Then it will launch a small testing server and watch the modifications of the js/css/html to build the project
-again in case of any change.
-
+making it easier. You can launch them by running `./node_modules/.bin/grunt <task>`.
+
+* `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.
+
Tasks for production :
-* 'default': will build the project and clean the temporary files (like templates.js) used during development and building.
-* 'copy-server': will copy the built project to the server side.
-
-## Tests
+* `default`: will build the project and clean the temporary files (like templates.js) used during development and building.
+* `copy-server`: will copy the built project ut put to the server part of this project.
+
+
+## <a name="tests"></a>Tests
Because of a simple php file enabling persistent connection, you can not test the writables examples by only opening them in your browser.
A url like file:///path/to/folder/test-writable-\*.html will not work.
-You need to run a localhost server that executes php and go to a url like http://localhost/renkan/test/test-writable-\*.html.
+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)
For read only examples, it appears that for security reasons urls like file:///path/to/folder/test-readonly-\*.html only work on Firefox.
-To see those examples with other browsers, you also need to run a localhost server and go to a url like http://localhost/renkan/test/test-readonly-\*.html.
+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)