Commit a14e25f4 authored by Sven Franck's avatar Sven Franck

fix README

/reviewed-on !68
parent 8990466a
# jIO
jIO is a promised-based JavaScript library that offers connectors to many storages (Dropbox, webdav, IndexedDB, GDrive, ...) using a single API. jIO supports offline use, replication, encryption and synchronization as well as querying of stored documents and attachments allowing to build complex client-side centric web applications.
### jIO Documentation
The documentation can be found on [https://jio.nexedi.com/](https://jio.nexedi.com/)
### jIO Quickstart
git clone https://lab.nexedi.com/nexedi/jio.git
npm install
grunt server
### jIO Code
RenderJS source code is hosted on Gitlab at [https://lab.nexedi.com/nexedi/jio](https://lab.nexedi.com/nexedi/jio) (Github [mirror](https://github.com/nexedi/jio/) - please use the issue tracker on Gitlab)
### jIO Test
You can run tests after installing and building jIO by opening the */test/* folder
## Javascript Input/Output # jIO
**jIO is a client-side JavaScript library to manage documents across multiple jIO is a promised-based JavaScript library that offers connectors to many storages (Dropbox, webdav, IndexedDB, GDrive, ...) using a single API. jIO supports offline use, replication, encryption and synchronization as well as querying of stored documents and attachments allowing to build complex client-side centric web applications.
storages.**
### Getting Started ### jIO Documentation
To set up jIO you should include jio.js, dependencies and the connectors for the storages The documentation can be found on [https://jio.nexedi.com/](https://jio.nexedi.com/)
you want to use in the HTML page header (note that more dependencies may be required
depending on type of storages being used):
```html ### jIO Quickstart
<script src="RSVP.js"></script> git clone https://lab.nexedi.com/nexedi/jio.git
<script src="jio-latest.js"></script>
```
Then create your jIO instance like this:
```javascript
// create a new jio
var jio_instance = jIO.createJIO({
type: "query",
sub_storage: {
type: "uuid",
sub_storage: {
"type": "indexeddb",
"database": "test"
}
}
});
```
### Documents and Methods
Documents are JSON strings that contain *metadata* (properties, like a filename)
and *attachments* (optional content, for example *image.jpg*).
jIO exposes the following methods to *create*, *read*, *update* and *delete* documents
(for more information, including revision management and available options for
each method, please refer to the documentation):
```javascript
// create and store new document
jio_instance.post({"title": "some title"})
.then(function (new_id) {
...
});
// create or update an existing document
jio_instance.put(new_id, {"title": "New Title"})
.then(function ()
// console.log("Document stored");
});
// add an attachement to a document
jio_instance.putAttachment(document_id, attachment_id, new Blob())
.then(function () {
// console.log("Blob stored");
});
// read a document
jio_instance.get(document_id)
.then(function (document) {
// console.log(document);
// {
// "title": "New Title",
// }
});
// read an attachement
jio_instance.getAttachment(document_id, attachment_id)
.then(function (blob) {
// console.log(blob);
});
// delete a document and its attachment(s)
jio_instance.remove(document_id)
.then(function () {
// console.log("Document deleted");
});
// delete an attachement
jio_instance.removeAttachment(document_id, attachment_id)
.then(function () {
// console.log("Attachment deleted");
});
// get all documents
jio_instance.allDocs().then(function (response) {
// console.log(response);
// {
// "data": {
// "total_rows": 1,
// "rows": [{
// "id": "my_document",
// "value": {}
// }]
// }
// }
});
```
### Example
This is an example of how to store a video file with one attachment in local
storage. Note that attachments should be added after document creation.
```javascript
// create a new localStorage
var jio_instance = jIO.createJIO({
"type": "local",
});
var my_video_blob = new Blob([my_video_binary_string], {
"type": "video/ogg"
});
// post the document
jio_instance.put("myVideo", {
"title" : "My Video",
"format" : ["video/ogg", "vorbis", "HD"],
"language" : "en",
"description" : "Images Compilation"
}).then(function (response) {
// add video attachment
return jio_instance.putAttachment(
"myVideo",
"video.ogv",
my_video_blob
});
}).then(function (response) {
alert('Video Stored');
}, function (err) {
alert('Error when attaching the video');
}, function (progression) {
console.log(progression);
});
```
### Storage Locations
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:
- LocalStorage (browser local storage)
- IndexedDB
- ERP5Storage
- DAVStorage (connect to webDAV, more information on the
[documentation](https://www.j-io.org/documentation/jio-documentation/))
For more information on the specific storages including guidelines on how to
create your own connector, please also refer to the [documentation](https://www.j-io.org/documentation/jio-documentation).
### jIO Query
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):
```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>
// }
// }, { .. }]
// }
});
```
To find out more about queries, please refer to the documentation.
### Authors
- Francois Billioud
- Tristan Cavelier
- Sven Franck
- Romain Courteaud
### Copyright and license
jIO is an open-source library and is licensed under the LGPL license. More
information on LGPL can be found
[here](http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License).
### Contribute
Get development environment:
git clone https://lab.nexedi.com/nexedi/jio.git jio.git
cd jio.git
npm install npm install
alias grunt="./node_modules/grunt-cli/bin/grunt"
grunt
Run tests:
grunt server grunt server
and open http://127.0.0.1:9000/test/tests.html ### jIO Code
RenderJS source code is hosted on Gitlab at [https://lab.nexedi.com/nexedi/jio](https://lab.nexedi.com/nexedi/jio) (Github [mirror](https://github.com/nexedi/jio/) - please use the issue tracker on Gitlab)
Submit merge requests on lab.nexedi.com. ### jIO Test
You can run tests after installing and building jIO by opening the */test/* folder
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment