Tutorial

Managing permissions

Table of contents
  1. Basic permission settings
  2. Seamlessly handling permissions
  3. Additive role inheritance

Basic permission settings

As explained in the Creating pages tutorial it is possible to either set a page's permissions to a specific value or edit them seamlessly by adding and removing persons and groups.

To set the read/write permissions of a page you simply have to provide an array of accepted values to a page's reader/writers fields. Accepted values are either Uid strings or objects of principal entities. You can mix different kinds of principals, i.e. use persons and groups cuncurrently.

// assigning variables so we can give them names
var personA_uid = 'person/kpf1s9cjf8s2kaerf7g0pdrvk';
var groupB_uid = 'group/bhhss96cpvvu9li110zb4zta9';

var currentUser = cplace.utils().getCurrentUser();
var groupC = cplace.utils().findGroupByName('senior_editors');

cplace.actions().updatePage(page, {
    // this will give read access to personA and groupB by assigning their uids
    readers: [personA_uid, groupB_uid],
    // this will give write access to the current user and groupC
    writerts: [currentUser, groupC]
});

However you can restore the system defaults at any time by setting either of the properties to 'inherited'. This will make the page to automatically inherit its read and write permissions from its parent:

{
    ...
    readers: 'inherited'
    ...
}

Seamlessly handling permissions

Seamless permission management means that you may provide only positive or negative changes to the permissions of a page to control access to it in cplace. To use this feature you have to provide a permissions object (no array) which defines the users or groups to be added or removed by '+' and '-' properties:

cplace.actions().updatePage(page, {
    readers: {
        '+': [userA, userB] // add these users to the readers
    },
    writers: {
        '+': [userA],
        '-': [userC, groupE] // remove these editors
    }
});

This only works with explicitly present values. If for example user1 belongs to groupA which has write access on a page but is not explicitly mentioned in the permissions is removed by '-': user1 this will have no effect:

Assume the page setup looks like this

page: {
    readers: ...,
    writers: user2, groupA
}

Than this will have no effect, because user1 is not explicitly set as a writer

cplace.actions().updatePage(page, {
    writers: {
        '-': user1
    }
});

Whereas this will successfully remove user2 from the writers

cplace.actions().updatePage(page, {
    writers: {
        '-': user2
    }
});

Also be sure to provide the + and - keys as strings ('') as javascript otherwise will interpret them as operators, which are not allowed in that context and will result in an error.

Additive role inheritance

Since cplace version 5.0 you can combine explicitly set and inherited permissions. To read about additive role inheritance you can read the API change article for 5.0 here.

TL;DR
With additive role inheritance turned on inherited permissions of pages can be extended manually. E.g. page1 inherits write permissions with userA from its parent page and declares permission for userB as well. Then A child page page2 inherits permissions for userA and userB and may define further permissions with that setting.

To explicitly enable or disable additive role inheritance, provide a boolean additiveInheritance property like

{
  ...
  writers: {
     'additiveInheritance': true,
     '+': [...],
     '-': [...]
  }
  ...
}

Note that this feature is only available when using permission objects to set permissions.