From dc45f9690e8c81f36109f56a2dace1b79c65e71b Mon Sep 17 00:00:00 2001 From: Brad Simpson Date: Mon, 11 Dec 2023 13:31:36 -0700 Subject: [PATCH 1/4] README - Formatting fixes, minor text changes --- README.md | 109 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 71 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index fb04a3b..35a6b1f 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,16 @@ -# TOC +# adapt-toc -This extension provides a drawer-based table of contents for Adapt as an alternative to (or complement) a traditional menu (for example `adapt-contrib-boxMenu`). +This extension provides a drawer-based table of contents for Adapt as an alternative to (or to complement) a traditional menu (e.g. `adapt-contrib-boxMenu`). -There are two modes of operation. In the simple case all content objects are listed as links in the drawer. Any content objects that should not appear in the list can be excluded. +There are two modes of operation: simple and custom: -For custom usage, groupings can be defined to create a hierarchy of content objects; for example to reflect a menu/submenu structure. Each group can have a title and there is no limit to the level of group nesting. +- In the *simple* case, all content objects are listed as links in the drawer. Any content objects that should not appear in the list can be excluded. -See example.json for configuration guidance. +- For *custom* usage, groupings can be defined to create a hierarchy of content objects; for example to reflect a menu/submenu structure. Each group can have a title and there is no limit to the level of group nesting. -If `adapt-contrib-pageLevelProgress` is enabled at course level (`course.json`) this extension calculates progress by the same method as `adapt-contrib-pageLevelProgress`. This is to ensure consistency of the progress indicators. +See [*example.json*](https://github.com/cgkineo/adapt-toc/blob/master/example.json) for configuration guidance. + +If `adapt-contrib-pageLevelProgress` is enabled at course level (*course.json*), this extension calculates progress by the same method as `adapt-contrib-pageLevelProgress`. This is to ensure consistency of the progress indicators. ## Settings Overview @@ -16,71 +18,102 @@ If `adapt-contrib-pageLevelProgress` is enabled at course level (`course.json`) ## Attributes -Add to _course.json_ under _\_globals.\_extensions_. +### *course.json - \_globals.\_extensions* + +Add to *course.json* under *\_globals.\_extensions*. + +### **\_toc** (object) + +The `_toc` object contains the following settings: -#### \_toc_ (object): -The Table of Contents object +#### **navigationToc** (string) -##### \navigationToc (string): Aria label for the navigation button -##### \toc (string): +#### **toc** (string) + Aria label to indicate the beginning of the table of contents -##### \tocEnd (string): +#### **tocEnd** (string) + Aria label to indicate the end of the table of contents -##### \tocContentObject (string): +#### **tocContentObject** (string) + Aria label to indicate completion -##### \optionalContent (string): +#### **optionalContent** (string) + Label to indicate optional content -##### \_navTooltip (object): +#### **\_navTooltip** (object) + The tooltip object. Used when tooltips are enabled globally -###### \_isEnabled (boolean): +##### **\_isEnabled** (boolean) + Enables tooltips on the button -###### \text (string): -The text of the tooltip +##### **text** (string) -Add the following directly to _course.json_. +The text of the tooltip ### *course.json* -The following attributes, set within *course.json*, configure the defaults for **ToC**. -#### \_toc (object): -The toc object contains the following settings: +The following attributes, set within *course.json*, configure the defaults for **ToC**. Add directly to *course.json*. + +### **\_toc** (object) + +The `_toc` object contains the following settings: -##### \_drawerPosition (string); -The position that the button appears in the drawer. Position options include 'auto', 'left', and 'right'. Defaults to 'auto' +#### **\_drawerPosition** (string) -##### \_excludeContentObjects (array); -Optional list of content object ids to be excluded from the toc list e.g. ["co-100"] or ["co-100", "co-200"] +The position that the button appears in the drawer. Position options include `auto`, `left`, and `right`. Defaults to `auto` + +#### **\_excludeContentObjects** (array) + +Optional list of content object `_id` values to be *excluded* from the ToC list. For example, `["co-100"]` or `["co-100", "co-200"]` + +#### **\_grouping** (object) -##### \_grouping (object): The grouping object contains the following settings: -####### title (string): -The title text for the group list. +##### **title** (string) + +The title text for the group list -####### \_ariaLevel (number): -Define the group list title aria level. Usually this will be set to `1` but if +##### **\_ariaLevel** (number) + +Define the group list title aria level. Usually this will be set to `1` but can be overridden. + +##### **\_classes** (string) -###### \_classes (string): CSS class name(s) to be applied to this groups containing `div`. The class(es) must be predefined in one of the Less files. Separate multiple classes with a space. -###### \_items (array): +##### **\_items** (array) + The items array contains the list of content objects to be included. Can also include the `_grouping` object for nested items. -####### \_classes (string): +###### **\_classes** (string) + CSS class name(s) to be applied to this items containing `div`. The class(es) must be predefined in one of the Less files. Separate multiple classes with a space. -####### \_contentObjects (array): -List of content object ids to be included in the groups item list e.g. ["co-100"] or ["co-100", "co-200"] +###### **\_contentObjects** (array) + +List of content object ids to be *included* in the groups item list. For example, `["co-100"]` or `["co-100", "co-200"]` ### Notes -- In most scenarios it is necessary to specify a start page (see `example.json`). -- It may be necessary to remove (or hide) the back button (`.navigation-back-button`) to prevent Adapt attempting to navigate to `course` level. \ No newline at end of file +- In most scenarios it is necessary to specify a start page (see [*example.json*](https://github.com/cgkineo/adapt-toc/blob/master/example.json)). +- It may be necessary to remove (or hide) the back button (`.navigation-back-button`) to prevent Adapt attempting to navigate to `course` level. + +## Limitations + +No known limitations. + +---------------------------- + +**Author / maintainer:** CGKineo
+**Accessibility support:** WAI AA
+**RTL support:** Yes
+**Cross-platform coverage:** Chrome, Chrome for Android, Firefox (ESR + latest version), Edge, Safari for macOS/iOS/iPadOS, Opera
From e2927abf39f294e5089c9e39d10421d40bba7870 Mon Sep 17 00:00:00 2001 From: Brad Simpson Date: Tue, 12 Dec 2023 09:24:45 -0700 Subject: [PATCH 2/4] Add note about excluding the menu link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 35a6b1f..05128a2 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ The position that the button appears in the drawer. Position options include `au #### **\_excludeContentObjects** (array) -Optional list of content object `_id` values to be *excluded* from the ToC list. For example, `["co-100"]` or `["co-100", "co-200"]` +Optional list of content object `_id` values to be *excluded* from the ToC list. For example, `["co-100"]` or `["co-100", "co-200"]`. To exclude the menu link, use 'course'. #### **\_grouping** (object) From b7a53891b0fa38fd7956c94513a0576e9b76bdf2 Mon Sep 17 00:00:00 2001 From: Brad Simpson Date: Tue, 12 Dec 2023 09:38:37 -0700 Subject: [PATCH 3/4] Update README.md - backticks --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 05128a2..0d6c489 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ The position that the button appears in the drawer. Position options include `au #### **\_excludeContentObjects** (array) -Optional list of content object `_id` values to be *excluded* from the ToC list. For example, `["co-100"]` or `["co-100", "co-200"]`. To exclude the menu link, use 'course'. +Optional list of content object `_id` values to be *excluded* from the ToC list. For example, `["co-100"]` or `["co-100", "co-200"]`. To exclude the menu link, use `course`. #### **\_grouping** (object) From 4d73d54bdcddfa809ddd62888b95708dfa91ddbd Mon Sep 17 00:00:00 2001 From: Brad Simpson Date: Mon, 18 Dec 2023 08:52:46 -0700 Subject: [PATCH 4/4] Remove extra colon --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0d6c489..b8d2e99 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This extension provides a drawer-based table of contents for Adapt as an alternative to (or to complement) a traditional menu (e.g. `adapt-contrib-boxMenu`). -There are two modes of operation: simple and custom: +There are two modes of operation: simple and custom. - In the *simple* case, all content objects are listed as links in the drawer. Any content objects that should not appear in the list can be excluded.