chainpad-listmap
v1.1.0
Published
collaborative lists and maps in the browser.
Downloads
433
Readme
chainpad-listmap
collaborative lists and maps in the browser.
Usage
Best used in conjunction with Chainpad-server.
define([
'/api/config',
'/bower_components/chainpad-listmap/chainpad-listmap.js',
'/bower_components/chainpad-crypto/crypto.js'
], function (Config, Listmap, Crypto) {
var rt = Listmap.create({
websocketURL: Config.websocketURL,
channel: "b87dff2e9a465f0e0ae36453d19b087c",
cryptKey: "sksyaHv+OOlQumRmZrQU4f5N",
data: {},
crypto: Crypto
});
var proxy = rt.proxy.on('ready', function () {
window.alert("realtime proxy object is ready to use!");
// listen for changes anywhere within the nested structure
proxy.on('change', [], function (oldValue, newValue, path) {
console.log("Realtime object was changed at path [%s]: %s => %s",
path.join(','), oldvalue, newvalue);
})
// or listen for changes at specific paths (or children thereof)
.on('change', ['one', 2, 'three'], function (o, n, p) {
console.log("Realtime object was changed at path [%s]: %s => %s",
path.join(','), oldvalue, newvalue);
// return `false` to prevent this event from 'bubbling up'
return false;
});
}).on('disconnect', function () {
window.alert("network connection lost!");
});
});
API
Listmap.create
Listmap.create
is a function which takes a configuration object consisting of the following attributes:
- websocketURL
- channel
- cryptKey
- crypto
- data
With the exception of data
, all configuration paramaters match those documented in chainpad-netflux, on which chainpad-listmap depends.
data
is used to generate initialState
, which is supplied to chainpad-netflux.
Chainpad expects that all users in a session will supply the same initialState, so unless you can guarantee that all users will provide an identical argument here, it is best to initialize data with an empty array or object.
chainpad-listmap supports both, but has been tested more extensively using objects.
Listmap.create
will return an object with the following properties:
- realtime
- the chainpad realtime object, in case you ever want to interact with chainpad directly
- proxy
- the realtime list or map that was created based on your supplied
data
attribute
- the realtime list or map that was created based on your supplied
- network
- the Netflux network object created and used by
chainpad-netflux
as a transport layer for your realtime object's messages.
- the Netflux network object created and used by
Listmap.create().proxy
For most purposes, this is the object you'll be interacting with most frequently.
Arrays
If you created your proxy using using an array (aka a list ([]
)) for a data attribute, you will be able to use the usual in-place array methods (push, pop, shift, unshift, sort).
Methods which return new arrays (map, slice, filter) will not trigger events.
Objects
If you created your proxy using an object (aka a map ({}
)) for a data attribute, it will behave as expected.
proxy.on
The List/Map api provides a means of listening to a variety of events related to your realtime proxy:
on('create', cb)
Corresponds to chainpad-netflux#onInit.
on('ready', cb)
Corresponds to chainpad-netflux#onReady
on('disconnect', cb)
Corresponds to chainpad-netflux#onAbort
on('change', path, cb)
Listen for changes which match a given path, where cb
is a callback, and path is an array of property names which would select the targeted property given the root object.
For example:
var A = {
b: [
0,
1,
{
c: 5
}
]
};
c
could be selected given the path ['b', 2, 'c']
.
Changes bubble up, so if you were to specify a path ['b', 2]
, changes to ['b', 2, 'c']
would trigger that listener.
Callbacks take the form:
function (oldvalue, newvalue, path, rootObject) {
// do things
};
To prevent a change from bubbling up, return false
from your callback, as you would with DOM event listeners.
Deletions are considered a change for the directly affected value.
If that value is an array or object, all of its children will be the subject of a remove
event.
on('remove', path, cb)
You can listen for removals and you would listen for changes, except removals cascade down. That is to say, if you remove an object, its children, and their children (etc) will be the subject of remove events.
remove
callbacks take the form:
function (oldvalue, path, rootObject) {
// do things
};
DeepProxy
The list/map api exposes DeepProxy, a submodule which is used internally for creating recursive proxies which execute a provided callback when modified.
For typical usage, users will not need to interact with DeepProxy, however, it is exposed in case you do want access to its features.
If you are particularly interested in DeepProxy, please file an issue and I'll try to address your questions.
Installation
bower install chainpad-listmap
License
This software is and will always be available under the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. If you wish to use this technology in a proprietary product, please contact [email protected]