Access API: Difference between revisions
No edit summary |
No edit summary |
||
Line 1: | Line 1: | ||
The Access API gives you functions so you can determine what the current user is allow to do, and it allows modules to extend Moodle with new capabilities. | {{Moodle_2.2}}The Access API gives you functions so you can determine what the current user is allow to do, and it allows modules to extend Moodle with new capabilities. | ||
==Overview== | ==Overview== | ||
==Determining that a user has a given capability== | Moodle is using a role based access control model. Most entities in Moodle (system, users, course categories, courses, modules and blocks) are represented by contexts that are arranged in a tree like hierarchy called context tree. Role is a set of capability definitions, each capability usually represents an ability of user to do something. Roles are defined at the top most system context level. Roles definitions can be overridden at lower context levels. User access control is calculated from the definitions of roles assigned to users. | ||
All users that did not log-in yet automatically get the default role defined in $CFG->notloggedinroleid, it is not possible to assign any other role to this non-existent user id. There is one special guest user account that is user when user logs in using the guest login button or when guest autologin is enabled. Again you can not assign any roles to the guest account directly, this account gets the $CFG->guestroleid automatically. All other authenticated users get the default user role specified in $CFG->defaultuserroleid and in the frontpage context the role specified in $CFG->defaultfrontpageroleid. | |||
==How to define new capabilities in plugins== | |||
Capabilities are defined by $capabilities array defined in db/access.php files. The name of the capability consists of "plugintype/pluginname:capabilityname". | |||
For example: | |||
<code> | |||
$capabilities = array( | |||
'enrol/manual:manage' => array( | |||
'captype' => 'write', | |||
'contextlevel' => CONTEXT_COURSE, | |||
'archetypes' => array( | |||
'manager' => CAP_ALLOW, | |||
'editingteacher' => CAP_ALLOW, | |||
) | |||
), | |||
); | |||
</code> | |||
Where the meaning of array keys is: | |||
* captype - ''read'' or ''write'' capability type, for security reasons system prevents all write capabilities for guest account and not-logged-in users | |||
* contextlevel - specified as context level constant, the lowest level where is this capability usable, plugins may hardcode exceptions if they use capability in more contexts | |||
* archetypes - specifies defaults for roles with standard archetypes, this is used in installs, upgrades and when resetting roles (it is recommended to use only CAP_ALLOW here) | |||
It is necessary to bump up plugin version number after any change in db/access.php. | |||
The capability names are defined in plugin language files, the name of the string consists of "pluginname:capabilityname", in the example above it would be: | |||
<code> | |||
$string['manual:manage'] = 'Manage user enrolments'; | |||
</code> | |||
==Useful functions and classes== | |||
===Context fetching=== | |||
describe context classes here | |||
===Determining that a user has a given capability=== | |||
has_capability() and friends | has_capability() and friends | ||
<code> | |||
</code> | |||
== | ===Enrolment related functions=== | ||
Since Moodle 2.2 there is a new concept of user enrolments, they are fully independent from the roles and capabilities, see [[Enrol API]] for more information. | |||
The capabilities are often used in combination with enrolment status - for example only enrolled students with a submit capability are allowed to submit assignments. | |||
is_enrolled() | |||
get_enrolled_sql() | get_enrolled_sql() | ||
get_enrolled_users() | |||
===Course login and access restrictions=== | |||
.... | .... |
Revision as of 14:30, 14 January 2012
Moodle 2.2 The Access API gives you functions so you can determine what the current user is allow to do, and it allows modules to extend Moodle with new capabilities.
Overview
Moodle is using a role based access control model. Most entities in Moodle (system, users, course categories, courses, modules and blocks) are represented by contexts that are arranged in a tree like hierarchy called context tree. Role is a set of capability definitions, each capability usually represents an ability of user to do something. Roles are defined at the top most system context level. Roles definitions can be overridden at lower context levels. User access control is calculated from the definitions of roles assigned to users.
All users that did not log-in yet automatically get the default role defined in $CFG->notloggedinroleid, it is not possible to assign any other role to this non-existent user id. There is one special guest user account that is user when user logs in using the guest login button or when guest autologin is enabled. Again you can not assign any roles to the guest account directly, this account gets the $CFG->guestroleid automatically. All other authenticated users get the default user role specified in $CFG->defaultuserroleid and in the frontpage context the role specified in $CFG->defaultfrontpageroleid.
How to define new capabilities in plugins
Capabilities are defined by $capabilities array defined in db/access.php files. The name of the capability consists of "plugintype/pluginname:capabilityname".
For example:
$capabilities = array(
'enrol/manual:manage' => array(
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'manager' => CAP_ALLOW,
'editingteacher' => CAP_ALLOW,
)
),
);
Where the meaning of array keys is:
- captype - read or write capability type, for security reasons system prevents all write capabilities for guest account and not-logged-in users
- contextlevel - specified as context level constant, the lowest level where is this capability usable, plugins may hardcode exceptions if they use capability in more contexts
- archetypes - specifies defaults for roles with standard archetypes, this is used in installs, upgrades and when resetting roles (it is recommended to use only CAP_ALLOW here)
It is necessary to bump up plugin version number after any change in db/access.php.
The capability names are defined in plugin language files, the name of the string consists of "pluginname:capabilityname", in the example above it would be:
$string['manual:manage'] = 'Manage user enrolments';
Useful functions and classes
Context fetching
describe context classes here
Determining that a user has a given capability
has_capability() and friends
Since Moodle 2.2 there is a new concept of user enrolments, they are fully independent from the roles and capabilities, see Enrol API for more information.
The capabilities are often used in combination with enrolment status - for example only enrolled students with a submit capability are allowed to submit assignments.
is_enrolled() get_enrolled_sql() get_enrolled_users()
Course login and access restrictions
....