Class: Role

Role

A role is logical grouping of a set of users. Role inherits from Object.

new Role(uid){Role}

role.js, line 8
Constructs a role
Name Type Description
uid Uid of a role on Built.io Backend
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
// 'blt111sample24a6b' is uid of a role object on Built.io Backend
var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');

Methods

staticRole.getRoleQuery(){Query}

role.js, line 28
Returns a query instance for Role Class
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
var Role = Built.App('blt5d4sample2633b').Role;
var query = Role.getRoleQuery();
query
.where('name','admin')
.exec()
.then(function(roles){
.deltaDeletedFrom('2014-09-02')// roles is an array of SDK objects
});

staticRole.off(event, callback){Role}

realtime.js, line 1921

[Only avaliable with realtime plugin]

This function unregisters a single or all event listener(s) from Role constructor.

Name Type Description
event String The event whose listener needs to be unregistered [Optional]
callback function The callback function used while registering [Optional]
Throws:
  • new Error('Callback function to be removed is missing')
  • new Error('Event name is missing');
Example
// 'blt5d4sample2633b' is a dummy Application API key
// app.Role returns a 'Role' constructor
var app = Built.App('blt5d4sample2633b').enableRealtime();
var Role = app.Role;

function cb(data){
   console.log(data);
}

// Sets up a listener for delete event
Role.on('delete',cb);   

// Sets up a listener for broadcast event
Role.on('broadcast',cb);  

// Specifically removes the delete listener
Role.off('delete',cb); 

// Removes all listeners on Person
Role.off();           

// Removes all callbacks attached for delete event on this resource
Role.off('delete');  

// Throws "Event name is missing"
Role.off(cb)            
	

addRole(role){Role}

role.js, line 65
Adds a new role
Name Type Description
role String | Object Accepts SDK's role object or its uid
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
// 'blt111sample24a6b' is uid of a role object on Built.io Backend

// Example using role's uid
var role  = Built.App('blt5d4sample2633b').Role();
role = role
       .setName('developers')
       .addRole('blt111sample24a6b');
//Example using SDK object
var role1 = Built.App('blt5d4sample2633b').Role('bltcd6168a6b9ad2add');

var role  = Built.App('blt5d4sample2633b').Role();
role = role
       .setName('developers')
       .addRole(role1)

addRoles(roles){Role}

role.js, line 121
Adds new sub roles within this role
Name Type Description
roles Array This can be an array of role uids or an array SDK objects
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
// 'blt111sample24a6b' and 'blt222sample24a6b' is uid of a role object on Built.io Backend

//Example using role's uid
var role = Built.App('blt5d4sample2633b').Role();
role = role
       .setName('developers')
       .addRoles(['blt111sample24a6b','blt222sample24a6b']);
//Example using SDK object
var role1 = Built.App('blt5d4sample2633b').Role('bltcd6168a6b9ad2add');
var role2 = Built.App('blt5d4sample2633b').Role('bltcd6168a6b9ad2acc');

var role = Built.App('blt5d4sample2633b').Role();
role = role
       .setName('developers')
       .addRoles([role1,role2])

addUser(user){Role}

role.js, line 93
Adds a new user to this role
Name Type Description
user String | Object Accepts SDK's user object or its uid
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
// 'blt111sample24a6b' is uid of a role object on Built.io Backend

//Example using role's uid
var role = Built.App('blt5d4sample2633b').Role();
role = role
       .setName('developers')
       .addUser('blt111sample24a6b');
//Example using SDK object
var user = Built.App('blt5d4sample2633b').User('blt111sample24a6b');

var role = Built.App('blt5d4sample2633b').Role();
role = role
       .setName('developers')
       .addUser(user)

addUsers(users){Role}

role.js, line 157
Adds a new users to this role
Name Type Description
users Array This can be an array of user uids or an array SDK objects
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
// 'blt111sample24a6b' and 'bll222sample24a6b' is uid of a user object on Built.io Backend

//Example using role's uid
var role = Built.App('blt5d4sample2633b').Role();
role = role
       .setName('developers')
       .addUsers(['blt111sample24a6b', 'bll222sample24a6b']);
//Example using SDK object
var user1 = Built.App('blt5d4sample2633b').User('bltcd6168a6b9ad2add');
var user2 = Built.App('blt5d4sample2633b').User('bltcd6168a6b9ad2acc');

var role = Built.App('blt5d4sample2633b').Role();
role = role
       .setName('developers')
       .addUsers([user1, user2])

getName(){String}

role.js, line 238
Gets the name of the role
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
var role  = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
role.fetch()
.then(function(role){
   role.getName();
})

getRoles(){Array}

role.js, line 256
Gets the sub-roles contained in this role. A sub-role is a subset of a role.
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
var role  = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
role.fetch()
.then(function(role){
   role.getRoles();
});

getRoleUid(){String}

role.js, line 274
Gets the uid of the role
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
// 'blt111sample24a6b' is uid of a role object on Built.io Backend
var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
var uid = role.getRoleUid(); 

getUsers(){Array}

role.js, line 290
Gets the users belonging to this role
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
// 'blt111sample24a6b' is uid of a role object on Built.io Backend
var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
role.fetch()
.then(function(role){
   role.getUsers();
})

hasRole(role_uid){Boolean}

role.js, line 345
Checks whether a sub-role exists in this role
Name Type Description
role_uid String Uid of the sub-role whose existence needs to be checked
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
// 'blt111sample24a6b' is uid of a role object on Built.io Backend

var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
role.fetch()
.then(fuction(role){
   role.hasRole('blt444sample24a6b'); // pass sub role uid
});

hasUser(user_uid){Boolean}

role.js, line 365
Checks whether a user belongs to this role
Name Type Description
user_uid String Uid of the user whose existence needs to be checked
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
// 'blt111sample24a6b' is uid of a role object on Built.io Backend

var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
role.fetch()
.then(fuction(role){
   role.hasUser('blt444sample24a6b'); // pass user uid
});

off(event, callback){Role}

realtime.js, line 1965

[Only avaliable with realtime plugin]

This function unregisters a single or all event listener(s) from Role instance.

Name Type Description
event String The event whose listener needs to be unregistered [Optional]
callback function The callback function used while registering [Optional]
Throws:
  • new Error('Callback function to be removed is missing')
  • new Error('Event name is missing');
Example
// 'blt5d4sample2633b' is a dummy Application API key
// app.Role() returns an instance of application role class
// 'blt111sample2211r' is uid of an object on Built.io Backend
var app = Built.App('blt5d4sample2633b').enableRealtime();
var role = app.Role('blt111sample2211r');

function cb(data){
   console.log(data);
}

// Sets up a listener for create event
role.on('delete',cb);   

// Sets up a listener for broadcast event
role.on('broadcast',cb);  

// Specifically removes the delete listener
role.off('delete',cb); 

// Removes all listeners on Person
role.off();           

// Removes all callbacks attached for delete event on this resource
role.off('delete');  

// Throws "Event name is missing"
role.off(cb)            
	

removeRole(role_uid){Role}

role.js, line 398
Removes a sub-role from the given role
Name Type Description
role_uid String Uid of the sub-role that needs to be removed from the role
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
// 'blt111sample24a6b' is uid of a role object on Built.io Backend
var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
role.fetch()
.then(function(role){
   if(role.hasRole('blt444sample24a6b'));
      return role.removeRole('blt444sample24a6b'); //pass role uid
   else
      return role;
});

removeUser(user_uid){Role}

role.js, line 421
Removes a user from a role
Name Type Description
user_uid String Uid of the user that needs to be removed from the role
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
// 'blt111sample24a6b' is uid of a role object on Built.io Backend
 
var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
role.fetch()
.then(function(role){
   if(role.hasUser('blt444sample24a6b'));
      return role.removeUser('blt444sample24a6b'); //pass user uid
   else
      return role;
});

setName(name){Role}

role.js, line 309
Assigns a name to this role
Name Type Description
name String Name to be assigned to this role
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
var role = Built.App('blt5d4sample2633b').Role();
role = role.setName('developers');

setRoleUid(uid){Role}

role.js, line 324
Assigns a uid to this role
Name Type Description
uid String Uid to be assigned to this role
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance
// 'blt111sample24a6b' is uid of a role object on Built.io Backend
var role = Built.App('blt5d4sample2633b').Role();
role = role.setRoleUid('blt111sample24a6b');

setUsersWithQuery(query){Role}

role.js, line 193
Fires a query on in-built ApplicationUser objects and the ones which fulfills the query condition are assigned againts the 'users' field.
Name Type Description
query Object The query to be executed on ApplicationUser objects. It can be a in json format or app.Class('class_uid').Query object.
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Role() returns a 'Role' instance

//Example using plain json object. Sets all the users who's username starts with pat
var role = Built.App('blt5d4sample2633b').Role();
role = role
       .setName('developers')
       .setUsersWithQuery({
       		query:{
       			"username": {
						    "$regex": "^pat",
						    "$options": "i"
						  }
       		}
       });
       
//Example using app.Class('class_uid').Query
var app       = Built.App('blt5d4sample2633b')
var role      = app.Role();
var userQuery = app.Class('built_io_application_user').Query()
userQuery     = queryQuery.matches("username", "^path")
role = role
       .setName('developers')
       .setUsersWithQuery(userQuery)