Table of Content Component

Component that renders a table of content to help navigating the page content.

User Story

As an author, I want to insert a table of content to my page, so that visitors can easily navigate to the titles that are within the page.

Requirements

• Lists all H1-H6 elements that are rendered on the page, regardless of which component renders them (core title or teaser components, custom components, RTE, etc).
• Lists also those titles that are coming from the page template or from (nested) experience fragments.
• Links to the corresponding component on the page by using the id attribute that is set on the closest parent from the title element.
• Creates a nested list of the titles found on the page, rendering them either with UL/LI or OL/LI elements.
• Authoring capabilities:
  • Capability to choose how to render the list (unordered list - the default, or ordered list).
  • Capability to restrict the start level (default being 1) and the end level (default being 6) of the titles listed.
  • Capability to restrict which title elements are to be listed based on their CSS class names, or of the class name of the elements containing them.
• Other components that must function with the TOC component:
  • Capability for the Carousel, Tabs and Accordion to automatically show potentially hidden element when navigating to it.
  • Same to function also when loading a page with the hash in the url: automatically show the corresponding Carousel, Tabs and Accordion element.
• The component must not impact page speed in any substantial ways:
  • It must not rely on JavaScript that might slow down the page in any way.
  • It must avoid any cumulative layout shifts that could be introduced by client-side rendering.
  • It must not slow down the first byte sent to the browser.
  • Any HTML rewriter must not block the output, or at least not until the placeholder of the TOC component is reached on the page.

Dialog

Edit Dialog

• "List type" label, with info popup "Whether to display the table of content as an unordered list of bullet points, or as an ordered listed of numbered items".
  Drop-down with options "unordered list" and "ordered list", defaulting to "unordered list".
  Option is hidden when the corresponding design configuration is not set to "no restriction".
• "Title start level" label, with info popup "The minimum title level to report in the table of content.". "
  Drop-down with options "1"-"6", defaulting to "1".
  Option is hidden when the corresponding design configuration is not set to "no restriction".
• "Title stop level" label, with info popup "The maximum title level to report in the table of content.". "\ Drop-down with options "1"-"6", defaulting to "6".
  Option is hidden when corresponding design configuration is not set to "no restriction".

Design Dialog

• "Settings" tab
  • "Restrict list type" label, with info popup "Whether the author should be able to choose the list type or not."
    Drop-down with options "no restriction", "unordered list" or "ordered list", defaulting to "no restriction".
  • "Restrict title start level" label, with info popup "Whether the author should be able to choose the the minimum title level to report in the table of content."
    Drop-down with options "no restriction" and "1"-"6", defaulting to "no restriction".
  • "Restrict title stop level" label, with info popup "Whether the author should be able to choose the the maximum title level to report in the table of content."\ Drop-down with options "no restriction", 1-6, defaulting to "no restriction".
  • "Include class names" label, with info popup "If set, only titles with those class names, or contained within elements of the indicated class names will be considered."
    Multi-list of text inputs.
  • "Ignore class names" label, with info popup "If set, titles with those class names, or contained within elements of the indicated class names will be ignored."
    Multi-list of text inputs.
• "Styles" tab with options as for any other core component.

Nesting

Displaying the titles in a nested list can be tricky when authors jump some title levels in their content as it is not desired to have a table of content with empty levels displayed. To correctly display nesting, it helps to think of nesting as a parent to child relationship: an item should only be nested when it also has a corresponding parent. So when an H1 is followed by an H3, in the hierarchy built by the table of content, the H3 should be considered as a direct child of the H1 component, and no empty intermediate node should be represented. Below are listed a few cases that try to push this logic to its limit, illustrating what the resulting table of content should be.

--------------------------------
1: Simple example

h1. Bla    |  * Bla
h2. Bli    |      * Bli
h3. Blo    |          * Blo
h4. Blu    |              * Blu

--------------------------------
2: Simple example

h1. Bla    |  * Bla
h2. Bli    |      * Bli
h1. Blo    |  * Blo
h2. Blu    |      * Blu

--------------------------------
3: Ignore unused levels in-between

h1. Bla    |  * Bla
h3. Bli    |      * Bli
h5. Blo    |          * Blo
h6. Blu    |              * Blu

--------------------------------
4: Ignore unused levels at start

h3. Bla    |  * Bla
h4. Bli    |      * Bli
h3. Blo    |  * Blo
h4. Blu    |      * Blu

--------------------------------
5: Don't nest items that have no parent

h4. Bla    |  * Bla
h3. Bli    |  * Bli
h2. Blo    |  * Blo
h4. Blu    |      * Blu

--------------------------------
6: Don't double-nest child items without a parent

h1. Bla    |  * Bla
h3. Bli    |      * Bli
h2. Blo    |      * Blo
h3. Blu    |          * Blu

--------------------------------
7: Combining all complexities

h3. Bla    |  * Bla
h6. Bli    |      * Bli
h5. Blo    |      * Blo
h2. Blu    |  * Blu
h3. Ble    |      * Ble