Availability conditions

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

I am hoping this code will be included in Moodle 2.7 but this is not yet confirmed. This documentation is somewhat speculative but I came to a convenient point to write it so I'm putting it here.

Moodle 2.7

Introduction

Availability conditions allow teachers to restrict an activity or section so that only certain users can access it.

Some of the conditions included in standard Moodle are:

Date (users can only access activity after specified date)
Grade (users can only access activity if they have a certain grade in another activity)

History

Availability conditions are being developed for introduction, hopefully, with Moodle 2.7.

Template

A simple example is the date condition which can be found in /availability/condition/date.

File structure

Files go within /availability/condition/name, where 'name' is the name of the condition plugin.

version.php

Standard version.php for the component.

lang/en/availability_name.php

Language strings for the plugin. Required strings:

pluginname - name of plugin.
title - text of button for adding this type of plugin.
description - explanatory text that goes alongside the button in the 'add restriction' dialog.

Example:

$string['description'] = 'Require students to complete (or not complete) another activity.'; $string['pluginname'] = 'Restriction by activity completion'; $string['title'] = 'Activity completion';

You will also need to add your own strings for two main purposes:

Creating suitable form controls for users who are editing the activity settings.
Displaying information about the condition.

classes/condition.php

This PHP class implements the back-end of the condition; in other words, this class contains the code which decides whether a user is allowed to access an activity that uses this condition, or not.

Here's an outline of the code (with standard PHPdoc comments omitted to save space) for a simple example in which there is a boolean value that controls whether access is allowed or not.

// You must use the right namespace (matching your plugin component name). namespace availability_name;

defined('MOODLE_INTERNAL') || die();

class condition extends \core_availability\condition {

   // Any data associated with the condition can be stored in member
   // variables. Here's an example variable:
   protected $allow;

   public function __construct($structure) {
       // Retrieve any necessary data from the $structure here. The
       // structure is extracted from JSON data stored in the database
       // as part of the tree structure of conditions relating to an
       // activity or section.
       // For example, you could obtain the 'allow' value:
       $this->allow = $structure->allow;

       // It is also a good idea to check for invalid values here and
       // throw a coding_exception if the structure is wrong.
   }

   public function is_available(&$information, $not,
           \core_availability\info $info, $grabthelot, $userid) {
       // This function needs to check whether the condition is true
       // or not for the user specified in $userid. If the condition
       // is true, $information should be set to an empty string. If
       // false, it should be set to a message.

       // The value $not should be used to negate the condition. Other
       // parameters provide data which can be used when evaluating the
       // condition.

       // For this trivial example, we will just use $allow to decide
       // whether it is allowed or not. In a real condition you would
       // do some calculation depending on the specified user.
       $allow = $this->allow;
       if ($not) {
           $allow = !$allow;
       }
       if ($allow) {
           $information = ;
       } else {
           $information = 'Haha, you are not allowed';
       }
       return $allow;
   }

   public function get_description($full, $not, \core_availability\info $info) {
       // This function just returns the information that shows about
       // the condition on editing screens. Usually it is similar to
       // the information shown if the user doesn't meet the
       // condition (it does not depend on the current user).
       $allow = $not ? !$this->allow : $this->allow;
       return $allow ? 'Users are allowed' : 'Users not allowed';
   }

   protected function get_debug_string() {
       // This function is only normally used for unit testing and
       // stuff like that. Just make a short string representation
       // of the values of the condition, suitable for developers.
       return $this->allow ? 'YES' : 'NO';
   }

}

There are other functions you might also want to implement. For example, if your condition should apply to lists of users (in general, conditions which are 'permanent' such as group conditions apply to lists, whereas those which are 'temporary' such as date or grade conditions do not) then you should also implement is_applied_to_user_lists and filter_user_list functions. To see the full list, look at the PHPdoc for the condition and tree_node classes inside availability/classes.

tests/condition_test.php

Normally you would write a unit test for the condition inside this file. See existing unit tests for examples.

Documentation