Fix: Update schemas and documentation (fixes #25)

README.md

@@ -1,44 +1,94 @@
 # adapt-homeButton
 
-Add home button to course navigation. Allows hide or redirect of home button. Allows hide of back button.
+**Home Button** is an extension that adds more control to the standard home and back buttons.
 
-## Settings
+## Settings Overview
 
-All configuration options must be added and amended, where appropriate, for all json files.
+**Home Button** can be configured based on the specific location where it is used (e.g. a menu or a page). Options include:
+- Hiding either the home and/or back button. One or both can appear in the navigation at the same time.
+- Changing the text of the buttons
+- Redirecting the button to a specific location (e.g. an introductory page)
 
-#### Config
+## Attributes
 
-**\_homeButton** (object): The config.json Home Button target attribute object.
+All configuration options must be added and amended, where appropriate, for all JSON files.
 
->**\_isEnabled** (boolean): Controls whether the Home Button extension is enabled or not.
+### *config.json*
+The following attributes are set within *config.json*.
 
-#### Course
+### **\_homeButton** (object):
+The Home Button object contains the following settings:
 
-**\_homeButton** (object): The course.json Home Button target attribute object.
+#### **\_isEnabled** (boolean):
+Controls whether the Home Button extension is enabled
 
->**\_isEnabled** (boolean): Controls whether the Home Button course object is enabled or not.
+### *course.json*
+The following attributes are set within *course.json*. These are used to set some default settings and the navigation order:
 
->**\_hideHomeButton** (boolean): Controls whether the navigational home button is hidden or not.
+### **\_homeButton** (object):
+The Home Button object contains the following settings:
 
->**\_redirectToId** (string): Define the page ID that the home button should direct the user to in case an override to the standard behaviour is required.
+#### **_navOrder** (number):
+The order that the button appears in the navigation
 
->**alt** (string): This text becomes the global home buttons's aria label attribute.
+#### **_showLabel** (boolean):
+Controls whether the button should use a navigation label or just an icon
 
-#### ContentObject
+#### **alt** (string):
+The button's `aria-label` text. Used to override global setting
 
-**\_homeButton** (object): The contentObject.json Home Button target attribute object.
+#### **navLabel** (string):
+The button label text as it appears in the navigation
 
->**\_isEnabled** (boolean): Controls whether the Home Button contentObject object is enabled or not.
+#### **_navTooltip** (object):
+The Navigation Tooltip object contains the following settings:
 
->**\_hideHomeButton** (boolean): Controls whether the navigational home button is hidden or not.
+##### **\_isEnabled** (boolean):
+Controls whether the navigation tooltip is enabled
 
->**\_hideBackButton** (boolean): Controls whether the navigational back button is hidden or not.
+##### **text** (string):
+The text of the tooltip. Used to override global setting
 
->**\_redirectToId** (string): Define the page ID that the home button should direct the user to in case an override to the standard behaviour is required.
+### *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:
+
+#### **\_isEnabled** (boolean):
+Controls whether the Home Button extension is enabled
+
+#### **\_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.
+
+#### **\_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.
+
+#### **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
+
+#### **_navTooltip** (object):
+The Navigation Tooltip object contains the following settings:
+
+##### **\_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
+
+## Limitations
+
+No known limitations.
 
 ----------------------------
 
-**Framework versions:**  5+<br>
+**Framework versions:**  5.30.3+<br>
 **Author / maintainer:**  CGKineo<br>
 **Accessibility support:** WAI AA<br>
 **RTL support:** Yes<br>

example.json

@@ -18,7 +18,7 @@
   }
 }
 
-// course.json or contentObjects - Use to configure at the menu or content object level
+// course.json - Use to configure at the menu level
 "_homeButton": {
   "_isEnabled": true,
   "_hideHomeButton": false,
@@ -31,3 +31,18 @@
     "text": "Introduction"
   }
 }
+
+// contentObjects.json - Use to configure at the content object level
+"_homeButton": {
+  "_isEnabled": true,
+  "_hideHomeButton": false,
+  "_hideBackButton": true,
+  "_comment": "Amend _redirectToId to match the ID of the start / landing page",
+  "_redirectToId": "",
+  "_comment": "Option to override navigation button label and tooltip",
+  "navLabel": "Introduction",
+  "_navTooltip": {
+    "_isEnabled": true,
+    "text": "Introduction"
+  }
+}

js/adapt-homeButton.js

@@ -65,6 +65,7 @@ class HomeButton extends Backbone.Controller {
     const currentModelConfig = this.currentModelConfig;
     const {
       _navOrder = -1,
+      alt,
       _showLabel = true,
       navLabel = '',
       _navTooltip = {}
@@ -75,7 +76,7 @@ class HomeButton extends Backbone.Controller {
       _showLabel,
       _classes: 'btn-icon nav__btn nav__homebutton-btn',
       _role: 'link',
-      ariaLabel: navLabel,
+      ariaLabel: alt || navLabel,
       text: navLabel,
       _navTooltip,
       _event: currentModelConfig?._redirectToId ? 'redirectedHomeButton' : 'homeButton'

properties.schema

@@ -9,17 +9,15 @@
       "required": true,
       "title": "Navigation bar order",
       "help": "Determines the order in which the button is displayed in the navigation bar. Negative numbers (e.g. -100) are left-aligned. Positive numbers (e.g. 100) are right-aligned.",
-      "default": 0,
-      "inputType": "Text",
-      "validators": []
+      "default": -1,
+      "inputType": "Text"
     },
     "_showLabel": {
       "type": "boolean",
       "required": true,
       "default": true,
       "title": "Enable navigation bar button label",
       "inputType": "Checkbox",
-      "validators": [],
       "help": "Controls whether a label is shown on the navigation bar button."
     },
     "navLabel": {
@@ -28,7 +26,6 @@
       "default": "Home",
       "title": "Navigation bar button label",
       "inputType": "Text",
-      "validators": [],
       "translatable": true
     },
     "_navTooltip": {
@@ -65,10 +62,9 @@
                 "_isEnabled": {
                   "type": "boolean",
                   "required": false,
-                  "default": false,
+                  "default": true,
                   "title": "Enable control of the home button plugin",
-                  "inputType": "Checkbox",
-                  "validators": []
+                  "inputType": "Checkbox"
                 }
               }
             }
@@ -103,18 +99,44 @@
                   "required": false,
                   "default": "",
                   "title": "Redirect the home button to id",
-                  "help": "Enter the Friendly id of the page that the home button should direct the user to (ex. a splash page)",
+                  "help": "Enter the Friendly id of the page that the home button should direct the user to (e.g. a splash page)",
                   "inputType": "Text",
                   "validators": []
                 },
                 "alt": {
                   "type": "string",
                   "required": false,
                   "default": "Home",
-                  "title": "Home button alt text - applied globally",
+                  "title": "Home button alt text",
+                  "help": "Used for aria-label value",
                   "inputType": "Text",
                   "validators": [],
                   "translatable": true
+                },
+                "navLabel": {
+                  "type": "string",
+                  "required": true,
+                  "default": "Home",
+                  "title": "Navigation bar button label",
+                  "inputType": "Text",
+                  "translatable": true
+                },
+                "_navTooltip": {
+                  "type": "object",
+                  "title": "Navigation tooltip",
+                  "properties": {
+                    "_isEnabled": {
+                      "type": "boolean",
+                      "title": "Enable tooltip for navigation button",
+                      "default": true
+                    },
+                    "text": {
+                      "type": "string",
+                      "title": "",
+                      "default": "Home",
+                      "translatable": true
+                    }
+                  }
                 }
               }
             }
@@ -131,8 +153,8 @@
                 "_isEnabled": {
                   "type": "boolean",
                   "required": false,
-                  "default": false,
-                  "title": "Enable control of the home button at page level",
+                  "default": true,
+                  "title": "Enable control of the home button on this page",
                   "inputType": "Checkbox",
                   "validators": []
                 },
@@ -147,7 +169,7 @@
                 "_hideBackButton": {
                   "type": "boolean",
                   "required": false,
-                  "default": false,
+                  "default": true,
                   "title": "Hide the back button",
                   "inputType": "Checkbox",
                   "validators": []
@@ -157,21 +179,48 @@
                   "required": false,
                   "default": "",
                   "title": "Redirect the home button to id",
+                  "help": "Enter the Friendly id of the page that the home button should direct the user to (e.g. a splash page)",
                   "inputType": "Text",
                   "validators": []
+                },
+                "alt": {
+                  "type": "string",
+                  "required": false,
+                  "default": "Home",
+                  "title": "Home button alt text",
+                  "help": "Used for aria-label value",
+                  "inputType": "Text",
+                  "validators": [],
+                  "translatable": true
+                },
+                "navLabel": {
+                  "type": "string",
+                  "required": true,
+                  "default": "Home",
+                  "title": "Navigation bar button label",
+                  "inputType": "Text",
+                  "translatable": true
+                },
+                "_navTooltip": {
+                  "type": "object",
+                  "title": "Navigation tooltip",
+                  "properties": {
+                    "_isEnabled": {
+                      "type": "boolean",
+                      "title": "Enable tooltip for navigation button",
+                      "default": true
+                    },
+                    "text": {
+                      "type": "string",
+                      "title": "",
+                      "default": "Home",
+                      "translatable": true
+                    }
+                  }
                 }
               }
             }
           }
-        },
-        "article": {
-          "type": "object"
-        },
-        "block": {
-          "type": "object"
-        },
-        "component": {
-          "type": "object"
         }
       }
     }

schema/config.schema.json

@@ -16,7 +16,7 @@
             "_isEnabled": {
               "type": "boolean",
               "title": "Enable control of the home button globally",
-              "default": false
+              "default": true
             }
           }
         }

schema/contentobject.schema.json

@@ -16,23 +16,60 @@
             "_isEnabled": {
               "type": "boolean",
               "title": "Enable control of the home button on this page",
-              "default": false
+              "default": true
             },
             "_hideHomeButton": {
               "type": "boolean",
-              "title": "Hide the home button on this page",
+              "title": "Hide the home button",
               "default": false
             },
             "_hideBackButton": {
               "type": "boolean",
-              "title": "Hide the back button on this page",
-              "default": false
+              "title": "Hide the back button",
+              "default": true
             },
             "_redirectToId": {
               "type": "string",
               "title": "Redirect the home button to id",
-              "description": "Enter the Friendly id of the page that the home button should direct the user to (ex. a splash page)",
+              "description": "Enter the Friendly id of the page that the home button should direct the user to (e.g. a splash page)",
               "default": ""
+            },
+            "alt": {
+              "type": "string",
+              "title": "Home button alt text",
+              "description": "Used for aria-label value",
+              "default": "Home",
+              "_adapt": {
+                "translatable": true
+              }
+            },
+            "navLabel": {
+              "type": "string",
+              "title": "Navigation bar button label",
+              "default": "Home",
+              "_adapt": {
+                "translatable": true
+              }
+            },
+            "_navTooltip": {
+              "type": "object",
+              "title": "Navigation tooltip",
+              "default": {},
+              "properties": {
+                "_isEnabled": {
+                  "type": "boolean",
+                  "title": "Enable tooltip for navigation button",
+                  "default": true
+                },
+                "text": {
+                  "type": "string",
+                  "title": "",
+                  "default": "Home",
+                  "_adapt": {
+                    "translatable": true
+                  }
+                }
+              }
             }
           }
         }