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 algorithm

Nesting should function as a child-parent relationship where each item must have a top-level parent node, and where multiple nesting cannot happen without a real element to materialize it. So it should never be possible to start an item or sub-item that is nested more than 1 level.

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

h1. One    |  * One
h2. Two    |      * Two
h3. Three  |          * Three
h4. Four   |              * Four

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

h1. One    |  * One
h2. Two    |      * Two
h1. Three  |  * Three
h2. Four   |      * Four

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

h1. One    |  * One
h3. Two    |      * Two
h5. Three  |          * Three
h6. Four   |              * Four

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

h3. One    |  * One
h4. Two    |      * Two
h3. Three  |  * Three
h4. Four   |      * Four

--------------------------------
5: Nest items only when they have parents

h4. One    |  * One
h3. Two    |  * Two
h2. Three  |  * Three
h4. Four   |      * Four

--------------------------------
6: Don't double-nest child item either

h1. One    |  * One
h4. Two    |      * Two
h3. Three  |      * Three
h2. Four   |      * Four

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

h3. One    |  * One
h6. Two    |      * Two
h5. Three  |      * Three
h2. Four   |  * Four