[Summary view]

Differences Between: [Versions 39 and 310] [Versions 39 and 311] [Versions 39 and 400] [Versions 39 and 401] [Versions 39 and 402] [Versions 39 and 403]

   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  }