From 97b5c961a6febf63a76ee94ec180c5bb405bf013 Mon Sep 17 00:00:00 2001 From: Peter Mayer Date: Tue, 28 Nov 2023 09:29:59 +0100 Subject: [PATCH] Add working examples and some clarifications to inplace_edit --- docs/apis/subsystems/output/inplace.md | 174 ++++++++++++++++++ .../apis/subsystems/output/inplace.md | 174 ++++++++++++++++++ 2 files changed, 348 insertions(+) diff --git a/docs/apis/subsystems/output/inplace.md b/docs/apis/subsystems/output/inplace.md index ad6224ef06..ac07b780f4 100644 --- a/docs/apis/subsystems/output/inplace.md +++ b/docs/apis/subsystems/output/inplace.md @@ -74,6 +74,68 @@ This was a very simplified example, in the real life you will probably want to: - Use an existing function to update a record (which hopefully also validates input value and triggers events) - Add unit tests and behat tests +
+ View example +
+ +```php title="admin/tool/mytest/classes/local/inplace_edit_text.php" + +class inplace_edit_text extends \core\output\inplace_editable { + /** + * Constructor. + * + * @param object $record + */ + public function __construct($record) { + parent::__construct( + component: 'tool_mytest', + // The item type as managed your plugin. + itemtype: 'mytesttext', + // An ID that relates to this instance of this item type. + itemid: $record->id, + // Whether this user can makes changes. + // Perhaps based upon a capability check. + editable: has_capability( + 'capname', + \context_system::instance(), + ), + // The display value of this item. + displayvalue: format_string($record->name), + // The machine-readable value. + value: $record->name, + // Hints and labels. + edithint: get_string('edithint', 'tool_mytest'), + editlabel: get_string('editlabel', 'tool_mytest'), + ); + $this->set_type_select($answeroptionstemp); + } + + /** + * Updates the value in database and returns itself. + * + * Called from inplace_editable callback + * + * @param int $itemid + * @param mixed $newvalue + * @return \self + */ + public static function update($itemid, $newvalue) { + // Clean the new value. + $newvalue = clean_param($newvalue, PARAM_INT); + + // {{ Do some mighty things here}} + + $record = $DB->get_record('xxx', ['id' => 'xxx']); + + // Finally return itself. + return new self($record); + } +} +``` + +
+
+ ## Toggles and dropdowns You may choose to set the UI for your inplace editable element to be a string value (default), toggle or dropdown. @@ -127,6 +189,118 @@ $tmpl = new \core\output\inplace_editable( $tmpl->set_type_toggle([0, 1]); ``` +
+ View example +
+ +```php title="admin/tool/mytest/classes/local/inplace_edit_select.php" +class inplace_edit_select extends \core\output\inplace_editable { + /** + * Constructor. + * + * @param \stdClass $record + */ + public function __construct($record) { + // Get the options for inplace_edit select box. + // The array needs the format: + // $options = [ + // 'value1' => 'text1', + // 'value2' => 'text2', + // ]; + $options = \tool_mytest\classes\helper::get_options(); + + parent::__construct( + component: 'tool_mytest', + // The item type as managed your plugin. + itemtype: 'mytestselect', + // An ID that relates to this instance of this item type. + itemid: $record->id, + // Whether this user can makes changes. + // Perhaps based upon a capability check. + editable: has_capability( + 'capname', + \context_system::instance(), + ), + // The display value of this item. + displayvalue: $options[$optionkey], + // The machine-readable value. + value: $optionkey, + // Hints and labels. + edithint: get_string('edithint', 'tool_mytest'), + editlabel: get_string('editlabel', 'tool_mytest'), + ); + $this->set_type_select($options); + } + + /** + * Updates the value in database and returns itself. + * + * Called from inplace_editable callback + * + * @param int $itemid + * @param mixed $newvalue + * @return \self + */ + public static function update($itemid, $newvalue) { + // Clean the new value. + $newvalue = clean_param($newvalue, PARAM_INT); + + // {{ Do some mighty things here}} + + $record = $DB->get_record('xxx', ['id' => 'xxx']); + + // Finally return itself. + return new self($record); + } +} +``` + +
+
+ +
+ View example rendering with PHP +
+ +```php +$renderer = $PAGE->get_renderer('core'); +$inplaceedit = new tool_mytest\local\inplace_edit_text($record); +$params = $inplaceedit->export_for_template($renderer); +echo $OUTPUT->render_from_template('core/inplace_edit', $params); +``` + +
+
+ +
+ View example rendering with JavaScript +
+ +```php title="Render inplace_edit with JavaScript" +$itemid = 153 // Id of the element to be modified inplace. +$renderer = $PAGE->get_renderer('core'); +$inplaceedit = new tool_mytest\local\inplace_edit_text($record); +$params = $inplaceedit->export_for_template($renderer); +``` + +```js title="The params are transferred via webservice and are then processed by JavaScript" +Templates.renderForPromise('core/inplace_edit', params) + .then(({html, js}) => { + Templates.replaceNodeContents('nodeid', html, js); + return true; + }) + .catch((error) => displayException(error)); +``` + +
+
+ +:::note + +In the examples above, `core/inplace_edit` can also be used as a partial in another template. + +::: + ## How does it work `inplace_editable` consists of diff --git a/versioned_docs/version-4.3/apis/subsystems/output/inplace.md b/versioned_docs/version-4.3/apis/subsystems/output/inplace.md index ad6224ef06..ac07b780f4 100644 --- a/versioned_docs/version-4.3/apis/subsystems/output/inplace.md +++ b/versioned_docs/version-4.3/apis/subsystems/output/inplace.md @@ -74,6 +74,68 @@ This was a very simplified example, in the real life you will probably want to: - Use an existing function to update a record (which hopefully also validates input value and triggers events) - Add unit tests and behat tests +
+ View example +
+ +```php title="admin/tool/mytest/classes/local/inplace_edit_text.php" + +class inplace_edit_text extends \core\output\inplace_editable { + /** + * Constructor. + * + * @param object $record + */ + public function __construct($record) { + parent::__construct( + component: 'tool_mytest', + // The item type as managed your plugin. + itemtype: 'mytesttext', + // An ID that relates to this instance of this item type. + itemid: $record->id, + // Whether this user can makes changes. + // Perhaps based upon a capability check. + editable: has_capability( + 'capname', + \context_system::instance(), + ), + // The display value of this item. + displayvalue: format_string($record->name), + // The machine-readable value. + value: $record->name, + // Hints and labels. + edithint: get_string('edithint', 'tool_mytest'), + editlabel: get_string('editlabel', 'tool_mytest'), + ); + $this->set_type_select($answeroptionstemp); + } + + /** + * Updates the value in database and returns itself. + * + * Called from inplace_editable callback + * + * @param int $itemid + * @param mixed $newvalue + * @return \self + */ + public static function update($itemid, $newvalue) { + // Clean the new value. + $newvalue = clean_param($newvalue, PARAM_INT); + + // {{ Do some mighty things here}} + + $record = $DB->get_record('xxx', ['id' => 'xxx']); + + // Finally return itself. + return new self($record); + } +} +``` + +
+
+ ## Toggles and dropdowns You may choose to set the UI for your inplace editable element to be a string value (default), toggle or dropdown. @@ -127,6 +189,118 @@ $tmpl = new \core\output\inplace_editable( $tmpl->set_type_toggle([0, 1]); ``` +
+ View example +
+ +```php title="admin/tool/mytest/classes/local/inplace_edit_select.php" +class inplace_edit_select extends \core\output\inplace_editable { + /** + * Constructor. + * + * @param \stdClass $record + */ + public function __construct($record) { + // Get the options for inplace_edit select box. + // The array needs the format: + // $options = [ + // 'value1' => 'text1', + // 'value2' => 'text2', + // ]; + $options = \tool_mytest\classes\helper::get_options(); + + parent::__construct( + component: 'tool_mytest', + // The item type as managed your plugin. + itemtype: 'mytestselect', + // An ID that relates to this instance of this item type. + itemid: $record->id, + // Whether this user can makes changes. + // Perhaps based upon a capability check. + editable: has_capability( + 'capname', + \context_system::instance(), + ), + // The display value of this item. + displayvalue: $options[$optionkey], + // The machine-readable value. + value: $optionkey, + // Hints and labels. + edithint: get_string('edithint', 'tool_mytest'), + editlabel: get_string('editlabel', 'tool_mytest'), + ); + $this->set_type_select($options); + } + + /** + * Updates the value in database and returns itself. + * + * Called from inplace_editable callback + * + * @param int $itemid + * @param mixed $newvalue + * @return \self + */ + public static function update($itemid, $newvalue) { + // Clean the new value. + $newvalue = clean_param($newvalue, PARAM_INT); + + // {{ Do some mighty things here}} + + $record = $DB->get_record('xxx', ['id' => 'xxx']); + + // Finally return itself. + return new self($record); + } +} +``` + +
+
+ +
+ View example rendering with PHP +
+ +```php +$renderer = $PAGE->get_renderer('core'); +$inplaceedit = new tool_mytest\local\inplace_edit_text($record); +$params = $inplaceedit->export_for_template($renderer); +echo $OUTPUT->render_from_template('core/inplace_edit', $params); +``` + +
+
+ +
+ View example rendering with JavaScript +
+ +```php title="Render inplace_edit with JavaScript" +$itemid = 153 // Id of the element to be modified inplace. +$renderer = $PAGE->get_renderer('core'); +$inplaceedit = new tool_mytest\local\inplace_edit_text($record); +$params = $inplaceedit->export_for_template($renderer); +``` + +```js title="The params are transferred via webservice and are then processed by JavaScript" +Templates.renderForPromise('core/inplace_edit', params) + .then(({html, js}) => { + Templates.replaceNodeContents('nodeid', html, js); + return true; + }) + .catch((error) => displayException(error)); +``` + +
+
+ +:::note + +In the examples above, `core/inplace_edit` can also be used as a partial in another template. + +::: + ## How does it work `inplace_editable` consists of