MDL-78806 core: Append site name on page title

moodle · Sep 9, 2023 · 4a96611 · 4a96611
1 parent 156a8bd
commit 4a96611
Show file tree

Hide file tree

Showing 2 changed files with 98 additions and 5 deletions.
diff --git a/lib/pagelib.php b/lib/pagelib.php
@@ -124,6 +124,11 @@ class moodle_page {
      */
     const STATE_DONE = 3;
 
+    /**
+     * The separator used for separating page title elements.
+     */
+    const TITLE_SEPARATOR = ' | ';
+
     /**
      * @var int The current state of the page. The state a page is within
      * determines what actions are possible for it.
@@ -1367,14 +1372,47 @@ public function add_body_classes($classes) {
 
     /**
      * Sets the title for the page.
+     *
      * This is normally used within the title tag in the head of the page.
      *
+     * Some tips for providing a meaningful page title:
+     * - The page title must be accurate and informative.
+     * - If the page causes a change of context (e.g. a search functionality), it should describe the result or change of context
+     *   to the user.
+     * - It should be concise.
+     * - If possible, it should uniquely identify the page.
+     * - The most identifying information should come first. (e.g. Submit assignment | Assignment | Moodle)
+     *
+     * For more information, see
+     * {@link https://www.w3.org/WAI/WCAG21/Understanding/page-titled Understanding Success Criterion 2.4.2: Page Titled}
+     *
      * @param string $title the title that should go in the <head> section of the HTML of this page.
+     * @param bool $appendsitename Appends site name at the end of the given title. It is encouraged to append the site name as this
+     *                              especially helps with accessibility. If it's necessary to override this, please keep in mind
+     *                              to ensure that the title provides a concise summary of the page being displayed.
      */
-    public function set_title($title) {
+    public function set_title($title, bool $appendsitename = true) {
+        global $CFG;
+
         $title = format_string($title);
         $title = strip_tags($title);
         $title = str_replace('"', '&quot;', $title);
+
+        if ($appendsitename) {
+            // Append the site name at the end of the page title.
+            $sitenamedisplay = 'shortname';
+            if (!empty($CFG->sitenameintitle)) {
+                $sitenamedisplay = $CFG->sitenameintitle;
+            }
+            $site = get_site();
+            if (empty(trim($site->{$sitenamedisplay}))) {
+                // If for some reason the site name is not yet set, fall back to 'Moodle'.
+                $title .= self::TITLE_SEPARATOR . 'Moodle';
+            } else {
+                $title .= self::TITLE_SEPARATOR . format_string($site->{$sitenamedisplay});
+            }
+        }
+
         $this->_title = $title;
     }
 

diff --git a/lib/tests/moodle_page_test.php b/lib/tests/moodle_page_test.php
@@ -325,11 +325,66 @@ public function test_set_heading() {
         $this->assertSame('a heading <a href="#">edit</a><p></p>', $this->testpage->heading);
     }
 
-    public function test_set_title() {
-        // Exercise SUT.
-        $this->testpage->set_title('a title');
+    /**
+     * Data provider for {@see test_set_title}.
+     *
+     * @return array
+     */
+    public function set_title_provider(): array {
+        return [
+            'Do not append the site name' => [
+                'shortname', false, '', false
+            ],
+            'Site not yet installed not configured defaults to site shortname' => [
+                null, true, 'shortname'
+            ],
+            '$CFG->sitenameintitle not configured defaults to site shortname' => [
+                null, true, 'shortname'
+            ],
+            '$CFG->sitenameintitle set to shortname' => [
+                'shortname', true, 'shortname'
+            ],
+            '$CFG->sitenameintitle set to fullname' => [
+                'fullname', true, 'fullname'
+            ],
+        ];
+    }
+
+    /**
+     * Test for set_title
+     *
+     * @dataProvider set_title_provider
+     * @param string|null $config The config value for $CFG->sitenameintitle.
+     * @param bool $appendsitename The $appendsitename parameter
+     * @param string $expected The expected site name to be appended to the title.
+     * @param bool $sitenameset To simulate the absence of the site name being set in the site.
+     * @return void
+     * @covers ::set_title
+     */
+    public function test_set_title(?string $config, bool $appendsitename, string $expected, bool $sitenameset = true): void {
+        global $CFG, $SITE;
+
+        if ($config !== null) {
+            $CFG->sitenameintitle = $config;
+        }
+
+        $title = "A title";
+        if ($appendsitename) {
+            if ($sitenameset) {
+                $expectedtitle = $title . moodle_page::TITLE_SEPARATOR . $SITE->{$expected};
+            } else {
+                // Simulate site fullname and shortname being empty for any reason.
+                $SITE->fullname = null;
+                $SITE->shortname = null;
+                $expectedtitle = $title . moodle_page::TITLE_SEPARATOR . 'Moodle';
+            }
+        } else {
+            $expectedtitle = $title;
+        }
+
+        $this->testpage->set_title($title, $appendsitename);
         // Validated.
-        $this->assertSame('a title', $this->testpage->title);
+        $this->assertSame($expectedtitle, $this->testpage->title);
     }
 
     public function test_default_pagelayout() {