[Summary view]

Differences Between: [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   * Customfield component data controller abstract class
  19   *
  20   * @package   core_customfield
  21   * @copyright 2018 Toni Barbera <toni@moodle.com>
  22   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  namespace core_customfield;
  26  
  27  use core_customfield\output\field_data;
  28  
  29  defined('MOODLE_INTERNAL') || die;
  30  
  31  /**
  32   * Base class for custom fields data controllers
  33   *
  34   * This class is a wrapper around the persistent data class that allows to define
  35   * how the element behaves in the instance edit forms.
  36   *
  37   * Custom field plugins must define a class
  38   * \{pluginname}\data_controller extends \core_customfield\data_controller
  39   *
  40   * @package core_customfield
  41   * @copyright 2018 Toni Barbera <toni@moodle.com>
  42   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  43   */
  44  abstract class data_controller {
  45      /**
  46       * Data persistent
  47       *
  48       * @var data
  49       */
  50      protected $data;
  51  
  52      /**
  53       * Field that this data belongs to.
  54       *
  55       * @var field_controller
  56       */
  57      protected $field;
  58  
  59      /**
  60       * data_controller constructor.
  61       *
  62       * @param int $id
  63       * @param \stdClass|null $record
  64       */
  65      public function __construct(int $id, \stdClass $record) {
  66          $this->data = new data($id, $record);
  67      }
  68  
  69      /**
  70       * Creates an instance of data_controller
  71       *
  72       * Parameters $id, $record and $field can complement each other but not conflict.
  73       * If $id is not specified, fieldid must be present either in $record or in $field.
  74       * If $id is not specified, instanceid must be present in $record
  75       *
  76       * No DB queries are performed if both $record and $field are specified.
  77  
  78       * @param int $id
  79       * @param \stdClass|null $record
  80       * @param field_controller|null $field
  81       * @return data_controller
  82       * @throws \coding_exception
  83       * @throws \moodle_exception
  84       */
  85      public static function create(int $id, \stdClass $record = null, field_controller $field = null) : data_controller {
  86          global $DB;
  87          if ($id && $record) {
  88              // This warning really should be in persistent as well.
  89              debugging('Too many parameters, either id need to be specified or a record, but not both.',
  90                  DEBUG_DEVELOPER);
  91          }
  92          if ($id) {
  93              $record = $DB->get_record(data::TABLE, array('id' => $id), '*', MUST_EXIST);
  94          } else if (!$record) {
  95              $record = new \stdClass();
  96          }
  97  
  98          if (!$field && empty($record->fieldid)) {
  99              throw new \coding_exception('Not enough parameters to initialise data_controller - unknown field');
 100          }
 101          if (!$field) {
 102              $field = field_controller::create($record->fieldid);
 103          }
 104          if (empty($record->fieldid)) {
 105              $record->fieldid = $field->get('id');
 106          }
 107          if ($field->get('id') != $record->fieldid) {
 108              throw new \coding_exception('Field id from the record does not match field from the parameter');
 109          }
 110          $type = $field->get('type');
 111          $customfieldtype = "\\customfield_{$type}\\data_controller";
 112          if (!class_exists($customfieldtype) || !is_subclass_of($customfieldtype, self::class)) {
 113              throw new \moodle_exception('errorfieldtypenotfound', 'core_customfield', '', s($type));
 114          }
 115          $datacontroller = new $customfieldtype(0, $record);
 116          $datacontroller->field = $field;
 117          return $datacontroller;
 118      }
 119  
 120      /**
 121       * Returns the name of the field to be used on HTML forms.
 122       *
 123       * @return string
 124       */
 125      public function get_form_element_name() : string {
 126          return 'customfield_' . $this->get_field()->get('shortname');
 127      }
 128  
 129      /**
 130       * Persistent getter parser.
 131       *
 132       * @param string $property
 133       * @return mixed
 134       */
 135      final public function get($property) {
 136          return $this->data->get($property);
 137      }
 138  
 139      /**
 140       * Persistent setter parser.
 141       *
 142       * @param string $property
 143       * @param mixed $value
 144       * @return data
 145       */
 146      final public function set($property, $value) {
 147          return $this->data->set($property, $value);
 148      }
 149  
 150      /**
 151       * Return the name of the field in the db table {customfield_data} where the data is stored
 152       *
 153       * Must be one of the following:
 154       *   intvalue - can store integer values, this field is indexed
 155       *   decvalue - can store decimal values
 156       *   shortcharvalue - can store character values up to 255 characters long, this field is indexed
 157       *   charvalue - can store character values up to 1333 characters long, this field is not indexed but
 158       *     full text search is faster than on field 'value'
 159       *   value - can store character values of unlimited length ("text" field in the db)
 160       *
 161       * @return string
 162       */
 163      abstract public function datafield() : string;
 164  
 165      /**
 166       * Delete data. Element can override it if related information needs to be deleted as well (such as files)
 167       *
 168       * @return bool
 169       */
 170      public function delete() {
 171          return $this->data->delete();
 172      }
 173  
 174      /**
 175       * Persistent save parser.
 176       *
 177       * @return void
 178       */
 179      public function save() {
 180          $this->data->save();
 181      }
 182  
 183      /**
 184       * Field associated with this data
 185       *
 186       * @return field_controller
 187       */
 188      public function get_field() : field_controller {
 189          return $this->field;
 190      }
 191  
 192      /**
 193       * Saves the data coming from form
 194       *
 195       * @param \stdClass $datanew data coming from the form
 196       */
 197      public function instance_form_save(\stdClass $datanew) {
 198          $elementname = $this->get_form_element_name();
 199          if (!property_exists($datanew, $elementname)) {
 200              return;
 201          }
 202          $value = $datanew->$elementname;
 203          $this->data->set($this->datafield(), $value);
 204          $this->data->set('value', $value);
 205          $this->save();
 206      }
 207  
 208      /**
 209       * Prepares the custom field data related to the object to pass to mform->set_data() and adds them to it
 210       *
 211       * This function must be called before calling $form->set_data($object);
 212       *
 213       * @param \stdClass $instance the instance that has custom fields, if 'id' attribute is present the custom
 214       *    fields for this instance will be added, otherwise the default values will be added.
 215       */
 216      public function instance_form_before_set_data(\stdClass $instance) {
 217          $instance->{$this->get_form_element_name()} = $this->get_value();
 218      }
 219  
 220      /**
 221       * Checks if the value is empty
 222       *
 223       * @param mixed $value
 224       * @return bool
 225       */
 226      protected function is_empty($value) : bool {
 227          if ($this->datafield() === 'value' || $this->datafield() === 'charvalue' || $this->datafield() === 'shortcharvalue') {
 228              return '' . $value === '';
 229          }
 230          return empty($value);
 231      }
 232  
 233      /**
 234       * Checks if the value is unique
 235       *
 236       * @param mixed $value
 237       * @return bool
 238       */
 239      protected function is_unique($value) : bool {
 240          global $DB;
 241          $datafield = $this->datafield();
 242          $where = "fieldid = ? AND {$datafield} = ?";
 243          $params = [$this->get_field()->get('id'), $value];
 244          if ($this->get('id')) {
 245              $where .= ' AND id <> ?';
 246              $params[] = $this->get('id');
 247          }
 248          return !$DB->record_exists_select('customfield_data', $where, $params);
 249      }
 250  
 251      /**
 252       * Called from instance edit form in validation()
 253       *
 254       * @param array $data
 255       * @param array $files
 256       * @return array array of errors
 257       */
 258      public function instance_form_validation(array $data, array $files) : array {
 259          $errors = [];
 260          $elementname = $this->get_form_element_name();
 261          if ($this->get_field()->get_configdata_property('uniquevalues') == 1) {
 262              $value = $data[$elementname];
 263              if (!$this->is_empty($value) && !$this->is_unique($value)) {
 264                  $errors[$elementname] = get_string('erroruniquevalues', 'core_customfield');
 265              }
 266          }
 267          return $errors;
 268      }
 269  
 270      /**
 271       * Called from instance edit form in definition_after_data()
 272       *
 273       * @param \MoodleQuickForm $mform
 274       */
 275      public function instance_form_definition_after_data(\MoodleQuickForm $mform) {
 276  
 277      }
 278  
 279      /**
 280       * Used by handlers to display data on various places.
 281       *
 282       * @return string
 283       */
 284      public function display() : string {
 285          global $PAGE;
 286          $output = $PAGE->get_renderer('core_customfield');
 287          return $output->render(new field_data($this));
 288      }
 289  
 290      /**
 291       * Returns the default value as it would be stored in the database (not in human-readable format).
 292       *
 293       * @return mixed
 294       */
 295      public abstract function get_default_value();
 296  
 297      /**
 298       * Returns the value as it is stored in the database or default value if data record is not present
 299       *
 300       * @return mixed
 301       */
 302      public function get_value() {
 303          if (!$this->get('id')) {
 304              return $this->get_default_value();
 305          }
 306          return $this->get($this->datafield());
 307      }
 308  
 309      /**
 310       * Return the context of the field
 311       *
 312       * @return \context
 313       */
 314      public function get_context() : \context {
 315          if ($this->get('contextid')) {
 316              return \context::instance_by_id($this->get('contextid'));
 317          } else if ($this->get('instanceid')) {
 318              return $this->get_field()->get_handler()->get_instance_context($this->get('instanceid'));
 319          } else {
 320              // Context is not yet known (for example, entity is not yet created).
 321              return \context_system::instance();
 322          }
 323      }
 324  
 325      /**
 326       * Add a field to the instance edit form.
 327       *
 328       * @param \MoodleQuickForm $mform
 329       */
 330      public abstract function instance_form_definition(\MoodleQuickForm $mform);
 331  
 332      /**
 333       * Returns value in a human-readable format or default value if data record is not present
 334       *
 335       * This is the default implementation that most likely needs to be overridden
 336       *
 337       * @return mixed|null value or null if empty
 338       */
 339      public function export_value() {
 340          $value = $this->get_value();
 341  
 342          if ($this->is_empty($value)) {
 343              return null;
 344          }
 345  
 346          if ($this->datafield() === 'intvalue') {
 347              return (int)$value;
 348          } else if ($this->datafield() === 'decvalue') {
 349              return (float)$value;
 350          } else if ($this->datafield() === 'value') {
 351              return format_text($value, $this->get('valueformat'), ['context' => $this->get_context()]);
 352          } else {
 353              return format_string($value, true, ['context' => $this->get_context()]);
 354          }
 355      }
 356  
 357      /**
 358       * Persistent to_record parser.
 359       *
 360       * @return \stdClass
 361       */
 362      final public function to_record() {
 363          return $this->data->to_record();
 364      }
 365  }