|
| 1 | +--- |
| 2 | +title: Inplace editable |
| 3 | +tags: |
| 4 | + - AJAX |
| 5 | + - Javascript |
| 6 | +--- |
| 7 | +import { Since } from '@site/src/components'; |
| 8 | + |
| 9 | +<Since versions={["3.1"]} /> |
| 10 | + |
| 11 | +inplace_editable is a mini-API introduced under [MDL-51802](https://tracker.moodle.org/browse/MDL-51802) for Moodle 3.1. It allows developers easily add in-place editing of a value on any page. The interface is the same as sections and activity name editing. It is implemented as AMD module using JQuery and is re-usable. |
| 12 | + |
| 13 | + |
| 14 | + |
| 15 | +## Implementing inplace_editable in a plugin |
| 16 | + |
| 17 | +The best way is to explain the usage on a simple example. Imagine we have plugin `tool_mytest` that needs to implement in-place editing of a field 'name' from db table `tool_mytest_mytable`. We are going to call this itemtype "mytestname". Each plugin (or core component) may use as many itemtypes as it needs. |
| 18 | + |
| 19 | +Define a callback in `/admin/tool/mytest/lib.php` that starts with the plugin name and ends with `_inplace_editable`: |
| 20 | + |
| 21 | +```php |
| 22 | +function tool_mytest_inplace_editable($itemtype, $itemid, $newvalue) { |
| 23 | + if ($itemtype === 'mytestname') { |
| 24 | + global $DB; |
| 25 | + $record = $DB->get_record('tool_mytest_mytable', array('id' => $itemid), '*', MUST_EXIST); |
| 26 | + // Must call validate_context for either system, or course or course module context. |
| 27 | + // This will both check access and set current context. |
| 28 | + \external_api::validate_context(context_system::instance()); |
| 29 | + // Check permission of the user to update this item. |
| 30 | + require_capability('tool/mytest:update', context_system::instance()); |
| 31 | + // Clean input and update the record. |
| 32 | + $newvalue = clean_param($newvalue, PARAM_NOTAGS); |
| 33 | + $DB->update_record('tool_mytest_mytable', array('id' => $itemid, 'name' => $newvalue)); |
| 34 | + // Prepare the element for the output: |
| 35 | + $record->name = $newvalue; |
| 36 | + return new \core\output\inplace_editable('tool_mytest', 'mytestname', $record->id, true, |
| 37 | + format_string($record->name), $record->name, 'Edit mytest name', 'New value for ' . format_string($record->name)); |
| 38 | + } |
| 39 | +} |
| 40 | +``` |
| 41 | + |
| 42 | +In your renderer or wherever you actually display the name, use the same `inplace_editable` template: |
| 43 | + |
| 44 | +```php |
| 45 | +$tmpl = new \core\output\inplace_editable('tool_mytest', 'mytestname', $record->id, |
| 46 | + has_capability('tool/mytest:update', context_system::instance()), |
| 47 | + format_string($record->name), $record->name, 'Edit mytest name', 'New value for ' . format_string($record->name)); |
| 48 | +echo $OUTPUT->render($tmpl); |
| 49 | +``` |
| 50 | + |
| 51 | +This was a very simplified example, in the real life you will probably want to: |
| 52 | + |
| 53 | +- Create a function (or class extending `core\output\inplace_editable`) to form the instance of templateable object so you don't need to duplicate code; |
| 54 | +- Use language strings for `edithint` and `editlabel`, best practice is to use `new lang_string` because these strings will not be needed if `editable=false` |
| 55 | +- Use an existing function to update a record (which hopefully also validates input value and triggers events) |
| 56 | +- Add unit tests and behat tests. There is a useful behat step **I press key "13" in the field "New value for myname"** |
| 57 | + |
| 58 | +## Toggles and dropdowns |
| 59 | + |
| 60 | +You may choose to set the UI for your inplace editable element to be a string value (default), toggle or dropdown. |
| 61 | + |
| 62 | +Examples of dropdown setup (see also [example by overriding class](https://github.com/moodle/moodle/blob/master/tag/classes/output/tagareacollection.php)): |
| 63 | + |
| 64 | +```php |
| 65 | +$tagcollections = \core_tag_collection::get_collections_menu(true); |
| 66 | +$tmpl = new \core\output\inplace_editable('core_tag', 'tagareacollection', $tagarea->id, $editable, |
| 67 | + null, $value, $edithint, $editlabel); |
| 68 | +$tmpl->set_type_select($tagcollections); |
| 69 | +// Note that $displayvalue is not needed (null was passed in the example above) - it will be automatically taken from options. |
| 70 | +// $value in the example above must be an existing index from the $tagcollections array, otherwise exception will be thrown. |
| 71 | +``` |
| 72 | + |
| 73 | +Example of toggle setup (see also [example by overriding class](https://github.com/moodle/moodle/blob/master/tag/classes/output/tagareaenabled.php)): |
| 74 | + |
| 75 | +```php |
| 76 | +$tmpl = new \core\output\inplace_editable('core_tag', 'tagflag', $tag->id, $editable, $displayvalue, $value, $hint); |
| 77 | +$tmpl->set_type_toggle(array(0, 1)); |
| 78 | +// Note that $editlabel is not needed. |
| 79 | +// $value must be an existing element of the array passed to set_type_toggle(), otherwise exception will be thrown. |
| 80 | +// $displayvalue in toggles is usually an image, for example closed/open eye. It is easier to implement by |
| 81 | +// overriding the class. In this case $displayvalue can be generated from $value during exporting. |
| 82 | +``` |
| 83 | + |
| 84 | +## How does it work |
| 85 | + |
| 86 | +`inplace_editable` consists of |
| 87 | + |
| 88 | +- Templateable/renderable **class core\output\inplace_editable** |
| 89 | +- Template **core/inplace_editable** |
| 90 | +- JavaScript module **core/inplace_editable** |
| 91 | +- Web service **core_update_inplace_editable** available from AJAX |
| 92 | + |
| 93 | +All four call each other so it's hard to decide where we start explaining this circle of friends but let's start with web service. |
| 94 | + |
| 95 | +1. **Web service** receives arguments (`$component`, `$itemtype`, `$itemid`, `$newvalue`) - it searches for the inplace_editable callback in the component. Then web service calls this callback as `{component}_inplace_editable($itemtype, $itemid, $newvalue)`, this must return templateable element which is sent back to the web service caller. Web service requires user to be logged in. **Any other `capability/access` checks must be performed inside the callback.** |
| 96 | + |
| 97 | +2. **Templateable element** contains such properties as component, `itemtype`, `itemid`, `displayvalue`, `value`, `editlabel` and `edithint`. When used in a **template** It only renders the displayvalue and the edit link (with `title=edithint`). All other properties are rendered as `data-xxx` attributes. Template also ensures that JavaScript module is loaded. |
| 98 | + |
| 99 | +3. **JavaScript module** registers a listener to when the edit link is clicked and then it replaces the displayvalue with the text input box that allows to edit value. When user presses "Enter" the AJAX request is called to the web service and code from the component is executed. If web service throws an exception it is displayed for user as a popup. |
| 100 | + |
| 101 | +## Events |
| 102 | + |
| 103 | +Plugin page can listen to JQuery events that are triggered on successful update or when update failed. Example of the listeners (as inline JS code): |
| 104 | + |
| 105 | +```php |
| 106 | +$PAGE->requires->js_amd_inline(" |
| 107 | +require(['jquery'], function(\$) { |
| 108 | + $('body').on('updatefailed', '[data-inplaceeditable]', function(e) { |
| 109 | + var exception = e.exception; // The exception object returned by the callback. |
| 110 | + var newvalue = e.newvalue; // The value that user tried to udpated the element to. |
| 111 | + e.preventDefault(); // This will prevent default error dialogue. |
| 112 | + // Do your own error processing here. |
| 113 | + }); |
| 114 | + $('body').on('updated', '[data-inplaceeditable]', function(e) { |
| 115 | + var ajaxreturn = e.ajaxreturn; // Everything that web service returned. |
| 116 | + var oldvalue = e.oldvalue; // Element value before editing (note, this is raw value and not display value). |
| 117 | + // Do your own stuff, for example update all other occurences of this element on the page. |
| 118 | + }); |
| 119 | +}); |
| 120 | +"); |
| 121 | +``` |
| 122 | + |
| 123 | +## See also |
0 commit comments