Api v2.0 - Geodan/cow GitHub Wiki

COW is a communication framework implemented with websocket technology. COW uses websockets to syncronize (geographical) data between the users in the same project so they can work together to edit the map.

Peers represent the people connected to the same websocket using COW clients. Peers share their physical location (if available) and their current view extent of the map.

In COW there are projects. A Project contains groups and items. Any Group or Item belongs to a Project. Items have permissions that allow groups to see, edit and/or share them. Every item also has an owner, which is the creator of the item.

1. Core 

function Cow.Core() {
    this._wsUrl = 'wss://localhost:443'; //default server URL

}

//SERVER URL
//getServerUrl() -> returns the server URL
Cow.Core.prototype.getServerUrl = function() {}
//setServerUrl(url) -> defines a server URL other than the default URL
Cow.Core.prototype.setServerUrl = function(url) {}

//PROJECTS
//projects() -> returns an array with all Project objects
//projects(ID) -> returns the Project object whose identifier is PID
//projects({config}) -> adds a new project with config and returns it
config = {_id: <string>,data:{<params>};
//getCurrentProject() -> returns your current Project object

Description The core of cow is where the server URL is established. Also, it contains the Project objects.

Start COW Core

        var mycore = new Cow.Core();

Get the URL of the server

    var url = mycore.getServerUrl();

Set the URL of the server

    var url = "wss://newServerUrl:443";
    mycore.setServerUrl(url);

Get all projects

    var projects = mycore.projects();

Get a project from its identifier (PID)

    var pid = 123;
    var project = mycore.projects(pid);

2. Project 

//PROJECT NAME
//getName() -> returns a string with the name of a project
Cow.Project.prototype.getName =  function() {}
//setName(name) -> assigns a new name to a project
Cow.Project.prototype.setName =  function(name) {}

//GROUPS
//groups() -> returns an array with all the Group objects belonging to a project
//groups(id) -> returns the Group object with the specified ID
//groups(config) -> adds a new Group object to a project
config = { _id:<string>, data:{params} };

//ITEMS
//items() -> returns an array with all the Item objects belonging to a project
//items(id) -> returns the Item object with the specified ID
//items(config) ->  adds a new Item object to a project
config = { _id:<string>, data:{params} };

Description The Project object has a name, an array of Group objects and an array of Item objects. Groups and items belong to only one project, which is the reason why they are stored inside the Project object. The contents of projects are synchronized only between its members. The default client assumes that a COW instance can be working on only one project at the same time, meaning that only the data contained on the current working project is synced.

Get the name of a Project 

    var name = project.data('name');

Set a new name for a Project 

    var newName = "bla bla bla";
    project.data('name',newName);

Get all the Group objects of a Project 

    var groups = project.groups();

Get a Group from a Project by its ID

    var id = 123;
    var group = project.groups(id);

Add a new Groupto a Project 

    var config = {_id:<string>};
    var group = project.groups(config);

Update an existing Group in a Project 

    var data = {name:'group1', members: [2,4,12]};
    group.data(data);

Get all the Item objects of a Project 

    var items = project.items();

Get an Item from a Project by its ID

    var id = 123;
    var item = project.items(id);

Add a new Itemto a Project 

    var config = {_id:<string>};
    project.items(config);

Update an existing Item in a Project 

    var config = {key:value};
    item.data(config);

3. Group 

//GROUP NAME
//group.data('name') ->  returns the name of the group
//group.data('name', <string>) ->  sets a new name for the group

//GROUP MEMBERS Tom: not sure wether well implement this
//getUsers() ->  returns an array of User IDs
Cow.Group.prototype.getUsers =  function() {}
//getUser(id) ->  returns a User object from its ID if it exists in the group
Cow.Group.prototype.getUser =  function(id) {}
//addUser(id) ->  adds a new User ID to the group
Cow.Group.prototype.addUser =  function(id) {}
//removeUser(id) ->  removes the user with the specified ID from the group
Cow.Group.prototype.removeUser =  function(id) {}

Description The Group object has a name, an array of Group IDs and an array of User IDs.

Get the name of a Group 

    var name = group.data('name');

Set a new name for a Group 

    var newName = "bla bla bla";
    group.data('name', newName);

Get all the User IDs from a Group 

    var users = group.users();

Add a UserID to a Group 

    var id = newUser.getId();
    group.addUser(id);

Remove a User[[ from a [[Group 

    var id = 123;
    group.removeUser(id);

4. User 

//USER NAME
//user.data('name') ->  returns a string with the User name
//user.data('name',<string>) ->  sets a new name for the user

//USER EMAIL
//user.data('mail') ->  returns a string with the User email
//user.data('mail',<sting>) ->  sets a new email for the user

//USER GROUPS
Tom: Is this function needed?

//USER PEERS
TODO: this is a convenience function, getting peers with the same user

Description The User object has a name, an email address. The User object is referred to as user in the documentation. A User is NOT another cow connected to the same websocket server (this can be someone else or the same user, using a different browser)

Get the name of a User 

    var name = user.data('name');

Set a new name for a User 

    var newName = "bla bla bla";
    user.data('name',newName);

Get the email of a User 

    var email = user.data('mail');

Set a new email for a User 

    var newEmail = "[email protected]";
    user.data('mail',newEmail);

Get the IDs of all the Group objects the User belongs to

Tom: this is not needed because it depends per project

Get a Group object by its ID if the user belongs to it

Tom: this is not needed because it depends per project

Add a Group ID to the list of groups if the user doesn't belong to it

Tom: this is not needed because it depends per project

Remove a Group ID from the list of groups if the group exists and the user belongs to it

Tom: this is not needed because it depends per project

Get the IDs of all the Peer objects that belong to the User 

    var peerIds = user.getPeers();

Get a Peer object by its ID if it belongs to the user.

Tom: Appears unneeded, if you known the peerid you can get it directly from the core

    var id = 123;
    var peer = user.getPeer(id);

5. Item 

//ITEM PROPERTIES
//getId() ->  returns the item ID
//getProject() ->  returns the project object the item belongs to
//data('type') ->  returns a string with the type of item. Currently items can be features
//getCreateDate() ->  returns the creation date of the item
//getCreatedBy() ->  returns the ID of the user that created the item
//timestamp() ->  returns the date the item was last updated
//timestamp(<timestamp>) ->  sets the current timestamp as the last update date
//getLastUpdatedBy() ->  returns the ID of the last user that updated the item
//setLastUpdatedBy(<string>) ->  sets the ID of the last user that updated the item

//ITEM PERMISSIONS
//getPermissions() ->  returns the permissions of the item
//setPermissions(config) ->  sets the permissions of the item
config = { xxx:"...", xxx:"..." };

//ITEM STATUS
//status() ->  returns a string with the status of the object (clean, dirty, deleted)
//status(<string>) ->  sets the status of the object (clean, dirty, deleted)

//ITEM DATA
//data() ->  returns the data of the item
//data(config) ->  updates the data of the item
config = { xxx:"...", xxx:"..." };

Description The Item object has a series of attributes that cannot be modified. An Item is created by a user, its owner, inside a project. When an item is created, the owner, the creation date and the project it belongs to are automatically set by the system using the user id of the owner, the current timestamp and the current project of the owner respectively. It also has a type attribute that is set when the item is initially created and cannot be changed. Whenever an Item is updated/edited, the last user id and timestamp are stored too. An Item is updated when the data, the status and/or the permissions are changed. The status of an Item indicates if it is active or not. Setting an Item as 'deleted' is equivalent to removing it. The permission types of an item are a free field. The permissions object are three lists of Group IDs that are allowed to perform each of the operations defined by the permission type. The data of an Item is inherent to the type of Item, so its structure will not be explained here.

Get the ID of an Item 

    var id = item.getId();

Get the ID of the Project the Item belongs to

    var id = item.getProject();

Get the type of the Item 

    var type = item.data('type');

Get the creation date of the Item 

    var date = item.getCreateDate();

Get the ID of the User that created the Item 

    var id = item.getCreatedBy();

Get the date when the Item was last updated

    var lastDate = user.getLastUpdateDate();

Set the current timestamp as the date when the Item was last updated

    item.timestamp(<CURRENT_TIMESTAMP>);

Get the ID of the User that last updated the Item 

    var id = item.getLastUpdatedBy();

Set the ID of the User that last updated the Item 

    var myid = 123;
    item.setLastUpdatedBy(myid);

Get the permissions of the Item 

    var perm = item.data('permissions');

Set new permissions for the Item

//TODO: needs some attention

    var permissions = {'permissions:{}};
    item.data('permissions',permissions);

Check if an item is active

    var status = item.status();

Set an Item as active

    item.status('clean');

Set an Item as inactive

    item.status('deleted');
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️