From f3b0bb1896770e29f69fd4d968f2faae5deb310b Mon Sep 17 00:00:00 2001
From: Jun Pataleta <jun@moodle.com>
Date: Wed, 28 Jan 2026 19:41:31 +0800
Subject: [PATCH] MDL-87694 core: `headinglevel` display option for
 $OUTPUT->confirm()

`\core\output\core_renderer::confirm()`'s `$displayoptions` parameter
now also accepts a `headinglevel` option that developers can use to
specify the heading level of the confirmation's heading. If not
specified, the confirmation heading will be rendered in an `h4` tag.
---
 .upgradenotes/MDL-87694-2026012811392962.yml |  9 +++++
 lib/classes/output/core_renderer.php         | 36 +++++++++++++-------
 2 files changed, 33 insertions(+), 12 deletions(-)
 create mode 100644 .upgradenotes/MDL-87694-2026012811392962.yml

diff --git a/.upgradenotes/MDL-87694-2026012811392962.yml b/.upgradenotes/MDL-87694-2026012811392962.yml
new file mode 100644
index 00000000000..fec1da92b9d
--- /dev/null
+++ b/.upgradenotes/MDL-87694-2026012811392962.yml
@@ -0,0 +1,9 @@
+issueNumber: MDL-87694
+notes:
+  core:
+    - message: >-
+        `\core\output\core_renderer::confirm()`'s `$displayoptions` parameter
+        now also accepts a `headinglevel` option that developers can use to
+        specify the heading level of the confirmation's heading. If not
+        specified, the confirmation heading will be rendered in an `h4` tag.
+      type: changed
diff --git a/lib/classes/output/core_renderer.php b/lib/classes/output/core_renderer.php
index 2e643ba45cc..b2c93da8646 100644
--- a/lib/classes/output/core_renderer.php
+++ b/lib/classes/output/core_renderer.php
@@ -1697,23 +1697,35 @@ class core_renderer extends renderer_base {
         return $this->action_link($url, $text . $icon, $action, $attributes);
     }
 
-   /**
-    * Print a message along with button choices for Continue/Cancel
-    *
-    * If a string or moodle_url is given instead of a single_button, method defaults to post.
-    *
-    * @param string $message The question to ask the user
-    * @param single_button|moodle_url|string $continue The single_button component representing the Continue answer. Can also be a moodle_url or string URL
-    * @param single_button|moodle_url|string $cancel The single_button component representing the Cancel answer. Can also be a moodle_url or string URL
-    * @param array $displayoptions optional extra display options
-    * @return string HTML fragment
-    */
+    /**
+     * Print a message along with button choices for Continue/Cancel
+     *
+     * If a string or moodle_url is given instead of a single_button, method defaults to post.
+     *
+     * @param string $message The question to ask the user
+     * @param single_button|moodle_url|string $continue The single_button component representing the Continue answer.
+     *      Can also be a moodle_url or string URL
+     * @param single_button|moodle_url|string $cancel The single_button component representing the Cancel answer.
+     *      Can also be a moodle_url or string URL
+     * @param array $displayoptions Display options (Optional).
+     *      Possible options:
+     *      - confirmtitle: The title to display above the message
+     *      - continuestr: The label to use for the continue button (if $continue is not a single_button)
+     *      - cancelstr: The label to use for the cancel button (if $cancel is not a single_button)
+     *      - headinglevel: The heading level to use for the title (1-6). Default is 4.
+     *      - type: The button type to use for the continue button (if $continue is not a single_button). Default is BUTTON_PRIMARY.
+     * @return string HTML fragment
+     */
     public function confirm($message, $continue, $cancel, array $displayoptions = []) {
 
         // Check existing displayoptions.
         $displayoptions['confirmtitle'] = $displayoptions['confirmtitle'] ?? get_string('confirm');
         $displayoptions['continuestr'] = $displayoptions['continuestr'] ?? get_string('continue');
         $displayoptions['cancelstr'] = $displayoptions['cancelstr'] ?? get_string('cancel');
+        $headinglevel = $displayoptions['headinglevel'] ?? 4;
+        if ($headinglevel < 1 || $headinglevel > 6) {
+            throw new coding_exception('The headinglevel option to $OUTPUT->confirm() must be between 1 and 6.');
+        }
 
         if ($continue instanceof single_button) {
             // Continue button should be primary if set to secondary type as it is the fefault.
@@ -1758,7 +1770,7 @@ class core_renderer extends renderer_base {
         $output = $this->box_start('generalbox modal modal-dialog modal-in-page show', 'notice', $attributes);
         $output .= $this->box_start('modal-content', 'modal-content');
         $output .= $this->box_start('modal-header px-3', 'modal-header');
-        $output .= html_writer::tag('h4', $displayoptions['confirmtitle']);
+        $output .= html_writer::tag('h' . $headinglevel, $displayoptions['confirmtitle'], ['class' => 'h4']);
         $output .= $this->box_end();
         $attributes = [
             'role' => 'alert',