Development:Roles and modules

This is a page describing how to make Moodle modules work under 1.7 roles system. For more background information, please read the roles page. For any clarifications please post to developer's forum.

Introduction

Moodle 1.6 and below uses 7 default roles, namely primary admin, admin, editting teachers, non-editting teachers, student and guest. To check a permission, we normally use isteacheredit($courseid), isguest() etc.

Under the new 1.7 system, we use a different function call has_capability, more on this later.

Context

Context is an important concept to make roles work. There are currently 8 levels

define('CONTEXT_SYSTEM', 10); define('CONTEXT_PERSONAL', 20); define('CONTEXT_USERID', 30); define('CONTEXT_COURSECAT', 40); define('CONTEXT_COURSE', 50); define('CONTEXT_GROUP', 60); define('CONTEXT_MODULE', 70); define('CONTEXT_BLOCK', 80);

They are stored as a tuple [contextlevel][instanceid]. For example course with id =2 would be [50][2]. Module with id 495 would be [70][495].

At module level, you only need to worry about CONTEXT_MODULE. Normally, foreach page accessible in your module you would need to load the module using get_context_instance(). The way to use it for modules is $context = get_context_instance(CONTEXT_MODULE, $cm->id); where $cm is the course module object that you would normally have anyway. The context is needed for every permission check later on in all your pages.

The has_capability($capability, $contextid, $kill) function

$capability is the name of the capability $contextid is normally $context->id, the module context id $kill set to 1 if you want to kill the page, it will throw an error and inform the user that required permission is missing.

This function looks up a capability for a given context and associated parents recursively. We are pretty much relying on this funciton alone to resolve all capability issues. Original isteacher(), isadmin(), isstudent() etc should all be changed accordingly.

Code rewrite

Some modules might require some tiny rewrites because permission is only checked once at the top, for example script only checks for isstudent() at the top. Now we are able to refine those capabilities, so we need to put the required code changes (add has_capability()) to where the specific capability is needed. For example, in a forum we check to see if user is a student before displaying a discussion, now we need to check individual permissions for forum_canread and forum_canreply.

Sample code

// somewhere at the top, after getting $cm, load context

$context = get_context_instance(CONTEXT_MODULE, $cm->id);

...

has_capability('forum_read', $cm->id, true); // kills this page if user is not allowed to read

...

if (has_capability('forum_reply', $cm->id) {

   print_reply_link();

}

Core API

The core API is located at libdir/accesslib, if you would like to read further =)