Permissions

Roles (or “profiles”)

Permissions are always applied to a role. Then, each user is given one or many roles, from which the permissions are determined.

One role by user

For the sake of simplicity and understanding, on a default installation:

  • these roles are hidden ;
  • each user gets one unique role attributed ;
  • it’s not possible to share a role among several users.

Hence the role notion is completely hidden and the permissions are configured on a dedicated tab of the user form :

../_images/user_standalone.png

Several roles by user

Meanwhile it’s possible to enable multiple roles in the main configuration file : novius-os.users.enable_roles = true.

Once enable, it becomes possible to share a role among several users. Permissions can then be configured more precisely:

  • on the user form, the “Permissions” tab disappear in favor of a “Roles” block ;
  • the AppDesk of the Users application gains:
    • a new “Roles” inspector ;
    • a new “Add a role” action.
  • permissions should now be configured on the role form.
../_images/user_roles.png

Permission structure

They are two types of permission:

  • simple: yes or no ;
  • multiples : applied on a list of categories (values);

A simple permission has a meaning just by itself. For instance “Can I add a page?” or “Can I delete a locked page?”.

A multiple permissions don’t have a meaning just by themselves, and can only be be expressed depending on a category (value). For instance with “Can I write in this folder?” we need a list of folders for the permission to have a meaning. With “Can I access this application?” we need a list of applications.

A simple permission is composed of a unique perm_name column, whereas a multiple role (using categories) is composed of two columns: perm_name (the same on as a simple permission) and perm_category_key (the value).

How-to use permissions in the applications

permissions.config.php file

By creating this file, each application can define its own list of permissions it needs.

They can be configured in the dedicated column when editing the permissions :

../_images/permissions.png

API to check a permission

<?php
// Simple: only 1 argument, the permission name
\Nos\User\Permission::check('noviusos_app::delete_locked');

// Multiple (uses categories) : 2 arguments, the permission name + the category key
\Nos\User\Permission::check('noviusos_app::create_in_folder', $folder_id);

// Handling acces level (advanced, useful when combined with multiple roles) : 2 arguments, the permission name + the level (numeric)
\Nos\User\Permission::atLeast('noviusos_app::level', '2_moderator');

See also

API documentation of the Permission class.

Warning

The permission name is an important thing. The part preceding :: must refer to an valid application. For the permission to be granted, the user also needs to have access to this application.

CRUD

It’s possible to hide some fields based on the permissions. To do so, the show_when key defines a callback function returning whether the field should be visible or not.

 <?php
 return array(
     'fields' => array(
         'my_field' => array(
             'label' => 'My field',
             'form' => array(
                 'type' => 'text',
             ),
             'show_when' => function() {
                 // The field will only be visible when the user has the requested permission
                 return Permission::check('my_app::my_permission');
             },
         ),
     ),
 );

Actions

It’s possible to disabled actions based on the permissions using the disabled key.

 <?php
 return array(
     'data_mapping' => array(/*...*/),
     'actions' => array(
         'delete' => array(
             'label' => __('Delete'),
             'primary' => false,
             'icon' => 'home',
             'action' => array(/*...*/),
             'targets' => array(
                 'grid' => true,
             ),
             'disabled' => array(
                 function($item) {
                     return !Permission::check('my_app::can_delete_item') ? __('You don\'t have the permission to delete items.') : false;
                 }
             ),
         ),
     ),
 );
Read the Docs v: dubrovka
Versions
latest
elche
dubrovka
chiba.2
chiba.1
Downloads
PDF
HTML
Epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.