Rappid - storage

storage.Local

storage.Local plugin gives you a convenient way to store documents (especially JointJS graphs and cells) to the client-side HTML 5 localStorage. This browser storage allows you to store data in the browser similar to cookies but with a greatly enhanced capacity and no information stored in the HTTP request header.

The standard HTML 5 localStorage is a simple key-value store where both keys and values are strings. Therefore, it is on the programmer to invent a way of storing and retrieving more complex data structures. storage.Local make this abstraction for you and its API, though overly simplified, resembles APIs for common NoSQL document object stores such as MongoDB.

Install

Include joint.storage.local.js file into your HTML:

<script src="joint.storage.local.js"></script>

Usage

joint.storage.Local is a singleton object with three basic methods: insert(), find() and remove(). It behaves like a single database with collections of objects. You can add, remove and search objects in each collection. Objects can be any JavaScript objects or JointJS elements, links or graphs. Currently, joint.storage.Local indexes objects in collections by their IDs only. It is important to note that all the methods are asynchronous. This means that the callback is defered until the current JavaScript call stack has cleared (similar to setTimeout with a delay of 0). This is because we want to keep the API similar to other NoSQL databases and so if you later decide to store your documents in e.g. MongoDB instead, you don't have to make drastic changes to your application. Instead, you can just write a simple replacement for joint.storage.Local and store your documents e.g. via AJAX on the server.

var graph = new joint.dia.Graph;
(new joint.shapes.basic.Rect).addTo(graph);

// Insert a graph into the collection 'graphs'.
joint.storage.Local.insert('graphs', graph);
// Find all the graphs in the collection 'graphs'.
joint.storage.Local.find('graphs', {}, function(err, graphs) {});
// Find a graph with ID 'mygraph' in the collection 'graphs'.
joint.storage.Local.find('graphs', { id: 'mygraph' }, function(err, graphs) {});
// Remove all the graphs from the collection 'graphs'.
joint.storage.Local.remove('graphs', {}, function(err) {});
// Remove a graph from the collection 'graphs'.
joint.storage.Local.remove('graphs', { id: 'mygraph' }, function(err) {});

API

insert(collection, doc [, callback]) Insert a document doc into the collection. Optionally pass a callback(err, doc). If the document doc didn't have an id property, one is automatically created and will be part of the doc object returned in the callback.
find(collection, query, callback) Find a document in collection. query can currently be either empty in which case all the documents from the collection are returned or it can contain id of a document in which case only a document with that id is returned. callback signature is: callback(err, docs).
remove(collection, query [, callback]) Remove a document from the collection. query can currently be either empty in which case all the documents from the collection are removed or it can contain an id of the document to be removed. callback signature is: callback(err).