Improvement: Configurable "Documentation for this page" link in footer,

resolves #649.

classes/output/core_renderer.php

@@ -663,4 +663,42 @@ public function standard_end_of_body_html_additionalhtmlfooter() {
         }
         return $output;
     }
+
+    /**
+     * Returns a string containing a link to the user documentation.
+     * Also contains an icon by default. Shown to teachers and admin only.
+     *
+     * @param string $path The page link after doc root and language, no leading slash.
+     * @param string $text The text to be displayed for the link
+     * @param boolean $forcepopup Whether to force a popup regardless of the value of $CFG->doctonewwindow
+     * @param array $attributes htm attributes
+     * @return string
+     */
+    public function doc_link($path, $text = '', $forcepopup = false, array $attributes = []) {
+        global $CFG;
+
+        $footerhelpsetting = get_config('theme_boost_union', 'footerhelp');
+        $icon = null;
+
+        // Set the icon only if the setting is set to one of the 'with icon' variant.
+        if ($footerhelpsetting == THEME_BOOST_UNION_SETTING_FOOTERHELP_SAMEWINDOW ||
+            $footerhelpsetting == THEME_BOOST_UNION_SETTING_FOOTERHELP_NEWWINDOW ) {
+            $icon = $this->pix_icon('book', '', 'moodle', ['class' => 'iconhelp icon-pre']);
+        }
+
+        $attributes['href'] = new moodle_url(get_docs_url($path));
+        $newwindowicon = '';
+        if (!empty($CFG->doctonewwindow) || $forcepopup) {
+            $attributes['target'] = '_blank';
+            $newwindowicon = $this->pix_icon('i/externallink', get_string('opensinnewwindow'), 'moodle',
+                ['class' => 'fa fa-externallink fa-fw']);
+        }
+
+        // Set the target to _blank if the setting is set to one of the 'new tab' variant.
+        if ($footerhelpsetting == THEME_BOOST_UNION_SETTING_FOOTERHELP_NOICON_NEWWINDOW ||
+            $footerhelpsetting == THEME_BOOST_UNION_SETTING_FOOTERHELP_NEWWINDOW ) {
+            $attributes['target'] = '_blank';
+        }
+        return html_writer::tag('a', $icon . $text . $newwindowicon, $attributes);
+    }
 }

lang/en/theme_boost_union.php

@@ -569,6 +569,13 @@
 // ... ... Setting: Suppress 'Documentation for this page' link.
 $string['footersuppresshelpsetting'] = 'Suppress \'Documentation for this page\' link';
 $string['footersuppresshelpsetting_desc'] = 'With this setting, you can entirely suppress the \'Documentation for this page\' link in the footer. This link would otherwise appear if a <a href="{$a->url}">Moodle Docs document root</a> is set.';
+// ... ... Setting: Suppress 'Documentation for this page' link.
+$string['footerhelpsetting'] = '\'Documentation for this page\' link look and behaviour';
+$string['footerhelpsetting_desc'] = 'With this setting, you can choose how the \'Documentation for this page\' link in the footer looks, i.e. whether it is with or without the fa-book icon and whether it opens in the same window or in a new tab. Note there is the <a href="{$a->url}">Open in new window</a> setting, but that one generates a whole new popup browser window.';
+$string['footerhelpsetting_samewindow'] = 'With icon and opening in the same window (unchanged as presented by Moodle core)';
+$string['footerhelpsetting_newwindow'] = 'With icon and opening in a new tab';
+$string['footerhelpsetting_noiconsamewindow'] = 'Without icon and opening in the same window';
+$string['footerhelpsetting_noiconnewwindow'] = 'Without icon and opening in a new tab';
 // ... ... Setting: Suppress 'Services and support' link.
 $string['footersuppressservicessetting'] = 'Suppress \'Services and support\' link';
 $string['footersuppressservicessetting_desc'] = 'With this setting, you can entirely suppress the \'Services and support\' link in the footer. This link would otherwise show the <a href="{$a->url}">Services and support link</a> to administrators.';

lib.php

@@ -117,6 +117,11 @@
 define('THEME_BOOST_UNION_SETTING_ENABLEFOOTER_MOBILE', 'enablefooterbuttonmobile');
 define('THEME_BOOST_UNION_SETTING_ENABLEFOOTER_NONE', 'enablefooterbuttonnone');
 
+define('THEME_BOOST_UNION_SETTING_FOOTERHELP_SAMEWINDOW', 'footerhelp_samewindow');
+define('THEME_BOOST_UNION_SETTING_FOOTERHELP_NEWWINDOW', 'footerhelp_newwindow');
+define('THEME_BOOST_UNION_SETTING_FOOTERHELP_NOICON_SAMEWINDOW', 'footerhelp_noiconsamewindow');
+define('THEME_BOOST_UNION_SETTING_FOOTERHELP_NOICON_NEWWINDOW', 'footerhelp_noiconnewwindow');
+
 define('THEME_BOOST_UNION_SETTING_COURSEOVERVIEW_SHOWCOURSEIMAGES_CARD', 'card');
 define('THEME_BOOST_UNION_SETTING_COURSEOVERVIEW_SHOWCOURSEIMAGES_LIST', 'list');
 define('THEME_BOOST_UNION_SETTING_COURSEOVERVIEW_SHOWCOURSEIMAGES_SUMMARY', 'summary');

settings.php

@@ -1712,6 +1712,24 @@
         $page->hide_if('theme_boost_union/footersuppresshelp', 'theme_boost_union/enablefooterbutton', 'eq',
                 THEME_BOOST_UNION_SETTING_ENABLEFOOTER_NONE);
 
+        // Setting: 'Documentation for this page' link look and behaviour.
+        $name = 'theme_boost_union/footerhelp';
+        $title = get_string('footerhelpsetting', 'theme_boost_union', null, true);
+        $url = new moodle_url('/admin/settings.php?', ['section' => 'documentation']);
+        $description = get_string('footerhelpsetting_desc', 'theme_boost_union', ['url' => $url], true);
+        $footerhelpoptions = [
+            THEME_BOOST_UNION_SETTING_FOOTERHELP_SAMEWINDOW =>
+                get_string('footerhelpsetting_samewindow', 'theme_boost_union'),
+            THEME_BOOST_UNION_SETTING_FOOTERHELP_NEWWINDOW =>
+                get_string('footerhelpsetting_newwindow', 'theme_boost_union'),
+            THEME_BOOST_UNION_SETTING_FOOTERHELP_NOICON_SAMEWINDOW =>
+                get_string('footerhelpsetting_noiconsamewindow', 'theme_boost_union'),
+            THEME_BOOST_UNION_SETTING_FOOTERHELP_NOICON_NEWWINDOW =>
+                get_string('footerhelpsetting_noiconnewwindow', 'theme_boost_union'), ];
+        $setting = new admin_setting_configselect($name, $title, $description, THEME_BOOST_UNION_SETTING_FOOTERHELP_SAMEWINDOW,
+            $footerhelpoptions);
+        $tab->add($setting);
+
         // Setting: Suppress 'Services and support' link.
         $name = 'theme_boost_union/footersuppressservices';
         $title = get_string('footersuppressservicessetting', 'theme_boost_union', null, true);

tests/behat/theme_boost_union_contentsettings_footer.feature

@@ -300,3 +300,23 @@ Feature: Configuring the theme_boost_union plugin for the "Footer" tab on the "C
       | value | shouldornot |
       | no    | should      |
       | yes   | should not  |
+
+  @javascript
+  Scenario Outline: Setting: Footer - 'Documentation for this page' link look and behaviour
+    Given the following config values are set as admin:
+      | docroot | https://docs.moodle.org |
+    And the following config values are set as admin:
+      | config     | value   | plugin            |
+      | footerhelp | <value> | theme_boost_union |
+    And I log in as "admin"
+    And I am on "Course 1" course homepage
+    And I click on ".btn-footer-popover" "css_element" in the "#page-footer" "css_element"
+    Then ".footer-support-link a i.icon.fa-book" "css_element" <shouldornoticon> exist in the ".footer .popover-body" "css_element"
+    And the "target" attribute of ".footer .popover-body .footer-support-link a[href*='topic']" "css_element" <shouldornotblank> be set
+
+    Examples:
+      | value                       | shouldornotblank | shouldornoticon |
+      | footerhelp_samewindow       | should not       | should          |
+      | footerhelp_newwindow        | should           | should          |
+      | footerhelp_noiconsamewindow | should not       | should not      |
+      | footerhelp_noiconnewwindow  | should           | should not      |