feat: render qpy:rich-text-editor and handle their uploads

Closes: #218

Author: MHajoha

amd/build/view_question.min.js

@@ -63,7 +63,9 @@ function validateInput(element) {
  * @param {boolean} showSpecificFeedback
  * @param {boolean} showRightAnswer
  * @param {boolean} showCorrectness
- * @param {string} responseId
+ * @param {string} responseId Id of the hidden input containing the JSON-encoded main response.
+ * @param {string} editorsId Id of the hidden input containing the JSON-encoded WYSIWYG editors data.
+ * @param {string[]} editorNames Names of the WYSIWYG editors.
  * @param {string[]} roles QPy role names that the user has.
  * @param {Object.<string, any>} data Dynamic data.
  * @param {Number} environmentVersion
@@ -75,6 +77,8 @@ export async function init(
     showRightAnswer,
     showCorrectness,
     responseId,
+    editorsId,
+    editorNames,
     roles,
     data,
     environmentVersion,
@@ -102,10 +106,17 @@ export async function init(
 
         // Modify a field in the main form in order to tell the Quiz's autosaver that the user changed an answer.
         const responseElement = parent.document.getElementById(responseId);
-        if (responseElement) {
+        const editorsElement = parent.document.getElementById(editorsId);
+        if (responseElement || editorsElement) {
             // We throttle here, as `JSON.stringify` might affect the performance.
             form.addEventListener("change", throttle(() => {
-                responseElement.value = createJsonFromFormData(form);
+                const [responseData, editorsData] = collectFormData(form, editorNames);
+                if (responseElement) {
+                    responseElement.value = responseData;
+                }
+                if (editorsElement) {
+                    editorsElement.value = editorsData;
+                }
             }, 250));
         }
 
@@ -403,29 +414,73 @@ class Attempt {
     }
 }
 
+function buildDraftFileUrlRegex() {
+    const wwwrootWithoutScheme = M.cfg.wwwroot.replace(/^https?:\/\//, "");
+
+    return new RegExp(
+        // Phpcs:disable -- phpcs is massively confused by this.
+        String.raw`https?://${wwwrootWithoutScheme}/draftfile\.php/(?<contextid>\d+)`
+        + String.raw`/user/draft/(?<itemid>\d+)/(?<filename>[^\'\",&<>|\`\s:\\\\]+)`
+        // Phpcs:enable
+    )
+}
+
 /**
  * Creates JSON from the FormData of the given form.
  *
  * @param {HTMLFormElement} form
- * @returns {string}
+ * @param {string[]} editorNames
+ * @returns {[string, string]}
  */
-function createJsonFromFormData(form) {
+function collectFormData(form, editorNames) {
     const iframeFormData = new FormData(form);
-    const iframeObject = Object.fromEntries(iframeFormData);
+
+    const editorData = {};
+    for (const name of editorNames) {
+        // TODO: Turn draftfile.php-URLs into @@PLUGINFILE@@-URLs.
+
+        const textKey = `${name}[text]`;
+        const formatKey = `${name}[format]`;
+        const itemidKey = `${name}[itemid]`;
+
+        const text = iframeFormData.get(textKey);
+        if (text === null) {
+            continue;
+        }
+
+        // TODO: Handle content pasted from other editors, where the draft item id would be different. We'd probably
+        // need to pass the encountered foreign files somewhere and copy them to our area in qbehaviour_questionpy.
+        const replacedText = text.replaceAll(buildDraftFileUrlRegex(), "@@PLUGINFILE@@/$<filename>");
+
+        editorData[name] = {text: replacedText};
+        iframeFormData.delete(textKey);
+
+        const format = iframeFormData.get(formatKey);
+        if (format !== null) {
+            editorData[name].format = format;
+            iframeFormData.delete(formatKey);
+        }
+
+        // The itemid is added by qpy_rich_text_editor to the list that gets sent from outside the iframe.
+        // No need to duplicate it here.
+        iframeFormData.delete(itemidKey);
+    }
+
+    const responseObject = Object.fromEntries(iframeFormData);
     for (const name of iframeFormData.keys()) {
         const values = iframeFormData.getAll(name);
         if (values.length > 1) {
-            iframeObject[name] = values;
+            responseObject[name] = values;
         }
     }
 
-    if (iframeObject.data) {
-        iframeObject.data = JSON.parse(iframeObject.data);
+    if (responseObject.data) {
+        responseObject.data = JSON.parse(responseObject.data);
     } else {
         window.console.warn("The form data field 'data' is missing in the question iframe form.");
     }
 
-    return JSON.stringify(iframeObject);
+    return [JSON.stringify(responseObject), JSON.stringify(editorData)];
 }
 
 /**
@@ -435,8 +490,10 @@ function createJsonFromFormData(form) {
  *
  * @param {string} iframeId - The ID of the question's iframe.
  * @param {string} responseFieldName - The complete field name for the JSON-encoded iframe form data.
+ * @param {string} editorsFieldName - The complete field name for the JSON-encoded WYSIWYG editors data.
+ * @param {string[]} editorNames - The input names that are WYSIWYG editors.
  */
-export function addIframeFormDataOnSubmit(iframeId, responseFieldName) {
+export function addIframeFormDataOnSubmit(iframeId, responseFieldName, editorsFieldName, editorNames) {
     const iframe = window.document.getElementById(iframeId);
     if (iframe === null) {
         window.console.error(`Could not find question iframe ${iframeId}. Cannot save answers.`);
@@ -450,9 +507,11 @@ export function addIframeFormDataOnSubmit(iframeId, responseFieldName) {
             window.console.error("Could not find form in question iframe " + iframeId);
             return;
         }
+
         // Since we are throttling the updating process of the response element on a change, it might happen that the
         // value is outdated - this is why we get the data again.
-        const jsonFormData = createJsonFromFormData(iframeForm);
-        event.formData.set(responseFieldName, jsonFormData);
+        const [responseData, editorsData] = collectFormData(iframeForm, editorNames);
+        event.formData.set(responseFieldName, responseData);
+        event.formData.set(editorsFieldName, editorsData);
     });
 }

amd/build/view_question.min.js.map

@@ -47,7 +47,8 @@ class constants {
     public const FILEAREA_RESPONSE_FILES = 'response_files';
     /** @var string */
     public const QT_VAR_RESPONSE_FILES = 'files';
-
+    /** @var string */
+    public const QT_VAR_EDITORS = 'editors';
 
     /** @var string */
     public const FILEAREA_OPTIONS = 'options';

amd/src/view_question.js

@@ -134,18 +134,20 @@ public function start_attempt(string $questionstate, int $variant, ?array $attri
      * @param string $attemptstate the attempt state previously returned from {@see start_attempt()}
      * @param string|null $scoringstate the last scoring state if this attempt has already been scored
      * @param object|null $response data currently entered by the student
+     * @param array|null $editors
      * @return attempt the attempt's metadata. The state is not returned since it never changes.
      * @throws GuzzleException
-     * @throws request_error
      * @throws moodle_exception
+     * @throws request_error
      */
     public function view_attempt(string $questionstate, ?array $attributes, string $attemptstate, ?string $scoringstate = null,
-                                 ?object $response = null): attempt {
+                                 ?object $response = null, ?array $editors = null): attempt {
         $options['multipart'] = $this->transform_to_multipart(
             [
                 'attempt_state' => $attemptstate,
                 'scoring_state' => $scoringstate,
                 'response' => $response,
+                'editors' => $editors === null ? null : (object) $editors,
                 'context' => $this->get_context_id(),
                 'lms_provided_attributes' => $attributes,
             ],
@@ -163,18 +165,20 @@ public function view_attempt(string $questionstate, ?array $attributes, string $
      * @param string $attemptstate the attempt state previously returned from {@see start_attempt()}
      * @param string|null $scoringstate the last scoring state if this attempt had been scored before
      * @param object $response data submitted by the student
+     * @param wysiwyg_editor_data[] $editors
      * @return attempt_scored the attempt's metadata. The state is not returned since it never changes.
      * @throws GuzzleException
-     * @throws request_error
      * @throws moodle_exception
+     * @throws request_error
      */
     public function score_attempt(string $questionstate, ?array $attributes, string $attemptstate, ?string $scoringstate,
-                                  object $response): attempt_scored {
+                                  object $response, array $editors): attempt_scored {
         $options['multipart'] = $this->transform_to_multipart(
             [
                 'attempt_state' => $attemptstate,
                 'scoring_state' => $scoringstate,
                 'response' => $response,
+                'editors' => (object) $editors,
                 'generate_hint' => false,
                 'context' => $this->get_context_id(),
                 'lms_provided_attributes' => $attributes,

classes/constants.php

@@ -0,0 +1,57 @@
+<?php
+// This file is part of the QuestionPy Moodle plugin - https://questionpy.org
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace qtype_questionpy\local\attempt_ui;
+
+
+use core\exception\coding_exception;
+use DOMElement;
+use DOMNode;
+use file_exception;
+use moodle_exception;
+use question_attempt;
+use stored_file_creation_exception;
+
+/**
+ * Represents a `<qpy:X/>` element in the question UI XML.
+ *
+ * @package    qtype_questionpy
+ * @author     Maximilian Haye
+ * @copyright  2025 TU Berlin, innoCampus {@link https://www.questionpy.org}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+interface custom_xhtml_element {
+    /**
+     * Parses the given DOMElement if possible.
+     *
+     * @param DOMElement $element
+     * @return static|null
+     */
+    public static function from_element(DOMElement $element): ?static;
+
+    /**
+     * Renders this element to a DOMNode.
+     *
+     * @param question_attempt $qa
+     * @param question_ui_renderer $renderer
+     * @return DOMNode
+     * @throws coding_exception
+     * @throws file_exception
+     * @throws moodle_exception
+     * @throws stored_file_creation_exception
+     */
+    public function render(question_attempt $qa, question_ui_renderer $renderer): DOMNode;
+}

classes/local/api/package_api.php

@@ -39,7 +39,7 @@
  * @copyright  2025 TU Berlin, innoCampus {@link https://www.questionpy.org}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
-class qpy_file_upload {
+class qpy_file_upload implements custom_xhtml_element {
     /**
      * Trivial private constructor. Use {@see from_element()}.
      * @param DOMElement $element
@@ -81,12 +81,12 @@ public function get_limits_in(context $context): validatable_upload_limits {
     }
 
     /**
-     * Creates a new {@see qpy_file_upload} from a given {@see DOMElement}.
+     * Parses the given DOMElement if possible.
      *
      * @param DOMElement $element
-     * @return self|null
+     * @return static|null
      */
-    public static function from_element(DOMElement $element): ?self {
+    public static function from_element(DOMElement $element): ?static {
         $name = $element->getAttribute('name');
         if (!$name) {
             debugging('qpy:file-upload without a name');
@@ -102,10 +102,6 @@ public static function from_element(DOMElement $element): ?self {
      * @param question_attempt $qa
      * @param question_ui_renderer $renderer
      * @return DOMNode
-     * @throws coding_exception
-     * @throws file_exception
-     * @throws moodle_exception
-     * @throws stored_file_creation_exception
      */
     public function render(question_attempt $qa, question_ui_renderer $renderer): DOMNode {
         if ($renderer->options->readonly) {