availability/classes/condition.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * Base class for a single availability condition.
  19  *
  20  * All condition types must extend this class.
  21  *
  22  * @package core_availability
  23  * @copyright 2014 The Open University
  24  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25  */
  26
  27 namespace core_availability;
  28
  29 defined('MOODLE_INTERNAL') || die();
  30
  31 /**
  32  * Base class for a single availability condition.
  33  *
  34  * All condition types must extend this class.
  35  *
  36  * The structure of a condition in JSON input data is:
  37  *
  38  * { type:'date', ... }
  39  *
  40  * where 'date' is the name of the plugin (availability_date in this case) and
  41  * ... is arbitrary extra data to be used by the plugin.
  42  *
  43  * Conditions require a constructor with one parameter: $structure. This will
  44  * contain all the JSON data for the condition. If the structure of the data
  45  * is incorrect (e.g. missing fields) then the constructor may throw a
  46  * coding_exception. However, the constructor should cope with all data that
  47  * was previously valid (e.g. if the format changes, old data may still be
  48  * present in a restore, so there should be a default value for any new fields
  49  * and old ones should be handled correctly).
  50  *
  51  * @package core_availability
  52  * @copyright 2014 The Open University
  53  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  54  */
  55 abstract class condition extends tree_node {
  56
  57     /**
  58      * Determines whether a particular item is currently available
  59      * according to this availability condition.
  60      *
  61      * If implementations require a course or modinfo, they should use
  62      * the get methods in $info.
  63      *
  64      * The $not option is potentially confusing. This option always indicates
  65      * the 'real' value of NOT. For example, a condition inside a 'NOT AND'
  66      * group will get this called with $not = true, but if you put another
  67      * 'NOT OR' group inside the first group, then a condition inside that will
  68      * be called with $not = false. We need to use the real values, rather than
  69      * the more natural use of the current value at this point inside the tree,
  70      * so that the information displayed to users makes sense.
  71      *
  72      * @param bool $not Set true if we are inverting the condition
  73      * @param info $info Item we're checking
  74      * @param bool $grabthelot Performance hint: if true, caches information
  75      *   required for all course-modules, to make the front page and similar
  76      *   pages work more quickly (works only for current user)
  77      * @param int $userid User ID to check availability for
  78      * @return bool True if available
  79      */
  80     public abstract function is_available($not, info $info, $grabthelot, $userid);
  81
  82     public function check_available($not, info $info, $grabthelot, $userid) {
  83         // Use is_available, and we always display (at this stage).
  84         $allow = $this->is_available($not, $info, $grabthelot, $userid);
  85         return new result($allow, $this);
  86     }
  87
  88     public function is_available_for_all($not = false) {
  89         // Default is that all conditions may make something unavailable.
  90         return false;
  91     }
  92
  93     /**
  94      * Display a representation of this condition (used for debugging).
  95      *
  96      * @return string Text representation of condition
  97      */
  98     public function __toString() {
  99         return '{' . $this->get_type() . ':' . $this->get_debug_string() . '}';
 100     }
 101
 102     /**
 103      * Gets the type name (e.g. 'date' for availability_date) of plugin.
 104      *
 105      * @return string The type name for this plugin
 106      */
 107     protected function get_type() {
 108         return preg_replace('~^availability_(.*?)\\\\condition$~', '$1', get_class($this));
 109     }
 110
 111     /**
 112      * Obtains a string describing this restriction (whether or not
 113      * it actually applies). Used to obtain information that is displayed to
 114      * students if the activity is not available to them, and for staff to see
 115      * what conditions are.
 116      *
 117      * The $full parameter can be used to distinguish between 'staff' cases
 118      * (when displaying all information about the activity) and 'student' cases
 119      * (when displaying only conditions they don't meet).
 120      *
 121      * If implementations require a course or modinfo, they should use
 122      * the get methods in $info.
 123      *
 124      * The special string <AVAILABILITY_CMNAME_123/> can be returned, where
 125      * 123 is any number. It will be replaced with the correctly-formatted
 126      * name for that activity.
 127      *
 128      * @param bool $full Set true if this is the 'full information' view
 129      * @param bool $not Set true if we are inverting the condition
 130      * @param info $info Item we're checking
 131      * @return string Information string (for admin) about all restrictions on
 132      *   this item
 133      */
 134     public abstract function get_description($full, $not, info $info);
 135
 136     /**
 137      * Obtains a string describing this restriction, used when there is only
 138      * a single restriction to display. (I.e. this provides a 'short form'
 139      * rather than showing in a list.)
 140      *
 141      * Default behaviour sticks the prefix text, normally displayed above
 142      * the list, in front of the standard get_description call.
 143      *
 144      * If implementations require a course or modinfo, they should use
 145      * the get methods in $info.
 146      *
 147      * The special string <AVAILABILITY_CMNAME_123/> can be returned, where
 148      * 123 is any number. It will be replaced with the correctly-formatted
 149      * name for that activity.
 150      *
 151      * @param bool $full Set true if this is the 'full information' view
 152      * @param bool $not Set true if we are inverting the condition
 153      * @param info $info Item we're checking
 154      * @return string Information string (for admin) about all restrictions on
 155      *   this item
 156      */
 157     public function get_standalone_description($full, $not, info $info) {
 158         return get_string('list_root_and', 'availability') . ' ' .
 159                 $this->get_description($full, $not, $info);
 160     }
 161
 162     /**
 163      * Obtains a representation of the options of this condition as a string,
 164      * for debugging.
 165      *
 166      * @return string Text representation of parameters
 167      */
 168     protected abstract function get_debug_string();
 169
 170     public function update_dependency_id($table, $oldid, $newid) {
 171         // By default, assumes there are no dependent ids.
 172         return false;
 173     }
 174
 175     /**
 176      * If the plugin has been configured to rely on a particular activity's
 177      * completion value, it should return true here. (This is necessary so that
 178      * we know the course page needs to update when that activity becomes
 179      * complete.)
 180      *
 181      * Default implementation returns false.
 182      *
 183      * @param \stdClass $course Moodle course object
 184      * @param int $cmid ID of activity whose completion value is considered
 185      * @return boolean True if the availability of something else may rely on it
 186      */
 187     public static function completion_value_used($course, $cmid) {
 188         return false;
 189     }
 190 }