Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
jio
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
0
Merge Requests
0
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
Aurélien Vermylen
jio
Commits
37c7c418
Commit
37c7c418
authored
Aug 09, 2013
by
Tristan Cavelier
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
README.md updated
parent
127b6558
Changes
1
Show whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
137 additions
and
133 deletions
+137
-133
README.md
README.md
+137
-133
No files found.
README.md
View file @
37c7c418
...
@@ -3,6 +3,8 @@
...
@@ -3,6 +3,8 @@
**
jIO is a client-side JavaScript library to manage documents across multiple
**
jIO is a client-side JavaScript library to manage documents across multiple
storages.
**
storages.
**
<!-- \index-and-table 3 -->
### Getting Started
### Getting Started
To set up jIO include jio.js, dependencies and the connectors for the storages
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):
...
@@ -11,6 +13,7 @@ depending on type of storages being used):
<!-- jio + dependency -->
<!-- jio + dependency -->
<script src="md5.js"></script>
<script src="md5.js"></script>
<script src="complex-queries.js"></script>
<script src="jio.js"></script>
<script src="jio.js"></script>
<!-- jio storage libraries -->
<!-- jio storage libraries -->
<script src="localstorage.js">
<script src="localstorage.js">
...
@@ -20,7 +23,7 @@ depending on type of storages being used):
...
@@ -20,7 +23,7 @@ depending on type of storages being used):
Then create your jIO instance like this:
Then create your jIO instance like this:
// create a new jio (type = localStorage)
// create a new jio (type = localStorage)
var jio = jIO.newJio({
var jio
_instance
= jIO.newJio({
"type": "local",
"type": "local",
"username": "your_username",
"username": "your_username",
"application_name": "your_application_name"
"application_name": "your_application_name"
...
@@ -28,34 +31,34 @@ Then create your jIO instance like this:
...
@@ -28,34 +31,34 @@ Then create your jIO instance like this:
### Documents and Methods
### Documents and Methods
Documents are JSON strings that contain
_meta-data_
(properties, like a filename)
Documents are JSON strings that contain
*meta-data*
(properties, like a filename)
and
_attachments_
(optional content, for example a base64 encoded image).
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
(for more information, including revision management and available options for
each method, please refer to the documentation):
each method, please refer to the documentation):
// create and store new document
// 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):
// console.log(response):
// {"ok": "true", "id": "cabc9...826" }
// {"ok": "true", "id": "cabc9...826" }
// Generated id
});
});
// create or update an existing document
// create or update an existing document
jio.put({"_id": "my_document", "title": "New Title"}, function (err, response) {
jio
_instance
.put({"_id": "my_document", "title": "New Title"}, function (err, response) {
// console.log(response):
// console.log(response):
// {"ok": "true", "id": "my_document"}
// {"ok": "true", "id": "my_document"}
});
});
// add an attachement to a document
// add an attachement to a document
jio.putAttachment({"_id": "my_document", "_attachment": "its_attachment",
jio
_instance
.putAttachment({"_id": "my_document", "_attachment": "its_attachment",
"_data":"abc", "_mimetype": "text/plain"}, function (err, response) {
"_data":"abc", "_mimetype": "text/plain"}, function (err, response) {
// console.log(response):
// console.log(response):
// {"ok":"true", "id": "my_document", "attachment": "its_attachment"}
// {"ok":"true", "id": "my_document", "attachment": "its_attachment"}
});
});
// read a document
// read a document
jio.get({"_id": "my_document"}, function (err, response) {
jio
_instance
.get({"_id": "my_document"}, function (err, response) {
// console.log(response);
// console.log(response);
// {
// {
// "_id": "my_document",
// "_id": "my_document",
...
@@ -71,36 +74,36 @@ each method, please refer to the documentation):
...
@@ -71,36 +74,36 @@ each method, please refer to the documentation):
});
});
// read an attachement
// 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);
// console.log(response);
// "<Base64 Image>"
// "<Base64 Image>"
});
});
// delete a document and its attachment(s)
// 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):
// console.log(response):
// {"ok": "true", "id": "my_document"}
// {"ok": "true", "id": "my_document"}
});
});
// delete an attachement
// 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):
// console.log(response):
// {"ok": true, "id": "my_document", "attachment": "its_attachment"}
// {"ok": true, "id": "my_document", "attachment": "its_attachment"}
});
});
// get all documents
// get all documents
jio.allDocs(function (err, response){
jio
_instance
.allDocs(function (err, response){
// console.log(response):
// console.log(response):
// {
// {
// "total_rows": 1,
// "total_rows": 1,
// "rows": [{
// "rows": [{
// "id": "my_document",
// "id": "my_document",
// "key": "my_document",
// "value": {}
// "value": {}
// }]
// }]
// }
// }
});
});
### Example
### Example
This is an example of how to store a video file with one attachment in local
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
...
@@ -108,13 +111,13 @@ storage . Note that attachments should best be added inside one of the available
document callback methods (success & error or callback)
document callback methods (success & error or callback)
// create a new localStorage
// create a new localStorage
var jio
= J
IO.newJio({
var jio
_instance = j
IO.newJio({
"type":"local",
"type":"local",
"username":"user",
"username":"user",
"application_name":"app"
"application_name":"app"
});
});
// post the document
// post the document
jio.post({
jio
_instance
.post({
"_id" : "myVideo",
"_id" : "myVideo",
"title" : "My Video",
"title" : "My Video",
"videoCodec" : "vorbis",
"videoCodec" : "vorbis",
...
@@ -125,7 +128,7 @@ document callback methods (success & error or callback)
...
@@ -125,7 +128,7 @@ document callback methods (success & error or callback)
alert('Error when posting the document description');
alert('Error when posting the document description');
} else {
} else {
// if successful, add video attachment (base64 encoded)
// if successful, add video attachment (base64 encoded)
jio.putAttachment({
jio
_instance
.putAttachment({
"_id": "myVideo/video",
"_id": "myVideo/video",
"_data": Base64(my_video),
"_data": Base64(my_video),
"_mimetype":"video/ogg"
"_mimetype":"video/ogg"
...
@@ -147,136 +150,139 @@ like revision management or indices to a child storage (sub_storage).
...
@@ -147,136 +150,139 @@ like revision management or indices to a child storage (sub_storage).
The following storages are currently supported:
The following storages are currently supported:
DummyStorage (custom storage prototype)
-
LocalStorage (browser local storage)
// initialize a dummy storage
var jio = JIO.newJio({
"type": <string>
});
LocalStorage (browser local storage)
// initialize a local storage
// initialize a local storage
var jio = J
IO.newJio({
var jio_instance = j
IO.newJio({
"type" : "local",
"type" : "local",
"username" : <string>,
"username" : "me"
"application_name" : <string>
});
});
DAVStorage (connect to webDAV)
-
DAVStorage (connect to webDAV)
// initialize a webDAV storage
// initialize a webDAV storage
var jio = J
IO.newJio({
var jio_instance = j
IO.newJio({
"type" : "dav",
"type" : "dav",
"username" : <string>,
"url" : "http://my.dav.srv/uploads",
"password" : <string>,
"auth_type": "basic",
"url" : <string>
"username" : "me",
"password" : "pwd"
});
});
xWiki storage (connect to xWiki)
-
xWiki storage (connect to xWiki)
// initialize a connection to xWiki storage
// initialize a connection to xWiki
coming soon
var jio_instance = jIO.newJio({
"type": "xwiki",
"xwikiurl": "http://my.site.com/xwiki",
"username": "me",
"password": "pwd"
});
S3 storage (connect to S3)
-
S3 storage (connect to S3)
// initialize a connection to S3 storage
// initialize a connection to S3 storage
coming soon
var jio_instance = jIO.newJio({
"type": "s3",
"AWSIdentifier": "AWS Identifier ID",
"password": "AWS Secret key",
"server": "Destination bucket"
});
IndexStorage (maintains indices of documents in a substorage)
-
IndexStorage (maintains indices of documents in a substorage)
// initialize an indexStorage (for a local storage)
// initialize an indexStorage (for a local storage)
var jio = J
IO.newJio({
var jio_instance = j
IO.newJio({
"type": "indexed",
"type": "indexed",
"sub_storage": {
"sub_storage": {
"type": "local",
"type": "local" // for instance
"username": <string>,
"username": "me"
"application_name": <string>
},
},
// create two indices for the substorage with fields A and A,B
"indices": [{
"indices": [
"id": "index_database.json",
{"name":<string>, "fields":[<string A>]},
"index": ["title", "author", "subject", "posted_date"]
{"name":<string>, "fields":[<string A>, <string B>]}
}, {
],
...
// pass the field type into the index
}]
"field_types": {
<string A>: "string",
<string B>: "number"
}
});
});
CryptStorage (encrypt/decrypt substorage files)
-
SplitStorage (simply split data into several parts):
// initialize a cryptStorage (to encrypt data on a storage)
// initialize a splitStorage
coming soon
var jio_instance = jIO.newJio({
"type": "split",
"storage_list": [<storage description>, ...]
});
Revision Storage (add revision management to a substorage)
-
Revision Storage (add revision management to a substorage)
// initialize a revison storage on a local storage
// initialize a revison storage on a local storage
// (revision-format 1-9ccd039de0674d935f3c6bae61afc9b7038d1df97d586507aa62336a02f9ee2a)
// (revision-format 1-9ccd039de0674d935f3c6bae61afc9b7038d1df97d586507aa62336a02f9ee2a)
var jio = J
IO.newJio({
var jio_instance = j
IO.newJio({
"type": "revision",
"type": "revision",
"sub_storage": {
"sub_storage": {
"type": "local",
"type": "local",
"username": <string>,
"username": "me"
"application_name": <string>
}
}
});
});
Replicate Revision Storage (replicate documents across multiple storages)
-
Replicate Revision Storage (replicate documents across multiple storages)
// initialize a replicate revision storage (with local and webDAV as substorages)
// initialize a replicate revision storage (with local and webDAV as substorages)
var jio = J
IO.newJio({
var jio_instance = j
IO.newJio({
"type": "replicaterevision",
"type": "replicaterevision",
"storage_list": [{
"storage_list": [{
"type": "revision",
"type": "revision",
"sub_storage": {
"sub_storage": {
"type": "local",
"type": "local",
"username": <string>,
"username": "me"
"application_name": <string>
}
}
}, {
}, {
"type": "revision",
"type": "revision",
"sub_storage": {
"sub_storage": {
"type" : "dav",
"type" : "dav",
"username" : <string>,
"auth_type": "basic",
"password" : <string>,
"username" : "me",
"url" : <string>
"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
### 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
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
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
that pre-querying of documents on distant storages should best be done
server-side):
server-side):
// run allDocs with query option on an existing jIO
// run allDocs with query option on an existing jIO
jio.allDocs({
jio_instance.allDocs({
"query":{
"query": '(fieldX: >= "string" AND fieldY: < "string")',
"query": '(fieldX: >= <string> AND fieldY: < <string>)',
"filter": {
// records to display ("from to")
// records to display ("from to")
"limit": [0, 5],
"limit": [0, 5],
// sort by
// sort by
"sort_on": [[<string A>, 'descending']],
"sort_on": [[<string A>, 'descending']],
// fields to return in response
// fields to return in response
"select_list": [<string A>, <string B>]
"select_list": [<string A>, <string B>]
},
"wildcard_character": '%'
}
}, function (err, response) {
}, function (err, response) {
// console.log(response):
// console.log(response):
// [{
// {
// "total_rows": 1,
// "rows": [{
// "id": <string>,
// "id": <string>,
// "value": {
// <string A>: <string>,
// <string A>: <string>,
// <string B>: <string>
// <string B>: <string>
// }]
// }
// }, { .. }]
// }
});
});
To find out more about complex queries, please refer to the documentation
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
...
@@ -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
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
tasks according to set of defined rules. To find out more and including how to
define your own execution rules, please refer to the
define your own execution rules, please refer to the documentation.
[
documentation
](
https://www.j-io.org/documentation
)
.
### Conflict Management
### Conflict Management
...
@@ -294,7 +299,7 @@ As jIO allows to manage and share documents across multiple storage locactions
...
@@ -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
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
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
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
respective jIO methods. For more info on conflicts and available options, please
refer to the documentation.
refer to the documentation.
...
@@ -313,5 +318,4 @@ when the page is reloaded after a browser crash.
...
@@ -313,5 +318,4 @@ when the page is reloaded after a browser crash.
### Copyright and license
### Copyright and license
jIO is an open-source library and is licensed under the LGPL license. More
jIO is an open-source library and is licensed under the LGPL license. More
information on LGPL can be found
information on LGPL can be found
[
here
](
http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License
)
.
[
here
](
http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License
)
.
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment