MDL-84142 core_enrol: new template for self enrolment widgets

.upgradenotes/MDL-84142-2025021801283101.yml

@@ -0,0 +1,9 @@
+issueNumber: MDL-84142
+notes:
+  core_enrol:
+    - message: >-
+        Plugins implementing enrol_page_hook() method are encouraged to use the
+        renderable \core_enrol\output\enrol_page to produce HTML for the
+        enrolment page. Forms should be displayed in a modal dialogue. See
+        enrol_self plugin as an example.
+      type: improved

enrol/classes/output/enrol_page.php

@@ -0,0 +1,70 @@
+<?php
+// This file is part of Moodle - http://moodle.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/>.
+
+declare(strict_types=1);
+
+namespace core_enrol\output;
+
+use core\output\named_templatable;
+use core\output\renderable;
+use core\output\single_button;
+
+/**
+ * Allows to render a widget provided by enrol_plugin::enrol_page_hook()
+ *
+ * @package    core_enrol
+ * @copyright  Marina Glancy
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class enrol_page implements named_templatable, renderable {
+
+    /**
+     * Constructor
+     *
+     * @param \stdClass $instance
+     * @param string|null $header
+     * @param string|null $body
+     * @param array $buttons
+     */
+    public function __construct(
+        /** @var \stdClass */
+        protected \stdClass $instance,
+        /** @var string|null */
+        protected ?string $header = null,
+        /** @var string|null */
+        protected ?string $body = null,
+        /** @var single_button[] */
+        protected array $buttons = []
+        ) {
+    }
+
+    #[\Override]
+    public function export_for_template(\core\output\renderer_base $output) {
+        return [
+            'enrol' => $this->instance->enrol,
+            'instanceid' => $this->instance->id,
+            'header' => $this->header,
+            'body' => $this->body,
+            'buttons' => array_map(fn($b) => $b->export_for_template($output), $this->buttons),
+            'hasbuttons' => !empty($this->buttons),
+        ];
+    }
+
+    #[\Override]
+    public function get_template_name(\core\output\renderer_base $renderer): string {
+        return 'core_enrol/enrol_page';
+    }
+}

enrol/templates/enrol_page.mustache

@@ -0,0 +1,52 @@
+{{!
+    This file is part of Moodle - http://moodle.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/>.
+}}
+{{!
+    @template core_enrol/enrol_page
+
+    Recommended template for displaying the enrolment plugin call-to-action on the enrol/index.php page
+
+    Usually to be used with the \core_enrol\output\enrol_page and returned from the enrol_plugin::enrol_page_hook()
+
+    Example context (json):
+    {
+        "enrol": "self",
+        "instanceid": 1,
+        "header": "Self-enrolment",
+        "body": "You can enrol yourself in this course.",
+        "hasbuttons": true,
+        "buttons": [{
+            "method" : "get",
+            "id": "buttonid-123",
+            "type": "primary",
+            "url" : "#",
+            "label" : "Enrol me"
+        }]
+    }
+}}
+<div class="box generalbox mb-3 enrol-instance" data-enrol="{{enrol}}" data-instanceid="{{instanceid}}">
+    <div class="card">
+        {{#header}}<div class="card-header"><h3 class="mb-0">{{{header}}}</h3></div>{{/header}}
+        <div class="card-body">{{{body}}}</div>
+        {{#hasbuttons}}
+        <div class="card-footer">
+            {{#buttons}}
+                {{> core/single_button }}
+            {{/buttons}}
+        </div>
+        {{/hasbuttons}}
+    </div>
+</div>

lib/enrollib.php

@@ -2807,11 +2807,15 @@ abstract class enrol_plugin {
     }
 
     /**
-     * Creates course enrol form, checks if form submitted
-     * and enrols user if necessary. It can also redirect.
+     * Creates a widget to display on the course enrolment page. It can also redirect.
+     *
+     * It is recommended that all plugins use the same template for the consistent output. Example:
+     *
+     *     $obj = new \core_enrol\output\enrol_page($instance, ...);
+     *     return $OUTPUT->render($obj);
      *
      * @param stdClass $instance
-     * @return string html text, usually a form in a text box
+     * @return string|null html to display on the enrolment page
      */
     public function enrol_page_hook(stdClass $instance) {
         return null;