2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
18 * Contains class \core\output\inplace_editable
22 * @copyright 2016 Marina Glancy
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 namespace core\output
;
33 * Class allowing to quick edit a title inline
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);
38 * echo $OUTPUT->render_from_template('core/inplace_editable', $element->export_for_template($OUTPUT));
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.
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.
51 * @copyright 2016 Marina Glancy
52 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
54 class inplace_editable
implements templatable
, renderable
{
57 * @var string component responsible for diplsying/updating
59 protected $component = null;
62 * @var string itemtype inside the component
64 protected $itemtype = null;
67 * @var int identifier of the editable element (usually database id)
69 protected $itemid = null;
72 * @var string value of the editable element as it is present in the database
74 protected $value = null;
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
80 protected $displayvalue = null;
83 * @var string label for the input element (for screenreaders)
85 protected $editlabel = null;
88 * @var string hint for the input element (for screenreaders)
90 protected $edithint = null;
93 * @var bool indicates if the current user is allowed to edit this element - set in constructor after permissions are checked
95 protected $editable = false;
98 * @var string type of the element - text, toggle or select
100 protected $type = 'text';
103 * @var string options for the element, for example new value for the toggle or json-encoded list of options for select
105 protected $options = '';
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)
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;
134 * Sets the element type to be a toggle
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.
139 * Toggle element can have two or more options.
141 * @param array $options toggle options as simple, non-associative array; defaults to array(0,1)
144 public function set_type_toggle($options = null) {
145 if ($options === null) {
146 $options = array(0, 1);
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');
153 $nextvalue = ($idx < count($options) - 1) ?
$idx +
1 : 0;
155 $this->type
= 'toggle';
156 $this->options
= (string)$nextvalue;
161 * Sets the element type to be a dropdown
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
168 * If only one option specified, the element will not be editable.
170 * @param array $options associative array with dropdown options
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');
177 if (count($options) < 2) {
178 $this->editable
= false;
180 $this->type
= 'select';
183 foreach ($options as $key => $value) {
189 $this->options
= json_encode($pairedoptions);
190 if ($this->displayvalue
=== null) {
191 $this->displayvalue
= $options[$this->value
];
197 * Sets the element type to be an autocomplete field
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.
203 public function set_type_autocomplete($options, $attributes) {
204 $this->type
= 'autocomplete';
207 foreach ($options as $key => $value) {
213 $this->options
= json_encode(['options' => $pairedoptions, 'attributes' => $attributes]);
218 * Whether the link should contain all of the content or not.
220 protected function get_linkeverything() {
221 if ($this->type
=== 'toggle') {
225 if (preg_match('#<a .*>.*</a>#', $this->displayvalue
) === 1) {
233 * Export this data so it can be used as the context for a mustache template (core/inplace_editable).
235 * @param renderer_base $output typically, the renderer that's calling this function
236 * @return array data context for a mustache template
238 public function export_for_template(\renderer_base
$output) {
239 if (!$this->editable
) {
241 'displayvalue' => (string)$this->displayvalue
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,
260 * Renders this element
262 * @param renderer_base $output typically, the renderer that's calling this function
265 public function render(\renderer_base
$output) {
266 return $output->render_from_template('core/inplace_editable', $this->export_for_template($output));