First you'll need to load the Simperium Javascript library by including this in your html:
<script type="text/javascript" src="https://js.simperium.com/v0.1/"></script>Simperium.js includes the following libraries:
Note— If you're testing a page locally, be sure to use a local web server. Browsers typically prevent cross-domain access when loading pages from a local file. If you have python, you can start a local web server in any directory by using this command:
>>> python -m SimpleHTTPServer 8080
var simperium = new Simperium(app_id, {options});app_id — Your application id
options — Options object, you should pass in your access token here
var simperium = new Simperium('your-application-id', { token: 'access_token' });A Simperium instance that you can use to create/retrieve buckets of synced objects. The token you use will dictate what kind of access you get to objects. Many users may create objects in a bucket, but each user's token will only allow access to their own objects.
Gets a bucket object to sync objects with
var bucket = simperium.bucket(bucket_name);bucket_name — Case insensitive name for your bucket, may or may not exist already
A Simperium bucket instance that you can use to sync objects with. A bucket is a namespace for you to create objects within.
Register a callback for a simperium event
bucket.on('eventname', event handler function);event_name — ready, notify, get
event handler function — Your function handler, parameters and expected return value varies depending on the event.
bucket.on('notify', function(id, object) {
console.log("received new data for object id: "+id);
console.log(object);
});Start syncing a bucket
bucket.start();Once you call the start() method, all data for the bucket (if any exists) will start to be retrieved. If you've registered for the notify event, you will start getting data. This is typically how you initialize a bucket that already has data in it.
bucket.update(id, data);id — The string identifier for the object.
data — a JSON object (optional)
returns — a string identifier if null was sent for id
bucket.update("myobject", {"content": "any json object is valid", "alist" : [1, 2, 3]});Use this function to update an object whenever it changes locally. If you don't pass in the object as the second parameter, you'll need to assign the local callback so the current state of the object can be retrieved and synced.
bucket.on('ready', function() {
console.log("Finished sending notifications for existing objects!");
});This event will be sent once all notifications for data already in a bucket have been sent. Prior to this event, notify_init will be triggered if it was set, otherwise, notify is triggered. After the bucket is ready, all remote changes will trigger notify only.
bucket.on('notify', function(id, data) {
console.log("got data for id: "+id);
console.log("data =");
console.log(data);
});id — The string identifier for the object.
data — a JSON object or null if object has been deleted.
This event is sent when there is an update for an object in the bucket. Your callback function should accept the id and data parameters. data will be the updated version of the object including any local changes you may have not sent yet. If the object is deleted elsewhere, data will be null.
bucket.on('notify_init', function(id, data) {
console.log("got existing data for id: "+id);
console.log("data =");
console.log(data);
});id — The string identifier for the object.
data — a JSON object or null if object has been deleted.
notify_init is the same as notify except it is sent only during bucket initialization (before ready is sent.) This callback is sent for objects that are already in the bucket when you initialize it. When a bucket is first start()'ed, any objects that have already been persisted/synced to the bucket will trigger callbacks so you can initialize your UI. A ready event will then be triggered when those callbacks have been issued. From then on, anytime an object is modified, you'll get a notify event. If you don't set a notify_init callback, you'll get notify instead during bucket initialization.
bucket.on('local', function(id) {
console.log("got request for current data for id: "+id);
if (id == "myobject") {
return { "content" : $("#mytextfield").val() };
}
});id — The string identifier for the object.
returns — a JSON object with the current local state of the object.
This callback is triggered whenever the library needs to check what the current local state of an object is before it sends you a notify event. This is so any local changes can be incorporated into the updated object. In the example above, you may be syncing text input from a HTML element named "mytextfield". If there is an update available (this object was changed elsewhere), the library will expect to get the current state of the object so it can incorporate the local changes with the remote changes. When you get the notify event, then you can update "mytextfield" directly.
If you don't intend to make any changes to the data locally, you don't need to register this callback.
bucket.on('error', function(errortype) {
console.log("got error for bucket: "+errortype);
if (id == "auth") {
console.log("auth error, need to reauthenticate and get new access token")
}
});errortype — A string for the type of error that occured.
This callback is used to commmunicate errors. Currently the valid values for errortype are auth. If this callback gets triggered and the value is auth, you should re-authenticate and get a new access token.
bucket.on('local', function(id) {
console.log("got request for current data for id: "+id);
if (id == "myobject") {
var data = {
"content" : $("mytextfield").val()
};
return [data, "content", $("#mytextfield")[0]];
}
});
id — The string identifier for the object.
returns — an array with 3 elements, the JSON data for the object, a field name, and an HTML DOM Element.
When working with text input elements like textareas, it can be disconcerting to update a textarea for a user because the cursor will typically jump back to the beginning. A special form of the local callback allows you to return an array with the object, a field name in the object, and an HTML Element for which the data of the field corresponds. In the above example, you may wish to check if the object "myobject" currently has focus, and if so, return an array instead of the plain object. When doing this, Simperium will update the element with any new content and keep the cursor where the user expects so you should not update the element yourself.