MDL-77690 core: New activity_header method get_heading_level()

Add a new method for activity_header that determines the heading level
depending on whether the theme displays a heading for the activity
header (usually a h2 heading with the activity name).

E.g. in Boost, the activity name is already being displayed in a
heading. So page headings can be rendered as h2. However, on Classic,
the activity name is being displayed as a h2 heading. So headings need
to be adjusted for the activity pages.

lib/classes/output/activity_header.php

@@ -197,4 +197,22 @@ class activity_header implements \renderable, \templatable {
             'additional_items' => $this->hideoverflow ? '' : $this->additionalnavitems,
         ];
     }
+
+    /**
+     * Get the heading level for a given heading depending on whether the theme's activity header displays a heading
+     * (usually the activity name).
+     *
+     * @param int $defaultlevel The default heading level when the activity header does not display a heading.
+     * @return int
+     */
+    public function get_heading_level(int $defaultlevel = 2): int {
+        // The heading level depends on whether the theme's activity header displays a heading (usually the activity name).
+        $headinglevel = $defaultlevel;
+        if ($this->is_title_allowed() && !empty(trim($this->title))) {
+            // A heading for the activity name is displayed on this page with a heading level 2.
+            // Increment the default level for this heading by 1.
+            $headinglevel++;
+        }
+        return $headinglevel;
+    }
 }

lib/tests/output/activity_header_test.php

@@ -123,4 +123,37 @@ class activity_header_test extends \advanced_testcase {
         $PAGE->activityheader->set_attrs(['unknown' => true]);
         $this->assertDebuggingCalledCount(1, ['Invalid class member variable: unknown']);
     }
+
+    /**
+     * Data provider for {@see test_get_heading_level()}.
+     *
+     * @return array[]
+     */
+    public function get_heading_level_provider(): array {
+        return [
+            'Title not allowed' => [false, '', 2],
+            'Title allowed, no title' => [true, '', 2],
+            'Title allowed, empty string title' => [true, ' ', 2],
+            'Title allowed, non-empty string title' => [true, 'Cool', 3],
+        ];
+    }
+
+    /**
+     * Test the heading level getter
+     *
+     * @dataProvider get_heading_level_provider
+     * @covers ::get_heading_level
+     * @param bool $allowtitle Whether the title is allowed.
+     * @param string $title The activity heading.
+     * @param int $expectedheadinglevel The expected heading level.
+     */
+    public function test_get_heading_level(bool $allowtitle, string $title, int $expectedheadinglevel): void {
+        $activityheaderstub = $this->getMockBuilder(activity_header::class)
+            ->disableOriginalConstructor()
+            ->onlyMethods(['is_title_allowed'])
+            ->getMock();
+        $activityheaderstub->method('is_title_allowed')->willReturn($allowtitle);
+        $activityheaderstub->set_title($title);
+        $this->assertEquals($expectedheadinglevel, $activityheaderstub->get_heading_level());
+    }
 }

lib/upgrade.txt

@@ -5,6 +5,8 @@ information provided here is intended especially for developers.
 * Added new \admin_setting::is_forceable() method to determine whether the setting can be overridden or not. Therefore,
   whether the settings can be overriden or not will depend on the value of implemented \admin_setting::is_forceable() method,
   even if we define the settings in config.php.
+* New \core\output\activity_header::get_heading_level() method to get the heading level for a given heading level depending whether
+  the page displays a heading for the activity (usually a h2 heading containing the activity name).
 
 === 4.1.4 ===
 * Added a new parameter in address_in_subnet to give us the ability to check for 0.0.0.0 or not.