-
Notifications
You must be signed in to change notification settings - Fork 8
Api v2.0
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.
var mycore = new Cow.Core();
var url = mycore.getServerUrl();
var url = "wss://newServerUrl:443";
mycore.setServerUrl(url);
var projects = mycore.projects();
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);
var groups = project.groups();
var id = 123;
var group = project.groups(id);
var config = {_id:<string>};
var group = project.groups(config);
var data = {name:'group1', members: [2,4,12]};
group.data(data);
var items = project.items();
var id = 123;
var item = project.items(id);
var config = {_id:<string>};
project.items(config);
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);
var users = group.users();
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 = "bla@bla.bla";
user.data('mail',newEmail);
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
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();
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();
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>);
var id = item.getLastUpdatedBy();
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);
var status = item.status();
Set an Item as active
item.status('clean');
Set an Item as inactive
item.status('deleted');