Breaking: Update and modernize, simplify configuration (fixes #41 #48)

cgkineo · Feb 27, 2024 · 2663645 · 2663645
2 parents 8a05e83 + d4745ab
commit 2663645
Show file tree

Hide file tree

Showing 20 changed files with 873 additions and 1,404 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # adapt-pageNav
 
-**PageNav** is a *presentation component* that adds basic navigation controls to a page
+**PageNav** is a *presentation component* that adds basic navigation controls to a page.
 
 <img src="demo.gif" alt="the page nav extension in action" align="right">
 
@@ -13,65 +13,68 @@ The attributes listed below are used in *components.json* to configure **PageNav
 
 Navigation bar component which can contain some or all of the following buttons:
 
-- _returnToPreviousLocation (takes you back to the previous location - not back in history, just the last routed location)
-- _root (takes you back to top level menu)
-- _up (takes you to the menu the next level up in the hierarchy)
-- _previous (navigates directly to the previous page, if exists, without having to navigate via the menu)
-- _next (navigates directly to the next page, if exists, without having to navigate via the menu)
-- _sibling (1,2,3,4 etc buttons representing each sibling page)
-- _close (closes the course window - only possible if the course was launched in a popup window)
+- `_root`: Navigates to the top level menu
+- `_up`: Navigates to the menu that is the next level up in the hierarchy. For instance, a sub menu.
+- `_previous`: Navigates to the previous page if it exists and is unlocked
+- `_next`: Navigates to the next page if it exists and is unlocked
+- `_close`: Closes the course window. Only possible if the course was launched in a popup window
 
-The pageNav buttons will respect any [locking](https://github.com/adaptlearning/adapt_framework/wiki/Locking-objects-with-'_isLocked'-and-'_lockType'#using-locking-with-menus) that has been configured in Adapt. In cases not covered by Adapt's locking system - such as a [start page](https://github.com/adaptlearning/adapt_framework/wiki/Content-starts-with-course.json#example-1) that appears immediately before the main menu - the setting `_lockUntilPageComplete` can be used to disable the button until the current page has been completed.
+The **PageNav** buttons will respect any [locking](https://github.com/adaptlearning/adapt_framework/wiki/Locking-objects-with-'_isLocked'-and-'_lockType'#using-locking-with-menus) that has been configured in Adapt. In cases not covered by Adapt's locking system - such as a [start page](https://github.com/adaptlearning/adapt_framework/wiki/Content-starts-with-course.json#example-1) that appears immediately before the main menu - the setting `_lockUntilPageComplete` can be used to disable the button until the current page has been completed.
 
 ### Attributes
 
-[**core model attributes**](https://github.com/adaptlearning/adapt_framework/wiki/Core-model-attributes): These are inherited by every Adapt component. [Read more](https://github.com/adaptlearning/adapt_framework/wiki/Core-model-attributes).
+[**core model attributes**](https://github.com/adaptlearning/adapt_framework/wiki/Core-model-attributes): These are inherited by every Adapt component. [Read more](https://github.com/adaptlearning/adapt_framework/wiki/Core-model-attributes)
 
-**\_component** (string): This value must be: `pageNav`. (One word.)
+**\_component** (string): This value must be `pageNav` (one word)
 
 **\_classes** (string): CSS class name to be applied to **PageNav**’s containing `div`. The class must be predefined in one of the Less files. Separate multiple classes with a space.
 
 **\_layout** (string): This defines the horizontal position of the component in the block. Acceptable values are `full`, `left` or `right`.
 
 **instruction** (string): This optional text appears above the component. It is frequently used to guide the learner’s interaction with the component.
 
-**\_loopStyle** (string): Acceptable values are `allPages`, `siblings`, and `none`. `allPages` = loop sequentially through all pages in course. `siblings` = loop sequentially through all pages in current parent object. `none` = disable previous and next buttons at start and end of the pages in the current parent object.
+**\_loopStyle** (string): Acceptable values are `allPages`, `siblings`, and `none`. Defaults to `none`.
+- `allPages`: Loop sequentially through all pages in course
+- `siblings`: Loop sequentially through all pages in current parent object
+- `none`: Disable previous and next buttons at start and end of the pages in the current parent object.
 
 **\_shouldSkipOptionalPages** (boolean): Skip pages that are set to `"_isOptional": true`. Default is `false`.
 
-**\_buttons** (object): The following attributes configure the defaults for the **Quickanv** buttons. These attributes are available on all of the following buttons **\_returnToPreviousLocation**, **\_previous**, **\_root**, **\_up**, **\_next**, **\_sibling**, and **\_close**.
+**\_buttons** (object): The following attributes configure the defaults for the **Quickanv** buttons. These attributes are available on all of the following buttons **\_previous**, **\_root**, **\_up**, **\_next**, and **\_close**.
 
 #### Global button configurations
 
 >**\_isEnabled** (boolean): Turns the button on and off. Acceptable values are `true` and `false`.
 
->**\_lockUntilPageComplete** (boolean): For use when the standard Adapt locking system doesn't apply, such as in a start page before the main menu. Acceptable values are `true` and `false`.
+>**\_lockUntilPageComplete** (boolean): For use when the standard Adapt locking system doesn't apply, such as in a start page before the main menu. Locks a button until the current page is complete. Acceptable values are `true` and `false`. Defaults to `false`
 
 >**\_order** (number): Defines the display order of the button. Numerical order with 0 rendering first.
 
 >**\_classes** (string): CSS class name to be applied to the `button`. The class must be predefined in one of the Less files. Separate multiple classes with a space.
 
->**\_iconClass** (string): CSS class name to be applied to the `button` icon. The class must be predefined in one of the Less files with the corresponding icon be added as part of a font. Suggested icons for each button detailed in the [_example.json_](https://github.com/cgkineo/adapt-pageNav/blob/master/example.json). List of all available [_vanilla_ icons](https://github.com/adaptlearning/adapt-contrib-vanilla/wiki/Icons) to choose from.
+>**\_iconClass** (string): CSS class name to be applied to the `button` icon. The class must be predefined in one of the Less files with the corresponding icon included as part of a font. To have _no_ icon, leave this field blank. Suggested icons for each button are detailed in the [_example.json_](https://github.com/cgkineo/adapt-pageNav/blob/master/example.json). See the list of all available [_vanilla_ icons](https://github.com/adaptlearning/adapt-contrib-vanilla/wiki/Icons) to choose from.
 
->**\_alignIconright** (boolean): Defines whether the icon is aligned to the left or right of the text. Default is `false` which aligns the icon to the left of the text.
+>**\_iconAlignment** (string): Determines how the icon is aligned to the text. Options include `auto`, `left`, `right`, `top`, and `bottom`. When using `auto`, the position will automatically adjust based on whether the user is using an LTR or RTL lanaguage. The `_next` button will also be adjusted accordingly when using `auto` (i.e. the icon will be right-aligned for LTR and left-aligned for RTL). Defaults to `auto`.
 
 >**text** (string): Defines the text that renders in the `button`.
 
 >**ariaLabel** (string): This text is associated with the button. It renders as part of the aria label to give screen readers more information.
 
->**\_showTooltip** (boolean): Defines whether the tooltip renders on hover. Default is `false`.
+> **\_tooltip** (object): The tooltip object. Used when tooltips are enabled globally
 
->**tooltip** (string): Defines the text that renders in the tooltip.
+>> **\_isEnabled** (boolean): Enables tooltips on the button
 
-#### **\_previous** / **\_root** / **\_up** / **\_next** / **\_sibling**
+>> **text** (string): The text of the tooltip
+
+#### **\_previous**, **\_root**, **\_up**, and **\_next** properties
 
 >**\_customRouteId** (string): Overrides the route ID. For use when non standard route navigation is required.
 
 ----------------------------
 
-**Framework versions:**  5.2+<br>
+**Framework versions:**  5.30.2+<br>
 **Vanilla versions:**  5.1.1+<br>
 **Author / maintainer:**  Kineo<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>
+**Cross-platform coverage:** Chrome, Chrome for Android, Firefox (ESR + latest version), Edge, Safari for macOS/iOS/iPadOS, Opera<br>
diff --git a/bower.json b/bower.json
@@ -5,7 +5,7 @@
     "url": "git://github.com/cgkineo/adapt-pageNav.git"
   },
   "version": "2.4.0",
-  "framework": ">=5.2",
+  "framework": ">=5.30.2",
   "homepage": "https://github.com/cgkineo/adapt-pageNav",
   "issues": "https://github.com/cgkineo/adapt-pageNav/issues/",
   "component": "pageNav",

diff --git a/demo.fw.png b/demo.fw.png
diff --git a/example.json b/example.json
@@ -1,118 +1,97 @@
-    // To go in the component.json file for each page
-    // --------------------------------------------------
-    {
-        "_id": "c-05",
-        "_parentId": "b-05",
-        "_type": "component",
-        "_component": "pageNav",
-        "_classes": "",
-        "_layout": "full",
-        "title": "",
-        "displayTitle": "",
-        "body": "",
-        "instruction": "",
-        "_loopStyleComment": {
-            "allPages": "loop sequentially through all pages in course",
-            "siblings": "loop sequentially through all pages in current parent object",
-            "none": "disable previous and next buttons at start and end of the pages in the current parent object"
-        },
-        "_loopStyle": "none",
-        "_shouldSkipOptionalPages": false,
-        "_buttons": {
-            "_returnToPreviousLocation": {
-                "_isEnabled": false,
-                "_lockUntilPageComplete": false,
-                "_order": 1,
-                "_classes": "",
-                "_iconClassComment": "Suggested icon = 'icon-controls-left'",
-                "_iconClass": "",
-                "_alignIconRight": false,
-                "text": "Return",
-                "ariaLabel": "Return to previous location",
-                "_showTooltip": false,
-                "tooltip": "{{displayTitle}}"
-            },
-            "_previous": {
+// To go in the component.json file for each page
+// --------------------------------------------------
+{
+    "_id": "c-05",
+    "_parentId": "b-05",
+    "_type": "component",
+    "_component": "pageNav",
+    "_classes": "",
+    "_layout": "full",
+    "title": "",
+    "displayTitle": "",
+    "body": "",
+    "instruction": "",
+    "_loopStyleComment": {
+        "allPages": "loop sequentially through all pages in course",
+        "siblings": "loop sequentially through all pages in current parent object",
+        "none": "disable previous and next buttons at start and end of the pages in the current parent object"
+    },
+    "_loopStyle": "none",
+    "_shouldSkipOptionalPages": false,
+    "_buttons": {
+        "_root": {
+            "_isEnabled": true,
+            "_lockUntilPageComplete": false,
+            "_order": 1,
+            "_classes": "",
+            "_iconClass": "icon-home",
+            "_iconAlignment": "auto",
+            "text": "Go to main menu",
+            "ariaLabel": "Go to main menu",
+            "_tooltip": {
                 "_isEnabled": true,
-                "_lockUntilPageComplete": false,
-                "_order": 1,
-                "_classes": "",
-                "_iconClassComment": "Suggested icon = 'icon-controls-left'",
-                "_iconClass": "",
-                "_alignIconRight": false,
-                "text": "Previous",
-                "ariaLabel": "Previous Page",
-                "_showTooltip": false,
-                "tooltip": "{{displayTitle}}",
-                "_customRouteId": ""
+                "text": "{{displayTitle}}"
             },
-            "_root": {
+            "_customRouteId": ""
+        },
+        "_up": {
+            "_isEnabled": false,
+            "_lockUntilPageComplete": false,
+            "_order": 1,
+            "_classes": "",
+            "_iconClass": "icon-controls-up",
+            "_iconAlignment": "auto",
+            "text": "Back to menu",
+            "ariaLabel": "Back to menu",
+            "_tooltip": {
                 "_isEnabled": true,
-                "_lockUntilPageComplete": false,
-                "_order": 1,
-                "_classes": "",
-                "_iconClassComment": "Suggested icon = 'icon-home'",
-                "_iconClass": "",
-                "_alignIconRight": false,
-                "text": "Go to main menu",
-                "ariaLabel": "Go to main menu",
-                "_showTooltip": false,
-                "tooltip": "{{displayTitle}}",
-                "_customRouteId": ""
+                "text": "{{displayTitle}}"
             },
-            "_up": {
-                "_isEnabled": false,
-                "_lockUntilPageComplete": false,
-                "_order": 1,
-                "_classes": "",
-                "_iconClassComment": "Suggested icon = 'icon-controls-up'",
-                "_iconClass": "",
-                "_alignIconRight": false,
-                "text": "Back to menu",
-                "ariaLabel": "Back to menu",
-                "_showTooltip": false,
-                "tooltip": "{{displayTitle}}",
-                "_customRouteId": ""
-            },
-            "_next": {
+            "_customRouteId": ""
+        },
+        "_previous": {
+            "_isEnabled": true,
+            "_lockUntilPageComplete": false,
+            "_order": 1,
+            "_classes": "",
+            "_iconClass": "icon-controls-left",
+            "_iconAlignment": "auto",
+            "text": "Previous",
+            "ariaLabel": "Previous Page",
+            "_tooltip": {
                 "_isEnabled": true,
-                "_lockUntilPageComplete": false,
-                "_order": 1,
-                "_classes": "",
-                "_iconClassComment": "Suggested icon = 'icon-controls-right'",
-                "_iconClass": "",
-                "_alignIconRight": true,
-                "text": "Next",
-                "ariaLabel": "Next Page",
-                "_showTooltip": false,
-                "tooltip": "{{displayTitle}}",
-                "_customRouteId": ""
+                "text": "{{displayTitle}}"
             },
-            "_sibling": {
-                "_isEnabled": false,
-                "_lockUntilPageComplete": false,
-                "_order": 1,
-                "_classes": "",
-                "_iconClass": "",
-                "_alignIconRight": false,
-                "text": "{{inc index}}",
-                "ariaLabel": "Page {{inc index}}",
-                "_showTooltip": false,
-                "tooltip": "{{displayTitle}}",
-                "_customRouteId": ""
+            "_customRouteId": ""
+        },
+        "_next": {
+            "_isEnabled": true,
+            "_lockUntilPageComplete": false,
+            "_order": 1,
+            "_classes": "",
+            "_iconClass": "icon-controls-right",
+            "_iconAlignment": "auto",
+            "text": "Next",
+            "ariaLabel": "Next Page",
+            "_tooltip": {
+                "_isEnabled": true,
+                "text": "{{displayTitle}}"
             },
-            "_close": {
-                "_isEnabled": false,
-                "_lockUntilPageComplete": false,
-                "_order": 1,
-                "_classes": "",
-                "_iconClassComment": "Suggested icon = 'icon-cross'",
-                "_iconClass": "",
-                "_alignIconRight": false,
-                "text": "Close",
-                "ariaLabel": "Close window",
-                "_showTooltip": false,
-                "tooltip": "Close window"
+            "_customRouteId": ""
+        },
+        "_close": {
+            "_isEnabled": false,
+            "_lockUntilPageComplete": false,
+            "_order": 1,
+            "_classes": "",
+            "_iconClass": "icon-cross",
+            "_iconAlignment": "auto",
+            "text": "Close",
+            "ariaLabel": "Close window",
+            "_tooltip": {
+                "_isEnabled": true,
+                "text": "Close window"
             }
         }
     }
+}