Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Availability API: Difference between revisions

From MoodleDocs
(Created page with "{{Moodle 2.7}} {{Infobox Project |name = Availability API |state = Integration review |tracker = MDL-44070 |discussion = https://moodle.org/mod/forum/discuss.php?d=253958 |as...")
 
No edit summary
Line 9: Line 9:
}}
}}


(Work in progress)
= Availability API =
 
The availability API controls access to activities and sections. For example, a teacher could restrict access so that an activity cannot be accessed until a certain date, or so that a section cannot be accessed unless users have a certain grade in a quiz.
 
The conditional availability system defaults to off; users enable it from the advanced features page in settings. You can still call the API functions even if the system is turned off.
 
== Change from Moodle 2.6 and below ==
 
This replaces the previous API (2.6 and below) in conditionlib.php. The main differences in the new code are:
 
* Supports plugins for different types of condition.
* Allows conditions to be combined in Boolean logic tree structures.
 
If you have code using conditionlib.php, you'll see deprecation warnings advising you how to modify your code.
 
== Using the API ==
 
In most cases you do not need to use the API directly because the system handles it. For example, if you are writing a module:
 
* The system will automatically prevent users accessing your module if they do not meet an availability condition (unless they have the ability to access hidden activities). This happens when you call require_login and pass your module information.
* Your module's form will automatically have controls for setting availability restriction, as part of the standard form controls.
 
However for special cases you might need to use API features. There are two main uses, shown below.
 
=== Check if the current user can access an activity ===
 
To check if the current user can access an activity (supposing you have a $course and $cmid):
 
<code php>
$modinfo = get_fast_modinfo($course);
$cm = $modinfo->get_cm($cmid);
if ($cm->uservisible) {
    // User can access the activity.
} else if ($cm->availableinfo) {
    // User cannot access the activity, but on the front page they will
    // see a link to it, greyed-out, with information (HTML format) from
    // $cm->availableinfo about why they can't access it.
} else {
    // User cannot access the activity and they will not see it at all.
}
</code>
 
There are similar properties for sections.
 
* You do not need to check the section properties when checking access for an activity, as the system takes these into account. (If the user cannot access a section, then $cm->uservisible will return false for all activities within the section.)
* You do not need to additionally check $cm->visible; $cm->uservisible already takes this into account too.
 
These properties are worked out for the current user. You can also obtain them for a different user by passing a user ID to get_fast_modinfo, although be aware that doing this repeatedly for different users will be slow.
 
=== Display a list of users who may be able to access the current activity ===
 
Sometimes you need to display a list of users who may be able to access the current activity.
 
While you could use the above approach for each user, this would be slow and also is generally not what you require. For example, if you have an activity such as an assignment which is set to be available to students until a certain date, and if you want to display a list of potential users within that activity, you probably don't want to make the list blank immediately the date occurs.
 
The system divides availability conditions into two types:
 
* Applied to user lists. (Group, grouping, profile condition.)
* Not applied to user lists. (Date, completion, grade.)
 
In general, the conditions which we expect are likely to change over time (such as dates) or as a result of user actions (such as grades) are not applied to user lists.
 
If you have a list of users (for example you could obtain this using one of the 'get enrolled users' functions), you can filter it to include only those users who are allowed to see an activity with this code:
 
<code php>
$info = new \core_availability\info_module($cm);
$filtered = $info->filter_user_list($users);
</code>
 
* This does not currently include the groupmembersonly flag (if enabled). You can filter separately for this setting.
* This does not currently include the $cm->visible setting, nor does it take into account the viewhiddenactivities setting.
 
== Implementing new availability conditions ==
 
You can implement new availability conditions... (TODO)

Revision as of 17:55, 7 April 2014

Moodle 2.7


Availability API
Project state Integration review
Tracker issue MDL-44070
Discussion https://moodle.org/mod/forum/discuss.php?d=253958
Assignee sam marshall (OU)


Availability API

The availability API controls access to activities and sections. For example, a teacher could restrict access so that an activity cannot be accessed until a certain date, or so that a section cannot be accessed unless users have a certain grade in a quiz.

The conditional availability system defaults to off; users enable it from the advanced features page in settings. You can still call the API functions even if the system is turned off.

Change from Moodle 2.6 and below

This replaces the previous API (2.6 and below) in conditionlib.php. The main differences in the new code are:

  • Supports plugins for different types of condition.
  • Allows conditions to be combined in Boolean logic tree structures.

If you have code using conditionlib.php, you'll see deprecation warnings advising you how to modify your code.

Using the API

In most cases you do not need to use the API directly because the system handles it. For example, if you are writing a module:

  • The system will automatically prevent users accessing your module if they do not meet an availability condition (unless they have the ability to access hidden activities). This happens when you call require_login and pass your module information.
  • Your module's form will automatically have controls for setting availability restriction, as part of the standard form controls.

However for special cases you might need to use API features. There are two main uses, shown below.

Check if the current user can access an activity

To check if the current user can access an activity (supposing you have a $course and $cmid):

$modinfo = get_fast_modinfo($course); $cm = $modinfo->get_cm($cmid); if ($cm->uservisible) {

   // User can access the activity.

} else if ($cm->availableinfo) {

   // User cannot access the activity, but on the front page they will
   // see a link to it, greyed-out, with information (HTML format) from
   // $cm->availableinfo about why they can't access it.

} else {

   // User cannot access the activity and they will not see it at all.

}

There are similar properties for sections.

  • You do not need to check the section properties when checking access for an activity, as the system takes these into account. (If the user cannot access a section, then $cm->uservisible will return false for all activities within the section.)
  • You do not need to additionally check $cm->visible; $cm->uservisible already takes this into account too.

These properties are worked out for the current user. You can also obtain them for a different user by passing a user ID to get_fast_modinfo, although be aware that doing this repeatedly for different users will be slow.

Display a list of users who may be able to access the current activity

Sometimes you need to display a list of users who may be able to access the current activity.

While you could use the above approach for each user, this would be slow and also is generally not what you require. For example, if you have an activity such as an assignment which is set to be available to students until a certain date, and if you want to display a list of potential users within that activity, you probably don't want to make the list blank immediately the date occurs.

The system divides availability conditions into two types:

  • Applied to user lists. (Group, grouping, profile condition.)
  • Not applied to user lists. (Date, completion, grade.)

In general, the conditions which we expect are likely to change over time (such as dates) or as a result of user actions (such as grades) are not applied to user lists.

If you have a list of users (for example you could obtain this using one of the 'get enrolled users' functions), you can filter it to include only those users who are allowed to see an activity with this code:

$info = new \core_availability\info_module($cm); $filtered = $info->filter_user_list($users);

  • This does not currently include the groupmembersonly flag (if enabled). You can filter separately for this setting.
  • This does not currently include the $cm->visible setting, nor does it take into account the viewhiddenactivities setting.

Implementing new availability conditions

You can implement new availability conditions... (TODO)