Table of Content Component

Component to insert a table of content that helps visitors to navigate the content of the page.

User Story

As an author, I want to insert a table of content to my page that lists all 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 (title or teaser component, 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.
• Capability for the author to choose how to render the list (unordered list - the default, or ordered list).
• Capability for the author 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.
• The component must not impact page speed:
  • It must avoid any cumulative layout shifts that could be introduced by client-side rendering. Server-side rendering by AEM is therefore preferred.
  • It must not slow down the first byte sent to the browser. Any HTML rewriter must therefore not block the output, or at least not until the placeholder of the TOC component is reached on the page.

Extended Requirements

• 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.

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