README.md 5.42 KB
Newer Older
Tristan Cavelier's avatar
Tristan Cavelier committed
1
## Javascript Input/Output
Tristan Cavelier's avatar
Tristan Cavelier committed
2 3 4 5

**jIO is a client-side JavaScript library to manage documents across multiple
  storages.**

Tristan Cavelier's avatar
Tristan Cavelier committed
6
### Getting Started
Tristan Cavelier's avatar
Tristan Cavelier committed
7

8
To set up jIO you should include jio.js, dependencies and the connectors for the storages
9
you want to use in the HTML page header (note that more dependencies may be required
Tristan Cavelier's avatar
Tristan Cavelier committed
10 11
depending on type of storages being used):

12
```html
Romain Courteaud's avatar
Romain Courteaud committed
13 14
<script src="RSVP.js"></script>
<script src="jio-latest.js"></script>
15
```
Tristan Cavelier's avatar
Tristan Cavelier committed
16

17
Then create your jIO instance like this:
Tristan Cavelier's avatar
Tristan Cavelier committed
18

19
```javascript
Romain Courteaud's avatar
Romain Courteaud committed
20
// create a new jio
21
var jio_instance = jIO.createJIO({
Romain Courteaud's avatar
Romain Courteaud committed
22 23 24 25 26 27 28 29
  type: "query",
  sub_storage: {
    type: "uuid",
    sub_storage: {
      "type": "indexeddb",
      "database": "test"
    }
  }
30 31
});
```
Tristan Cavelier's avatar
Tristan Cavelier committed
32

Tristan Cavelier's avatar
Tristan Cavelier committed
33
### Documents and Methods
Tristan Cavelier's avatar
Tristan Cavelier committed
34

35
Documents are JSON strings that contain *metadata* (properties, like a filename)
Tristan Cavelier's avatar
Tristan Cavelier committed
36
and *attachments* (optional content, for example *image.jpg*).
Tristan Cavelier's avatar
Tristan Cavelier committed
37

Tristan Cavelier's avatar
Tristan Cavelier committed
38
jIO exposes the following methods to *create*, *read*, *update* and *delete* documents
Tristan Cavelier's avatar
Tristan Cavelier committed
39 40 41
(for more information, including revision management and available options for
each method, please refer to the documentation):

42 43
```javascript
// create and store new document
Klaus Wölfel's avatar
Klaus Wölfel committed
44
jio_instance.post({"title": "some title"})
Romain Courteaud's avatar
Romain Courteaud committed
45 46
  .then(function (new_id) {
    ...
47 48 49
  });

// create or update an existing document
Romain Courteaud's avatar
Romain Courteaud committed
50 51 52
jio_instance.put(new_id, {"title": "New Title"})
  .then(function () 
    // console.log("Document stored");
53 54 55
  });

// add an attachement to a document
Romain Courteaud's avatar
Romain Courteaud committed
56 57 58
jio_instance.putAttachment(document_id, attachment_id, new Blob())
  .then(function () {
    // console.log("Blob stored");
59 60 61
  });

// read a document
Romain Courteaud's avatar
Romain Courteaud committed
62 63 64
jio_instance.get(document_id)
  .then(function (document) {
    // console.log(document);
65
    // {
Romain Courteaud's avatar
Romain Courteaud committed
66
    //   "title": "New Title",
67 68 69 70
    // }
  });

// read an attachement
Romain Courteaud's avatar
Romain Courteaud committed
71 72 73
jio_instance.getAttachment(document_id, attachment_id)
  .then(function (blob) {
    // console.log(blob);
74 75 76
  });

// delete a document and its attachment(s)
Romain Courteaud's avatar
Romain Courteaud committed
77 78 79
jio_instance.remove(document_id)
  .then(function () {
    // console.log("Document deleted");
80 81 82
  });

// delete an attachement
Romain Courteaud's avatar
Romain Courteaud committed
83 84 85
jio_instance.removeAttachment(document_id, attachment_id)
  .then(function () {
    // console.log("Attachment deleted");
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101
  });

// get all documents
jio_instance.allDocs().then(function (response) {
  // console.log(response);
  // {
  //   "data": {
  //     "total_rows": 1,
  //     "rows": [{
  //       "id": "my_document",
  //       "value": {}
  //     }]
  //   }
  // }
});
```
Tristan Cavelier's avatar
Tristan Cavelier committed
102

Tristan Cavelier's avatar
Tristan Cavelier committed
103

Tristan Cavelier's avatar
Tristan Cavelier committed
104
### Example
Tristan Cavelier's avatar
Tristan Cavelier committed
105 106

This is an example of how to store a video file with one attachment in local
Tristan Cavelier's avatar
Tristan Cavelier committed
107
storage. Note that attachments should be added after document creation.
Tristan Cavelier's avatar
Tristan Cavelier committed
108

109 110 111 112 113
```javascript
// create a new localStorage
var jio_instance = jIO.createJIO({
  "type": "local",
});
Tristan Cavelier's avatar
Tristan Cavelier committed
114

115 116 117
var my_video_blob = new Blob([my_video_binary_string], {
  "type": "video/ogg"
});
Tristan Cavelier's avatar
Tristan Cavelier committed
118

119
// post the document
Romain Courteaud's avatar
Romain Courteaud committed
120
jio_instance.put("myVideo", {
121 122 123 124 125
  "title"       : "My Video",
  "format"      : ["video/ogg", "vorbis", "HD"],
  "language"    : "en",
  "description" : "Images Compilation"
}).then(function (response) {
Tristan Cavelier's avatar
Tristan Cavelier committed
126

127
  // add video attachment
Romain Courteaud's avatar
Romain Courteaud committed
128 129 130 131
  return jio_instance.putAttachment(
    "myVideo",
    "video.ogv",
    my_video_blob
132
  });
Tristan Cavelier's avatar
Tristan Cavelier committed
133

134
}).then(function (response) {
Tristan Cavelier's avatar
Tristan Cavelier committed
135

136
  alert('Video Stored');
Tristan Cavelier's avatar
Tristan Cavelier committed
137

138
}, function (err) {
Tristan Cavelier's avatar
Tristan Cavelier committed
139

Romain Courteaud's avatar
Romain Courteaud committed
140
  alert('Error when attaching the video');
Tristan Cavelier's avatar
Tristan Cavelier committed
141

142
}, function (progression) {
Tristan Cavelier's avatar
Tristan Cavelier committed
143

144
  console.log(progression);
Tristan Cavelier's avatar
Tristan Cavelier committed
145

146 147
});
```
Tristan Cavelier's avatar
Tristan Cavelier committed
148

Tristan Cavelier's avatar
Tristan Cavelier committed
149
### Storage Locations
Tristan Cavelier's avatar
Tristan Cavelier committed
150 151 152 153 154 155 156

jIO allows to build "storage trees" consisting of connectors to multiple
storages (webDav, xWiki, S3, localStorage) and use type-storages to add features
like revision management or indices to a child storage (sub_storage).

The following storages are currently supported:

Tristan Cavelier's avatar
Tristan Cavelier committed
157
- LocalStorage (browser local storage)
Romain Courteaud's avatar
Romain Courteaud committed
158 159
- IndexedDB
- ERP5Storage
Tristan Cavelier's avatar
Tristan Cavelier committed
160 161
- DAVStorage (connect to webDAV, more information on the
  [documentation](https://www.j-io.org/documentation/jio-documentation/))
Tristan Cavelier's avatar
Tristan Cavelier committed
162 163

For more information on the specific storages including guidelines on how to
Tristan Cavelier's avatar
Tristan Cavelier committed
164
create your own connector, please also refer to the [documentation](https://www.j-io.org/documentation/jio-documentation).
Tristan Cavelier's avatar
Tristan Cavelier committed
165

166
### jIO Query
Tristan Cavelier's avatar
Tristan Cavelier committed
167

168 169 170 171
jIO can use queries, which can be run in the allDocs() method to query document
lists. A sample query would look like this (note that not all storages support
allDocs and jio queries, and that pre-querying of documents on distant storages
should best be done server-side):
Tristan Cavelier's avatar
Tristan Cavelier committed
172

173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196
```javascript
// run allDocs with query option on an existing jIO
jio_instance.allDocs({
  "query": '(fieldX: >= "string" AND fieldY: < "string")',
  // records to display ("from to")
  "limit": [0, 5],
  // sort by
  "sort_on": [[<string A>, 'descending']],
  // fields to return in response
  "select_list": [<string A>, <string B>]
}).then(function (response) {
  // console.log(response);
  // {
  //   "total_rows": 1,
  //   "rows": [{
  //     "id": <string>,
  //     "value": {
  //       <string A>: <string>,
  //       <string B>: <string>
  //     }
  //   }, { .. }]
  // }
});
```
Tristan Cavelier's avatar
Tristan Cavelier committed
197

198
To find out more about queries, please refer to the documentation.
Tristan Cavelier's avatar
Tristan Cavelier committed
199 200 201 202 203 204

### Authors

- Francois Billioud
- Tristan Cavelier
- Sven Franck
Romain Courteaud's avatar
Romain Courteaud committed
205
- Romain Courteaud
Tristan Cavelier's avatar
Tristan Cavelier committed
206 207 208 209

### Copyright and license

jIO is an open-source library and is licensed under the LGPL license. More
Tristan Cavelier's avatar
Tristan Cavelier committed
210 211
information on LGPL can be found
[here](http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License).
212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233

### Contribute

Get development environment:


    git clone https://lab.nexedi.com/nexedi/jio.git jio.git
    cd jio.git
    npm install
    alias grunt="./node_modules/grunt-cli/bin/grunt"
    grunt


Run tests:


    grunt server


and open http://127.0.0.1:9000/test/tests.html

Submit merge requests on lab.nexedi.com.