Skip to content

J
jio
Commit 37c7c418 authored by Tristan Cavelier's avatar Tristan Cavelier
Browse files
Options

README.md updated

parent 127b6558
Hide whitespace changes
Inline Side-by-side
Showing with 137 additions and 133 deletions
README.md
View file @ 37c7c418
......@@ -3,6 +3,8 @@
**jIO is a client-side JavaScript library to manage documents across multiple
storages.**
<!-- \index-and-table 3 -->
### Getting Started
To set up jIO include jio.js, dependencies and the connectors for the storages
......@@ -11,6 +13,7 @@ depending on type of storages being used):
<!-- jio + dependency -->
<script src="md5.js"></script>
<script src="complex-queries.js"></script>
<script src="jio.js"></script>
<!-- jio storage libraries -->
<script src="localstorage.js">
......@@ -20,7 +23,7 @@ depending on type of storages being used):
Then create your jIO instance like this:
// create a new jio (type = localStorage)
var jio = jIO.newJio({
var jio_instance = jIO.newJio({
"type": "local",
"username": "your_username",
"application_name": "your_application_name"
......@@ -28,34 +31,34 @@ Then create your jIO instance like this:
### Documents and Methods
Documents are JSON strings that contain _meta-data_ (properties, like a filename)
and _attachments_ (optional content, for example a base64 encoded image).
Documents are JSON strings that contain *meta-data* (properties, like a filename)
and *attachments* (optional content, for example a base64 encoded image).
jIO exposes the following methods to _create_, _read_, _update_ and _delete_ documents
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):
// create and store new document
jio.post({"title": "some title"}, function (err, response) {
jio_instance.post({"title": "some title"}, function (err, response) {
// console.log(response):
// {"ok": "true", "id": "cabc9...826" }
// {"ok": "true", "id": "cabc9...826" } // Generated id
});
// create or update an existing document
jio.put({"_id": "my_document", "title": "New Title"}, function (err, response) {
// console.log(response):
// {"ok": "true", "id": "my_document"}
jio_instance.put({"_id": "my_document", "title": "New Title"}, function (err, response) {
// console.log(response):
// {"ok": "true", "id": "my_document"}
});
// add an attachement to a document
jio.putAttachment({"_id": "my_document", "_attachment": "its_attachment",
"_data":"abc", "_mimetype": "text/plain"}, function (err, response) {
jio_instance.putAttachment({"_id": "my_document", "_attachment": "its_attachment",
"_data":"abc", "_mimetype": "text/plain"}, function (err, response) {
// console.log(response):
// {"ok":"true", "id": "my_document", "attachment": "its_attachment"}
});
// read a document
jio.get({"_id": "my_document"}, function (err, response) {
jio_instance.get({"_id": "my_document"}, function (err, response) {
// console.log(response);
// {
// "_id": "my_document",
......@@ -71,36 +74,36 @@ each method, please refer to the documentation):
});
// read an attachement
jio.getAttachment({"_id": "my_document", "_attachment": "its_attachment"}, function (err, response) {
jio_instance.getAttachment({"_id": "my_document", "_attachment": "its_attachment"}, function (err, response) {
// console.log(response);
// "<Base64 Image>"
});
// delete a document and its attachment(s)
jio.remove({"_id": "my_document"}, function (err, response) {
jio_instance.remove({"_id": "my_document"}, function (err, response) {
// console.log(response):
// {"ok": "true", "id": "my_document"}
});
// delete an attachement
jio.removeAttachment({"_id": "my_document", "_attachment": "its_attachment"}, function (err, response) {
jio_instance.removeAttachment({"_id": "my_document", "_attachment": "its_attachment"}, function (err, response) {
// console.log(response):
// {"ok": true, "id": "my_document", "attachment": "its_attachment"}
});
// get all documents
jio.allDocs(function (err, response){
jio_instance.allDocs(function (err, response){
// console.log(response):
// {
// "total_rows": 1,
// "rows": [{
// "id": "my_document",
// "key": "my_document",
// "value": {}
// }]
// }
});
### Example
This is an example of how to store a video file with one attachment in local
......@@ -108,13 +111,13 @@ storage . Note that attachments should best be added inside one of the available
document callback methods (success & error or callback)
// create a new localStorage
var jio = JIO.newJio({
"type":"local",
var jio_instance = jIO.newJio({
"type":"local",
"username":"user",
"application_name":"app"
});
// post the document
jio.post({
jio_instance.post({
"_id" : "myVideo",
"title" : "My Video",
"videoCodec" : "vorbis",
......@@ -125,7 +128,7 @@ document callback methods (success & error or callback)
alert('Error when posting the document description');
} else {
// if successful, add video attachment (base64 encoded)
jio.putAttachment({
jio_instance.putAttachment({
"_id": "myVideo/video",
"_data": Base64(my_video),
"_mimetype":"video/ogg"
......@@ -147,136 +150,139 @@ like revision management or indices to a child storage (sub_storage).
The following storages are currently supported:
DummyStorage (custom storage prototype)
- LocalStorage (browser local storage)
// initialize a dummy storage
var jio = JIO.newJio({
"type": <string>
});
// initialize a local storage
var jio_instance = jIO.newJio({
"type" : "local",
"username" : "me"
});
LocalStorage (browser local storage)
- DAVStorage (connect to webDAV)
// initialize a local storage
var jio = JIO.newJio({
"type" : "local",
"username" : <string>,
"application_name" : <string>
});
// initialize a webDAV storage
var jio_instance = jIO.newJio({
"type" : "dav",
"url" : "http://my.dav.srv/uploads",
"auth_type": "basic",
"username" : "me",
"password" : "pwd"
});
DAVStorage (connect to webDAV)
- xWiki storage (connect to xWiki)
// initialize a webDAV storage
var jio = JIO.newJio({
"type" : "dav",
"username" : <string>,
"password" : <string>,
"url" : <string>
});
// initialize a connection to xWiki
var jio_instance = jIO.newJio({
"type": "xwiki",
"xwikiurl": "http://my.site.com/xwiki",
"username": "me",
"password": "pwd"
});
xWiki storage (connect to xWiki)
// initialize a connection to xWiki storage
coming soon
S3 storage (connect to S3)
// initialize a connection to S3 storage
coming soon
IndexStorage (maintains indices of documents in a substorage)
// initialize an indexStorage (for a local storage)
var jio = JIO.newJio({
"type": "indexed",
"sub_storage": {
"type": "local",
"username": <string>,
"application_name": <string>
},
// create two indices for the substorage with fields A and A,B
"indices": [
{"name":<string>, "fields":[<string A>]},
{"name":<string>, "fields":[<string A>, <string B>]}
],
// pass the field type into the index
"field_types": {
<string A>: "string",
<string B>: "number"
}
});
- S3 storage (connect to S3)
CryptStorage (encrypt/decrypt substorage files)
// initialize a connection to S3 storage
var jio_instance = jIO.newJio({
"type": "s3",
"AWSIdentifier": "AWS Identifier ID",
"password": "AWS Secret key",
"server": "Destination bucket"
});
// initialize a cryptStorage (to encrypt data on a storage)
coming soon
- IndexStorage (maintains indices of documents in a substorage)
// initialize an indexStorage (for a local storage)
var jio_instance = jIO.newJio({
"type": "indexed",
"sub_storage": {
"type": "local" // for instance
"username": "me"
},
"indices": [{
"id": "index_database.json",
"index": ["title", "author", "subject", "posted_date"]
}, {
...
}]
});
Revision Storage (add revision management to a substorage)
- SplitStorage (simply split data into several parts):
// initialize a revison storage on a local storage
// (revision-format 1-9ccd039de0674d935f3c6bae61afc9b7038d1df97d586507aa62336a02f9ee2a)
var jio = JIO.newJio({
"type": "revision",
"sub_storage": {
"type": "local",
"username": <string>,
"application_name": <string>
}
});
// initialize a splitStorage
var jio_instance = jIO.newJio({
"type": "split",
"storage_list": [<storage description>, ...]
});
Replicate Revision Storage (replicate documents across multiple storages)
// initialize a replicate revision storage (with local and webDAV as substorages)
var jio = JIO.newJio({
"type": "replicaterevision",
"storage_list": [{
"type": "revision",
"sub_storage": {
"type": "local",
"username": <string>,
"application_name": <string>
}
}, {
"type": "revision",
"sub_storage": {
"type" : "dav",
"username" : <string>,
"password" : <string>,
"url" : <string>
}
}]
});
- Revision Storage (add revision management to a substorage)
// initialize a revison storage on a local storage
// (revision-format 1-9ccd039de0674d935f3c6bae61afc9b7038d1df97d586507aa62336a02f9ee2a)
var jio_instance = jIO.newJio({
"type": "revision",
"sub_storage": {
"type": "local",
"username": "me"
}
});
- Replicate Revision Storage (replicate documents across multiple storages)
// initialize a replicate revision storage (with local and webDAV as substorages)
var jio_instance = jIO.newJio({
"type": "replicaterevision",
"storage_list": [{
"type": "revision",
"sub_storage": {
"type": "local",
"username": "me"
}
}, {
"type": "revision",
"sub_storage": {
"type" : "dav",
"auth_type": "basic",
"username" : "me",
"password" : "pwd",
"url" : "http://my.dav.srv/uploads"
}
}]
});
For more information on the specific storages including guidelines on how to create your own connector, please also refer to the documentation.
- And more!
For more information on the specific storages including guidelines on how to
create your own connector, please also refer to the documentation.
### Complex Queries
jIO includes a complex-queries manager, which can be run on top of the allDocs()
jIO uses complex-queries manager, which can be run on top of the allDocs()
method to query documents in the storage tree. A sample query would look like
this (note, that allDocs and complex queries cannot be run on every storage and
that pre-querying of documents on distant storages should best be done
server-side):
// run allDocs with query option on an existing jIO
jio.allDocs({
"query":{
"query": '(fieldX: >= <string> AND fieldY: < <string>)',
"filter": {
// 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>]
},
"wildcard_character": '%'
}
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>]
}, function (err, response) {
// console.log(response):
// [{
// "id": <string>,
// <string A>: <string>,
// <string B>: <string>
// }]
// {
// "total_rows": 1,
// "rows": [{
// "id": <string>,
// "value": {
// <string A>: <string>,
// <string B>: <string>
// }
// }, { .. }]
// }
});
To find out more about complex queries, please refer to the documentation
......@@ -285,8 +291,7 @@ To find out more about complex queries, please refer to the documentation
jIO is running a task queue manager in the background which processes incoming
tasks according to set of defined rules. To find out more and including how to
define your own execution rules, please refer to the
[documentation](https://www.j-io.org/documentation).
define your own execution rules, please refer to the documentation.
### Conflict Management
......@@ -294,7 +299,7 @@ As jIO allows to manage and share documents across multiple storage locactions
it is likely for conflicts to occur (= multiple versions of a single document
existing in the storage tree). jIO manages conflicts by ensuring that every
version of a document is available on every storage and that conflicts are
accessible (and solvable) using the `conflicts: true` option when using the
accessible (and solvable) using the *conflicts: true* option when using the
respective jIO methods. For more info on conflicts and available options, please
refer to the documentation.
......@@ -313,5 +318,4 @@ when the page is reloaded after a browser crash.
### 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).
information on LGPL can be found [here](http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License).
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7