To set up jIO, include the source file, dependencies and connectors for the storages you plan to use in your page header (dependencies vary depending on the types of storages being used):
To set up jIO include jio.js, dependencies and the connectors for the storages
```
you want to use in your page header (note that more dependencies may be required
<!-- jio core-->
depending on type of storages being used):
<script src="jio.js"></script>
<!-- jio dependencies-->
<!-- jio + dependency -->
<script src="md5.js"></script>
<script src="md5.js"></script>
<!-- jio storage connectors -->
<script src="jio.js"></script>
<script src="localstorage.js">
<!-- jio storage libraries -->
<script ...>
<script src="localstorage.js">
<!-- jio complex queries -->
<script src="revisionstorage.js">
<script src="jio.complex_queries.js"></script>
<script ...>
```
Then create your jIO instance like this:
Then create your jIO instance like this:
```
var jio = jIO.newJio({
// create a new jio (type = localStorage)
"type": "local",
var jio = jIO.newJio({
"username": "your_username",
"type": "local",
"application_name": "your_application_name"
"username": "your_username",
});
"application_name": "your_application_name"
```
});
Documents and Methods
## Documents and Methods
-------------------------------------------------
Documents are JSON strings that contain <em><u>meta-data</u></em>
Documents are JSON strings that contain _meta-data_ (properties, like a filename)
(properties, e.g. filename) and <em><u>attachments</u></em> (optional content, e.g. a base64-encoded image).
and _attachments_ (optional content, for example a base64 encoded image).
jIO exposes the following methods to <em><u>create</u></em>,
jIO exposes the following methods to _create_, _read_, _update_ and _delete_ documents
<em><u>read</u></em>, <em><u>update</u></em> and <em><u>delete</u></em> documents:
(for more information, including revision management and available options for
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.post({"title": "some title"}, function (err, response) {
// console.log(response):
// console.log(response):
// {"ok":"true", "id":"cabc9...826" }
// {"ok": "true", "id": "cabc9...826" }
});
});
// create or update an existing document
// create or update an existing document
jio.put({"_id":"demoID", "title":"new title"}, function (err, response) {
jio.put({"_id": "my_document", "title": "New Title"}, function (err, response) {
// console.log(response):
// console.log(response):
// {"ok":"true", "id":"demoID" }
// {"ok": "true", "id": "my_document"}
});
});
// add an attachement to a document (Note: no underscore on id!)
This is an example of how to store a video file with an attachment in
// get all documents
local storage. Note that attachments should best be added inside one of the available document callback methods (success & error or callback).
jio.allDocs(function (err, response){
```
// console.log(response):
// create a new localStorage
// {
var jio = JIO.newJio({
// "total_rows": 1,
"type":"local",
// "rows": [{
"username":"user",
// "id": "my_document",
"application_name":"app"
// "key": "my_document",
});
// "value": {}
// post the document
// }]
jio.post(
// }
{
});
"_id" : "myVideo",
"title" : "My Video",
## Example
"videoCodec" : "vorbis",
"language" : "en",
This is an example of how to store a video file with one attachment in local
"description" : "Images Compilation"
storage . Note that attachments should best be added inside one of the available
},
document callback methods (success & error or callback)
function (err, response) {
if (err) {
// create a new localStorage
alert('Error when posting the document description');
var jio = JIO.newJio({
} else {
"type":"local",
// if successful, add video attachment (base64 encoded)
"username":"user",
jio.putAttachment(
"application_name":"app"
{
});
"id": "myVideo/video",
// post the document
"data": Base64(my_video),
jio.post({
"mimetype":"video/ogg"
"_id" : "myVideo",
},
"title" : "My Video",
function (err, response) {
"videoCodec" : "vorbis",
"language" : "en",
"description" : "Images Compilation"
}, function (err, response) {
if (err) {
alert('Error when posting the document description');
} else {
// if successful, add video attachment (base64 encoded)
jio.putAttachment({
"_id": "myVideo/video",
"_data": Base64(my_video),
"_mimetype":"video/ogg"
}, function (err, response) {
if (err) {
if (err) {
alert('Error when attaching the video');
alert('Error when attaching the video');
} else {
} else {
alert('Video Stored');
alert('Video Stored');
}
}
}
});
);
}
}
});
}
);
## Storage Locations
```
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
jIO allows to build "storage trees" consisting of connectors to multiple storages (webDav, xWiki, S3, localStorage) and use storage handlers to add features like revision management or indices to a child storage (sub_storage).
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)**
DummyStorage (custom storage prototype)
```
// initialize a dummy storage
// initialize a dummy storage
var jio = JIO.newJio({
var jio = JIO.newJio({
"type": <string>
"type": <string>
});
});
```
**LocalStorage (browser local storage)**
LocalStorage (browser local storage)
```
// initialize a local storage
// initialize a local storage
var jio = JIO.newJio({
var jio = JIO.newJio({
"type" : "local",
"type" : "local",
"username" : <string>,
"username" : <string>,
"application_name" : <string>
"application_name" : <string>
});
});
```
**DAVStorage (connect to webDAV)**
DAVStorage (connect to webDAV)
```
// initialize a webDAV storage
// initialize a webDAV storage
var jio = JIO.newJio({
var jio = JIO.newJio({
"type" : "dav",
"username" : <string>,
"password" : <string>,
"application_name" : <string>,
"url" : <string>
});
```
**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>]}
**Replicate Revision Storage (replicate documents across multiple storages)**
```
// initialize a replicate revision storage (with local, 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",
"type" : "dav",
"username" : <string>,
"username" : <string>,
"password" : <string>,
"password" : <string>,
"application_name" : <string>,
"url" : <string>
"url" : <string>
}
});
}]
});
xWiki storage (connect to xWiki)
```
For more information on the specific storages including guidelines on how to create your own connector, please refer to the documentation.
// initialize a connection to xWiki storage
coming soon
Complex Queries
-------------------------------------------------
S3 storage (connect to S3)
jIO includes a complex-queries manager, which can be run on top of the
<em>allDocs()</em> method to query documents in the storage tree. A
// initialize a connection to S3 storage
sample query would look like this (note, that <em>allDocs</em> and complex queries cannot be run on every storage and that pre-querying of documents on distant storages should best be done server-side):
coming soon
```
IndexStorage (maintains indices of documents in a substorage)
// run allDocs with query option on an existing jIO
jio.allDocs({
// initialize an indexStorage (for a local storage)
"query":{
var jio = JIO.newJio({
"query":'(fieldX: >= <string> AND fieldY: < <string>)',
"type": "indexed",
"filter": {
"sub_storage": {
// records to display ("from to")
"type": "local",
"limit":[0,5],
"username": <string>,
// sort by
"application_name": <string>
"sort_on":[[<string A>,'descending']],
// fields to return in response
"select_list":[<string A>;,<string B>]
},
},
"wildcard_character":'%'
// create two indices for the substorage with fields A and A,B
}
"indices": [
},function(err, response){
{"name":<string>, "fields":[<string A>]},
// console.log(response):
{"name":<string>, "fields":[<string A>, <string B>]}
// [{
],
// "id": <string>,
// pass the field type into the index
// <string A>: <string>,
"field_types": {
// <string B>: <string>
<string A>: "string",
// }]
<string B>: "number"
}
}
});
});
```
Task Management
CryptStorage (encrypt/decrypt substorage files)
-------------------------------------------------
jIO is running a task queue manager in the background which processes
// initialize a cryptStorage (to encrypt data on a storage)
incoming tasks according to set of defined rules. To find out
coming soon
more and including how to define your own execution rules, please refer to the documentation.
Revision Storage (add revision management to a substorage)
Conflict Management
-------------------------------------------------
// initialize a revison storage on a local storage
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 <em><u>conflicts:true</u></em> option when using the respective jIO methods. For more info on conflicts and available options, please refer to the documentation.
var jio = JIO.newJio({
"type": "revision",
Crash-Proof
"sub_storage": {
-------------------------------------------------
"type": "local",
All tasks are managed inside the browser local storage so no data is lost, as the task manager queue will persist through browser crashes and continues to run when the page is reloaded after a browser crash.
"username": <string>,
"application_name": <string>
Authors
}
-------------------------------------------------
});
+ Francois Billioud
+ Tristan Cavelier
Replicate Revision Storage (replicate documents across multiple storages)
Copyright and license
// initialize a replicate revision storage (with local and webDAV as substorages)
-------------------------------------------------
var jio = JIO.newJio({
jIO is an open-source library and is licensed under the LGPL license. More information on LGPL can be found <ahref="http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License">here</a>.
"type": "replicaterevision",
"storage_list": [{
Documentation
"type": "revision",
=============
"sub_storage": {
You can find the full documentation here: [jIO Documentation](http://www.j-io.org/documentation).
"type": "local",
"username": <string>,
For developers
"application_name": <string>
==============
}
Quick start
}, {
-------------------------------------------------
"type": "revision",
To get started with jIO, clone one of the repositories on
jIO uses a <ahref="http://git.erp5.org/gitweb/jio.git/blob_plain/HEAD:/Makefile?js=1">makeFile</a> to build and compress the necessary files (jIO.js and complex-queries.js). To run the makeFile you will require the following:
}
}]
+[NodeJS](http://nodejs.org/)(including NPM)
});
+[JSLint](https://github.com/jslint/jslint)
+[UglifyJS](https://github.com/mishoo/UglifyJS)
For more information on the specific storages including guidelines on how to create your own connector, please also refer to the documentation.
The repository also includes the built ready-to-use files, so in case you do not want to build jIO yourself, just use <em>jio.min.js</em> as well as <em>complex-queries.min.js</em> plus the storages and dependencies you need and you will be good to go.
jIO includes a complex-queries manager, which can be run on top of the allDocs()
You can also check out the jIO QUnit tests (jiotests_withoutrequirejs.html) for an overview on how to create a page
method to query documents in the storage tree. A sample query would look like
[setup](http://git.erp5.org/gitweb/jio.git/blob/HEAD:/test/jiotests_withoutrequirejs.html?js=1) with required scripts as well as setting up jIO itself
this (note, that allDocs and complex queries cannot be run on every storage and
[setup](http://git.erp5.org/gitweb/jio.git/blob/HEAD:/test/jiotests.js?js=1). If you want to run the QUnit tests
that pre-querying of documents on distant storages should best be done
locally after cloning the repo, please make sure you have the above minified files in your repository.
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": '%'
}
}, function (err, response) {
// console.log(response):
// [{
// "id": <string>,
// <string A>: <string>,
// <string B>: <string>
// }]
});
To find out more about complex queries, please refer to the documentation
### Task Management
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
