Working with Collaborative Objects

Creating and opening collaborative objects

Collaborative objects are created and opened using the same open() method:

  SwellRT.open(
    {
      // Leave this object empty to create a new object
      id : "local.net/s+cpY3mjyA6BA"
    },

    function(co) {

      // Error
      if (co == null) {
        console.log("Error, object is null");
      } else if (co.error)  {
        console.log("Error, "+co.error);
      }

      // Success
      console.log("Object "+co.id()+" is ready!")
     
     });

If no id parameter is provided in the first argument, a new object will be created with an new auto genarated id. The current id of an object can be retrieved using the method co.id().

Across this documentation we will use the reference co as an instance of a collaborative object

Close the collaborative object using its id. This method is synchronous.

  SwellRT.close(
    {
      id : "local.net/s+cpY3mjyA6BA"
    });

Collaborative objects and users

SwellRT users are identified by an email-like id, for example [email protected]. The domain part is configured in the SwellRT's server installation. In this documentation we will use local.net as domain

Collaborative objects can be shared with users (participants). Of course, after an object is created its first participant is the creator. In general, participants can add or remove others through following methods:

co.addParticipant("[email protected]");
co.removeParticipant("[email protected]");

Ok, got it, this way of sharing and participation model is very simple. We are working to provide a more powerful permissions system in the short-term.

Listeners can be set in the object to be notified when a participant is added or removed.

co.registerEventHandler(SwellRT.events.PARTICIPANT_ADDED, 

    function(userId) { 
            
    });

co.registerEventHandler(SwellRT.events.PARTICIPANT_REMOVED, 

     function(userId) { 
 
    });

Public objects

Public objects can be read and edited by any kind of participant (anonymous or not). In order to turn an object "public" add the wildcard user @<domain> as participant.

co.addParticipant("@local.net");

The root map

Any collaborative object provides a root map where different collaborative fields can be added.

For example, to add a new string field to the root map

var stringField = co.root.put("key1","hello world");

The 'put()' method returns an collaborative field reference of String type. To get the actual string value:

alert(stringField.getValue());

To get the keys on the map as an array:

alert(co.root.keySet());

Collaborative fields

Collaborative fields are created from the collaborative object:

var list = co.createList();
var map = co.createMap();
var str = co.createString("default value");
var txt = co.createText("initial content");

They are not actually usable until they are attached to the object, for example, being added to the root map, or added to an already attached field:

map = co.root.put("keymap", map); // map is attached to the root
list = map.put("keylist",list); // list is attached to the sub map: root->map->list
str = list.add(str); // root->map->list[0]->str

If you try to attach a field to a non already attached field an exception will be thrown.

Collaborative field types

Strings

Strings provide following methods:

str.setValue("string value");
str.getValue();

Maps

Maps provide following methods:

var field = map.put("key",<field>);
var field = map.get("key");
var keys = map.keySet();
map.remove("key");

Lists

Lists provide following methods:

var field = list.add(<field>, <index>);
var field = list.get(<index>);
list.size();
list.remove(<index>);

Files / Attachments

SwellRT supports storage of files (images, documents, etc) in collaborative fields.

Create a new file field to upload the file to the server:

// Get a HTML5 File object from an input element.
var inputFile = document.getElementById("inputFileElementId").files[0];


// Upload the file and get the SwellRT's file field
co.createFile(inputFile, function(response) {

    if (response.error) {
        // The file couldn't be uploaded
    } else {
        // Get the reference to the SwellRT file
        file = response;

        // Now the file can be attached to the object
        co.root.put("key-file", file);

        // Get the URL to download the file
        file.getUrl();
    }

});

To change an existing file already attached in the object is preferable to overwrite that existing value with a new file field:

var file = co.root.get("key-file");

obj.createFile(inputFile, function(response) {

    if (response.error) {
        // The file couldn't be uploaded
    } else {
        // Get the reference to the SwellRT File field
        newFile = response;

        // Overwrite the current value with the new file
        // file is attached
        // newFile is not attached
        file.setValue(newFile);

        // Get the URL to the new file
        file.getUrl();
    }

});

Rich Text Fields

See Collaborative Text Editor

Listening object changes

Fields in the collaborative object are observables. This allows you to register listeners to know when values changes. For example, to handle changes in a string field:

stringField.registerEventHandler(SwellRT.events.ITEM_CHANGED,

                                 function(newStr, oldStr) {

                                    alert("String changed:"+oldStr+"->"+newStr);

                                 });

All object fields (maps, lists and strings) provides these two methods:

<field>.registerEventHandler: function(<event>, <handler>);
<field>.unregisterEventHandler: function(<event>, <handler>);

The 'event' parameter is a value from the SwellRT.events object. '' is a listener function called when the event occurs.

A list of events applying each field type follows:

• String: SwellRT.events.ITEM_CHANGED
• Map: SwellRT.events.ITEM_ADDED SwellRT.events.ITEM_CHANGED SwellRT.events.ITEM_REMOVED
• List: SwellRT.events.ITEM_ADDED SwellRT.events.ITEM_REMOVED

Handler functions receive operation's changes as parameter:

• String: two string parameters: new value, old value
• List: array of objects: index, new value, [old value]
• Map: array of objects: key, new value / removed value, [old value]

Checking object's data type

Use the method type() to check object's type.

co.root.type() == SwellRT.type.MAP;