New: Added custom icon support (fixes #19)

cgkineo · Jul 23, 2024 · 9840896 · 9840896
2 parents 2f32837 + 1cf6ba2
commit 9840896
Show file tree

Hide file tree

Showing 7 changed files with 64 additions and 58 deletions.
diff --git a/README.md b/README.md
@@ -9,87 +9,72 @@
 - Changing the text of the buttons
 - Redirecting the button to a specific location (e.g. an introductory page)
 
-## Attributes
+### Attributes
 
 All configuration options must be added and amended, where appropriate, for all JSON files.
 
-### *config.json*
+*config.json*
+
 The following attributes are set within *config.json*.
 
-### **\_homeButton** (object):
-The Home Button object contains the following settings:
+**\_homeButton** (object): The Home Button object contains the following settings:
+
+>**\_isEnabled** (boolean): Controls whether the Home Button extension is enabled.
 
-#### **\_isEnabled** (boolean):
-Controls whether the Home Button extension is enabled
+*course.json*
 
-### *course.json*
 The following attributes are set within *course.json*. These are used to set some default settings and the navigation order:
 
-### **\_homeButton** (object):
-The Home Button object contains the following settings:
+**\_homeButton** (object): The Home Button object contains the following settings:
+
+>**\_navOrder** (number): The order that the button appears in the navigation.
+
+>**\_showLabel** (boolean): Controls whether the button should use a navigation label or just an icon.
 
-#### **_navOrder** (number):
-The order that the button appears in the navigation
+>**alt** (string): The button's `aria-label` text. Used to override global setting.
 
-#### **_showLabel** (boolean):
-Controls whether the button should use a navigation label or just an icon
+>**navLabel** (string): The button label text as it appears in the navigation.
 
-#### **alt** (string):
-The button's `aria-label` text. Used to override global setting
+>**\_navTooltip** (object): The Navigation Tooltip object contains the following settings:
 
-#### **navLabel** (string):
-The button label text as it appears in the navigation
+>>**\_isEnabled** (boolean): Controls whether the navigation tooltip is enabled.
 
-#### **_navTooltip** (object):
-The Navigation Tooltip object contains the following settings:
+>>**text** (string): The text of the tooltip. Used to override global setting.
 
-##### **\_isEnabled** (boolean):
-Controls whether the navigation tooltip is enabled
+*course.json* and *contentObjects.json*
 
-##### **text** (string):
-The text of the tooltip. Used to override global setting
+The following attributes are set within *course.json* and / or *contentObjects.json*. These are used to *override* global settings and customize the button for a specific page or menu.
 
-### *course.json / contentObjects.json*
-The following attributes are set within *course.json* and/or *contentObjects.json*. These are used to *override* global settings and customize the button for a specific page or menu.
+**\_homeButton** (object): The Home Button object contains the following settings:
 
-### **\_homeButton** (object):
-The Home Button object contains the following settings:
+>**\_isEnabled** (boolean): Controls whether the Home Button extension is enabled.
 
-#### **\_isEnabled** (boolean):
-Controls whether the Home Button extension is enabled
+>**\_hideHomeButton** (boolean): Controls whether the home button is hidden or not.
 
-#### **\_hideHomeButton** (boolean):
-Controls whether the home button is hidden or not
+>**\_hideBackButton** (boolean): Controls whether the back button is hidden or not. Applies to *contentObjects.json* only.
 
-#### **\_hideBackButton** (boolean):
-Controls whether the back button is hidden or not. Applies to *contentObjects.json* only.
+>**\_redirectToId** (string): The page ID that the home button should redirect the user to. Use when overriding standard behaviour such as redirecting to an introductory page from the menu.
 
-#### **\_redirectToId** (string):
-The page ID that the home button should redirect the user to. Use when overriding standard behaviour such as redirecting to an introductory page from the menu.
+>**\_iconClasses** (string): CSS class name to override the default home button icon application. Default application for the home button is `icon-home` on all pages with `icon-controls-left` on the menu. If an override is applied to *course.json* the override will apply to the menu and all pages. If an override is applied to *contentObjects.json* the override will only apply specifically to that page.
 
-#### **alt** (string):
-The button's `aria-label` text. Used to override global setting
+>**alt** (string): The button's `aria-label` text. Used to override global setting.
 
-#### **navLabel** (string):
-The button label text as it appears in the navigation. Used to override global setting
+>**navLabel** (string): The button label text as it appears in the navigation. Used to override global setting.
 
-#### **_navTooltip** (object):
-The Navigation Tooltip object contains the following settings:
+>**_navTooltip** (object): The Navigation Tooltip object contains the following settings:
 
-##### **\_isEnabled** (boolean):
-Controls whether the navigation tooltip is enabled. Used to override global setting
+>>**\_isEnabled** (boolean): Controls whether the navigation tooltip is enabled. Used to override global setting.
 
-##### **text** (string):
-The text of the tooltip. Used to override global setting
+>>**text** (string): The text of the tooltip. Used to override global setting.
 
 ## Limitations
 
 No known limitations.
 
 ----------------------------
 
-**Framework versions:**  5.30.3+<br>
-**Author / maintainer:**  CGKineo<br>
+**Framework versions:** 5.30.3+<br>
+**Author / maintainer:** CGKineo<br>
 **Accessibility support:** WAI AA<br>
 **RTL support:** Yes<br>
 **Cross-platform coverage:** Chrome, Chrome for Android, Firefox (ESR + latest version), Edge, IE11, Safari 12+13 for macOS/iOS/iPadOS, Opera<br>
diff --git a/example.json b/example.json
@@ -10,6 +10,7 @@
   "_homeButton": {
     "_navOrder": -1,
     "_showLabel": true,
+    "alt": "",
     "navLabel": "Home",
     "_navTooltip": {
       "_isEnabled": false,
@@ -24,6 +25,8 @@
   "_hideHomeButton": false,
   "_comment": "Amend _redirectToId to match the ID of the start / landing page",
   "_redirectToId": "",
+  "_iconClasses": "",
+  "alt": "",
   "_comment": "Option to override navigation button label and tooltip",
   "navLabel": "Introduction",
   "_navTooltip": {
@@ -39,6 +42,8 @@
   "_hideBackButton": true,
   "_comment": "Amend _redirectToId to match the ID of the start / landing page",
   "_redirectToId": "",
+  "_iconClasses": "",
+  "alt": "",
   "_comment": "Option to override navigation button label and tooltip",
   "navLabel": "Introduction",
   "_navTooltip": {

diff --git a/js/adapt-homeButton.js b/js/adapt-homeButton.js
@@ -65,6 +65,7 @@ class HomeButton extends Backbone.Controller {
     const currentModelConfig = this.currentModelConfig;
     const {
       _navOrder = -1,
+      _iconClasses,
       alt,
       _showLabel = true,
       navLabel = '',
@@ -75,6 +76,8 @@ class HomeButton extends Backbone.Controller {
       _order: _navOrder,
       _showLabel,
       _classes: 'btn-icon nav__btn nav__homebutton-btn',
+      courseConfig: HomeButton.courseConfig,
+      _iconClasses,
       _role: 'link',
       ariaLabel: alt || navLabel,
       text: navLabel,

diff --git a/less/homeButton.less b/less/homeButton.less
@@ -3,13 +3,4 @@
   .hide-nav-home-btn & {
     .u-display-none;
   }
-
-  // Change the home button icon to use the back arrow on the menu
-  .location-menu & .icon {
-    .icon-controls-small-left;
-  }
-
-  .location-page & .icon {
-    .icon-home;
-  }
 }
diff --git a/schema/contentobject.schema.json b/schema/contentobject.schema.json
@@ -34,6 +34,12 @@
               "description": "Enter the Friendly id of the page that the home button should direct the user to (e.g. a splash page)",
               "default": ""
             },
+            "_iconClasses": {
+              "type": "string",
+              "title": "Icon class",
+              "description": "CSS class name to override the default home button icon application. If an override is applied at this level the override will only apply specifically to this page.",
+              "default": ""
+            },
             "alt": {
               "type": "string",
               "title": "Home button alt text",

diff --git a/schema/course.schema.json b/schema/course.schema.json
@@ -87,6 +87,12 @@
               "description": "Enter the Friendly id of the page that the home button should direct the user to (e.g. a splash page)",
               "default": ""
             },
+            "_iconClasses": {
+              "type": "string",
+              "title": "Icon class",
+              "description": "CSS class name to override the default home button icon application. If an override is applied at this level the override will apply to the menu and all pages.",
+              "default": ""
+            },
             "alt": {
               "type": "string",
               "title": "Home button alt text",

diff --git a/templates/HomeNavigationButton.jsx b/templates/HomeNavigationButton.jsx
@@ -1,17 +1,27 @@
 import React from 'react';
+import location from 'core/js/location';
 import { classes, compile } from 'core/js/reactHelpers';
 
 export default function HomeNavigationButton(props) {
   const {
     text,
-    _iconClasses
+    _iconClasses,
+    courseConfig
   } = props;
+
+  const currentIconClass = _iconClasses;
+  const courseIconClass = courseConfig?._iconClasses;
+  const currentLocation = location._currentLocation;
+  const defaultClass = (currentLocation !== 'course') ? 'icon-home' : 'icon-controls-small-left';
+
+  const iconClass = (currentIconClass || courseIconClass || defaultClass);
+
   return (
     <>
       <span
         className={classes([
           'icon',
-          _iconClasses
+          iconClass
         ])}
         aria-hidden="true"
       />