Export (0) Print
Expand All

How to: Work with Roles Using JavaScript

SharePoint 2010

Last modified: June 20, 2011

Applies to: SharePoint Foundation 2010

In this article
Creating a Role Definition Using JavaScript
Assigning a User to a Role on a Website Using JavaScript
Creating a SharePoint Group and Adding the Group to a Role Using JavaScript

Through the client object model, you can create custom role definitions within site collections, and you can assign new or existing users and groups to specific roles for websites, lists, and list items. Similar to the way you use the SPRoleDefinitionBindingCollection class in the server object model, you add a user or group, together with a RoleDefinitionBindingCollection object, to the collection of role assignments for a specific object.

To create a role definition in the collection of role definitions for a site collection using ECMAScript (JavaScript, JScript), use the BasePermissions object to define a permission set, use the RoleDefinitionCreationInformation object to define a role that includes the permission set, and then add the new role to the collection of role definitions. The following example shows how to create a role for creating and managing alerts. The order property specifies that the new role be displayed fourth in order among custom role definitions listed on the Permissions Levels page of the site collection.

siteUrl = '/sites/MySiteCollection';

function createRoleDefinition() {

    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();

    var permissions = new SP.BasePermissions();
    permissions.set(SP.PermissionKind.createAlerts);
    permissions.set(SP.PermissionKind.manageAlerts);

    var roleCreationInfo = new SP.RoleDefinitionCreationInformation();
    roleCreationInfo.set_basePermissions(permissions);
    roleCreationInfo.set_description('A new role with create and manage alerts permission');
    roleCreationInfo.set_name('Create and Manage AlertsT');
    roleCreationInfo.set_order(4);

    this.oRoleDefinition = oWebsite.get_roleDefinitions().add(roleCreationInfo);

    clientContext.load(oRoleDefinition);

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded() {

    var roleInfo = oRoleDefinition.get_name() + ' role created.';
    alert(roleInfo);
}

function onQueryFailed(sender, args) {

    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

To assign a user to a particular role on a website, you create a RoleDefinitionBindingCollection object for the website context, add a role definition to the binding collection object, and then use the add(principal, roleBindings) function to add the user together with the binding collection to the role assignments for the website. The following example assigns an existing site collection user to the role that was defined in the previous example.

siteUrl = '/sites/MySiteCollection/MyWebSite';

function addUserToRole() {

    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();

    this.oUser = oWebsite.get_siteUsers().getByLoginName('DOMAIN\\alias');
    this.oRoleDefinition = oWebsite.get_roleDefinitions().getByName('Create and Manage Alerts');

    var collRoleDefinitionBinding = SP.RoleDefinitionBindingCollection.newObject(clientContext);        

    collRoleDefinitionBinding.add(oRoleDefinition);

    var oRoleAssignment = oWebsite.get_roleAssignments().add(oUser, collRoleDefinitionBinding);

    clientContext.load(oUser, 'Title');
    clientContext.load(oRoleDefinition, 'Name');

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded() {

    var roleInfo = oUser.get_title() + ' assigned to ' + oRoleDefinition.get_name();
    alert(roleInfo);
}

function onQueryFailed(sender, args) {

    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

In the same way that you create most other objects through the client object model, use the GroupCreationInformation object to define a new group, and then use the add(parameters) function to add the group to the collection of site groups in a site collection. And just as you assign users to a role, you assign a group to a particular role on a website by creating a RoleDefinitionBindingCollection object for the website context, adding a role definition to the binding collection object, and then using the add(principal, roleBindings) function to add the group together with the binding collection to the role assignments for the website. The following example creates a group and assigns it the Contribute role on the website.

var siteUrl = '/sites/MySiteCollection/MyWebSite';

function createGroupAddToRole() {

    var clientContext = new SP.ClientContext(siteUrl);
    this.oWebsite = clientContext.get_web();

    var groupCreationInfo = new SP.GroupCreationInformation();
    groupCreationInfo.set_title('My New GroupT');
    groupCreationInfo.set_description('Description of new group.');
    this.oGroup = oWebsite.get_siteGroups().add(groupCreationInfo);

    var collRoleDefinitionBinding = SP.RoleDefinitionBindingCollection.newObject(clientContext);

    this.oRoleDefinition = oWebsite.get_roleDefinitions().getByType(SP.RoleType.contributor);
    collRoleDefinitionBinding.add(oRoleDefinition);

    var collRollAssignment = oWebsite.get_roleAssignments();
    collRollAssignment.add(oGroup, collRoleDefinitionBinding);

    clientContext.load(oGroup, 'Title');
    clientContext.load(oRoleDefinition, 'Name');

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded() {

    var roleInfo = oGroup.get_title() + ' created and assigned to ' + oRoleDefinition.get_name();
    alert(roleInfo);
}

function onQueryFailed(sender, args) {

    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}
Show:
© 2014 Microsoft