lib/classes/output/inplace_editable.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  * Contains class \core\output\inplace_editable
  19  *
  20  * @package    core
  21  * @category   output
  22  * @copyright  2016 Marina Glancy
  23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  */
  25
  26 namespace core\output;
  27
  28 use templatable;
  29 use renderable;
  30 use lang_string;
  31
  32 /**
  33  * Class allowing to quick edit a title inline
  34  *
  35  * This class is used for displaying an element that can be in-place edited by the user. To display call:
  36  * echo $OUTPUT->render($element);
  37  * or
  38  * echo $OUTPUT->render_from_template('core/inplace_editable', $element->export_for_template($OUTPUT));
  39  *
  40  * Template core/inplace_editable will automatically load javascript module with the same name
  41  * core/inplace_editable. Javascript module registers a click-listener on edit link and
  42  * then replaces the displayed value with an input field. On "Enter" it sends a request
  43  * to web service core_update_inplace_editable, which invokes the callback from the component.
  44  * Any exception thrown by the web service (or callback) is displayed as an error popup.
  45  *
  46  * Callback {$component}_inplace_editable($itemtype, $itemid, $newvalue) must be present in the lib.php file of
  47  * the component or plugin. It must return instance of this class.
  48  *
  49  * @package    core
  50  * @category   output
  51  * @copyright  2016 Marina Glancy
  52  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  53  */
  54 class inplace_editable implements templatable, renderable {
  55
  56     /**
  57      * @var string component responsible for diplsying/updating
  58      */
  59     protected $component = null;
  60
  61     /**
  62      * @var string itemtype inside the component
  63      */
  64     protected $itemtype = null;
  65
  66     /**
  67      * @var int identifier of the editable element (usually database id)
  68      */
  69     protected $itemid = null;
  70
  71     /**
  72      * @var string value of the editable element as it is present in the database
  73      */
  74     protected $value = null;
  75
  76     /**
  77      * @var string value of the editable element as it should be displayed,
  78      * must be formatted and may contain links or other html tags
  79      */
  80     protected $displayvalue = null;
  81
  82     /**
  83      * @var string label for the input element (for screenreaders)
  84      */
  85     protected $editlabel = null;
  86
  87     /**
  88      * @var string hint for the input element (for screenreaders)
  89      */
  90     protected $edithint = null;
  91
  92     /**
  93      * @var bool indicates if the current user is allowed to edit this element - set in constructor after permissions are checked
  94      */
  95     protected $editable = false;
  96
  97     /**
  98      * @var string type of the element - text, toggle or select
  99      */
 100     protected $type = 'text';
 101
 102     /**
 103      * @var string options for the element, for example new value for the toggle or json-encoded list of options for select
 104      */
 105     protected $options = '';
 106
 107     /**
 108      * Constructor.
 109      *
 110      * @param string $component name of the component or plugin responsible for the updating of the value (must declare callback)
 111      * @param string $itemtype type of the item inside the component - each component/plugin may implement multiple inplace-editable elements
 112      * @param int $itemid identifier of the item that can be edited in-place
 113      * @param bool $editable whether this value is editable (check capabilities and editing mode), if false, only "displayvalue"
 114      *              will be displayed without anything else
 115      * @param string $displayvalue what needs to be displayed to the user, it must be cleaned, with applied filters (call
 116      *              {@link format_string()}). It may be wrapped in an html link, contain icons or other decorations
 117      * @param string $value what needs to be edited - usually raw value from the database, it may contain multilang tags
 118      * @param lang_string|string $edithint hint (title) that will be displayed under the edit link
 119      * @param lang_string|string $editlabel label for the input element in the editing mode (for screenreaders)
 120      */
 121     public function __construct($component, $itemtype, $itemid, $editable,
 122             $displayvalue, $value = null, $edithint = null, $editlabel = null) {
 123         $this->component = $component;
 124         $this->itemtype = $itemtype;
 125         $this->itemid = $itemid;
 126         $this->editable = $editable;
 127         $this->displayvalue = $displayvalue;
 128         $this->value = $value;
 129         $this->edithint = $edithint;
 130         $this->editlabel = $editlabel;
 131     }
 132
 133     /**
 134      * Sets the element type to be a toggle
 135      *
 136      * For toggle element $editlabel is not used.
 137      * $displayvalue must be specified, it can have text or icons but can not contain html links.
 138      *
 139      * Toggle element can have two or more options.
 140      *
 141      * @param array $options toggle options as simple, non-associative array; defaults to array(0,1)
 142      * @return self
 143      */
 144     public function set_type_toggle($options = null) {
 145         if ($options === null) {
 146             $options = array(0, 1);
 147         }
 148         $options = array_values($options);
 149         $idx = array_search($this->value, $options, true);
 150         if ($idx === false) {
 151             throw new \coding_exception('Specified value must be one of the toggle options');
 152         }
 153         $nextvalue = ($idx < count($options) - 1) ? $idx + 1 : 0;
 154
 155         $this->type = 'toggle';
 156         $this->options = (string)$nextvalue;
 157         return $this;
 158     }
 159
 160     /**
 161      * Sets the element type to be a dropdown
 162      *
 163      * For select element specifying $displayvalue is optional, if null it will
 164      * be assumed that $displayvalue = $options[$value].
 165      * However displayvalue can still be specified if it needs icons and/or
 166      * html links.
 167      *
 168      * If only one option specified, the element will not be editable.
 169      *
 170      * @param array $options associative array with dropdown options
 171      * @return self
 172      */
 173     public function set_type_select($options) {
 174         if (!array_key_exists($this->value, $options)) {
 175             throw new \coding_exception('Options for select element must contain an option for the specified value');
 176         }
 177         if (count($options) < 2) {
 178             $this->editable = false;
 179         }
 180         $this->type = 'select';
 181
 182         $pairedoptions = [];
 183         foreach ($options as $key => $value) {
 184             $pairedoptions[] = [
 185                 'key' => $key,
 186                 'value' => $value,
 187             ];
 188         }
 189         $this->options = json_encode($pairedoptions);
 190         if ($this->displayvalue === null) {
 191             $this->displayvalue = $options[$this->value];
 192         }
 193         return $this;
 194     }
 195
 196     /**
 197      * Sets the element type to be an autocomplete field
 198      *
 199      * @param array $options associative array with dropdown options
 200      * @param array $attributes associative array with attributes for autoselect field. See AMD module core/form-autocomplete.
 201      * @return self
 202      */
 203     public function set_type_autocomplete($options, $attributes) {
 204         $this->type = 'autocomplete';
 205
 206         $pairedoptions = [];
 207         foreach ($options as $key => $value) {
 208             $pairedoptions[] = [
 209                 'key' => $key,
 210                 'value' => $value,
 211             ];
 212         }
 213         $this->options = json_encode(['options' => $pairedoptions, 'attributes' => $attributes]);
 214         return $this;
 215     }
 216
 217     /**
 218      * Whether the link should contain all of the content or not.
 219      */
 220     protected function get_linkeverything() {
 221         if ($this->type === 'toggle') {
 222             return true;
 223         }
 224
 225         if (preg_match('#<a .*>.*</a>#', $this->displayvalue) === 1) {
 226             return false;
 227         }
 228
 229         return true;
 230     }
 231
 232     /**
 233      * Export this data so it can be used as the context for a mustache template (core/inplace_editable).
 234      *
 235      * @param renderer_base $output typically, the renderer that's calling this function
 236      * @return array data context for a mustache template
 237      */
 238     public function export_for_template(\renderer_base $output) {
 239         if (!$this->editable) {
 240             return array(
 241                 'displayvalue' => (string)$this->displayvalue
 242             );
 243         }
 244
 245         return array(
 246             'component' => $this->component,
 247             'itemtype' => $this->itemtype,
 248             'itemid' => $this->itemid,
 249             'displayvalue' => (string)$this->displayvalue,
 250             'value' => (string)$this->value,
 251             'edithint' => (string)$this->edithint,
 252             'editlabel' => (string)$this->editlabel,
 253             'type' => $this->type,
 254             'options' => $this->options,
 255             'linkeverything' => $this->get_linkeverything() ? 1 : 0,
 256         );
 257     }
 258
 259     /**
 260      * Renders this element
 261      *
 262      * @param renderer_base $output typically, the renderer that's calling this function
 263      * @return string
 264      */
 265     public function render(\renderer_base $output) {
 266         return $output->render_from_template('core/inplace_editable', $this->export_for_template($output));
 267     }
 268 }