Blog - Blocks - Table of Contents Block

Table of Contents Block

The Table of Contents block scrapes and filters the page content for heading blocks to create a nested list of links to those heading blocks/sections on the page. It is very simple to use, just insert one into the page anywhere you wish. It’s location does not determine it’s content. You can include/exclude heading blocks by tag value by turning on/off settings found in the Block Settings panel in the block inspector. You can also include a title and custom style each part of the block.

Settings Overview

  • List Options
    • Heading Blocks : Choose which heading block H-Tag levels to include in the list. Successive tags with lower value become an indented sub-list below the previous higher tag.
    • Layout & Styling
      • List Bullet Style : Choose a bullet style for the list or choose NONE to exclude the bullets. Supported styles include those most common, they have been tested in Firefox and Chrome. Results may vary across browsers and devices.
      • Sub-List Indent : Adjust the distance on pixels for the indent of each list level. Set to 0 to use the default.
      • Indent Base Level : Turn this on to apply the indent setting to the base level of the list. This setting is only available when Sub-List Indent is not set to 0.
      • Bold Level 1 : Bold the base level of the list.
      • Bold Level 2 : Bold the second level of the list.
      • Bold Level 3 : Bold the third and all subsequent levels of the list.
  • Styled Nodes : Object nodes within the block DOM with styling settings. [tutorial]
    • root object : Block Settings panel
      • table wrapper : Table Wrapper panel
        • title : Title panel
        • list : Table panel
      • content wrapper : Content Wrapper panel

Object Map (DOM)

  • root object (div) targeted node from Block Settings panel : You may assign basic settings that apply to this block.
    • internal wrapper (div) untargeted node : Used to support advanced layout options. Most of our blocks have one of these wrappers. It has no styling of it’s own, it’s children are considered the block’s children.
      • table wrapper (div) targeted node from Table Wrapper panel : This node contains the block title and heading list. Styles applied to this node will be inherited by all children and will override the same style applied to the block at root level.
        • title (div) targeted node from Title panel : Single text field, text is edited in the block not in the panel. Styles targeting this node only apply to the title, and will override the same style applied to the block and/or content wrapper.
        • list wrapper (div) targeted node from Table panel : Used to separate the list object from it’s siblings (all divs) and utilize higher CSS prioritization for list level rules.
          • list object (ul) untargeted node : List object with links targeting heading objects on the page.
      • content wrapper (div) targeted node from Content Wrapper panel : This node is where you may enter basic text as paragraph blocks (just type) or insert other blocks. Styles applied to this node are inherited by it’s children and it follow suit with previously explained cascading.
        • wp nested wrapper (div) untargeted node : This node is generated by Gutenberg around nested content, we sometimes use it when layout rules need to be applied. Follow suit with the internal wrapper.
          • nested blocks (?) untargeted nodes : Anything put into the nested content area. Each block may have it’s own style rules, some core blocks do. Styles applied to a child “should” be able to override the same style cascaded to it from above. I use the word “should” because we only have control over our own blocks and how styles are applied to them, core and outsider blocks have their own methods.

Tutorial

  • Insert a Table of Contents block into the page or insert it into another block.
  • Open the List Options panel in the block inspector (sidebar).
    • Turn off any Heading Blocks H-Tag values you wish to exclude from the list.
    • Change the List Bullet Style if you wish.
    • Adjust the Sub-List Indent distance if you wish. By default the base level of the list is not indented to align it with the block edges or padding. If you set a custom indent distance you may also override this behavior by turning on the Indent Base Level setting.
    • You may bold any/all levels of the list independently using the Bold Level settings.
  • Styled Nodes : Object nodes within the block DOM with styling settings. [tutorial]
    • block : Block Settings panel
      • table wrapper : Table Wrapper panel
        • title : Title panel
        • table : Table panel
      • content wrapper : Content Wrapper panel
  • The PHP magic happens during page rendering.

Example #1 – basic block with default options

Example #2 – title, styling, list/heading options and a tutorial for reproducing it

  • Insert a Table of Contents block into your page.
  • Open the Table Settings panel.
    • Turn off the Include H5 Tags setting. This ignores the Heading blocks used for the Example headings. You will see the difference in these examples.
    • Choose “Circle” from the List Bullet Style selector.
    • Set the Sub-List Indent to 20px using the slider or by entering 20 in the number field. This allows you to prevent indenting the base level of the list.
    • Turn on the Bold Level 1 setting. This will bold the text for the base level links in the list.
    • Set the Font Size to 18px.
    • Choose “Georgia” from the Font Family selector.
  • Open the Block Settings panel.
    • Choose a Background Color that works with the text color. This example uses a light blue.
    • Choose a Border Color. This example uses a dark blue.
    • Set the Border Width to 7px. This setting directly affects the double border style.
    • Choose “Double” from the Border Style selector. With a 7px width you get 2px lines with 5px space between them. If you were to choose 8px width, it will result in 3px lines with only 2px space between them, this is just how the double border CSS rule works. Each border style is affected by width differently.
    • Choose a Shadow Color from the Box Shadow section. This example uses a black shadow with default offset and blur.
    • Set the Padding to 20px.
  • Enter some text into the Title field in the block editor. This example uses “Table of Contents”.
  • Open the Title panel.
    • Set the Font Color to white.
    • Set the Text Shadow Color to black.
    • Turn on the Double Shadow setting.
    • Set the Font Size to 30px.

Example #3 – block as image banner

  • Insert a Table of Contents block into your page.
  • This is a banner, we want it to go to the browser edges, but in this example we want to keep the content wrapper aligned with the page text and content. We support the WordPress “full width” and “wide” alignments, and we also have a block layout to cover this scenario.
    • In the Block Layout section of the block toolbar toggle on Full Content Aligned (last button). This setting can also be found in the Block Settings panel. [tutorial]
  • Open the Table Settings panel.
    • Turn off the Include H5 Tags setting. This ignores the Heading blocks used for the Example headings. You will see the difference in these examples.
  • Open the Block settings panel.
    • Choose a Background Image. [tutorial] As this is a banner it will only look good with a large image, preferrably wide or with content that crops well vertically. The example image was a good choice for this reason.
    • Set both the Padding Top and Padding Bottom to 60px.
  • Open the Content Wrapper panel.
    • Set the Background Color to white. [tutorial]
    • Set the Padding to 20px. [tutorial]

The following demo content will provide content for the examples above. Example #1 includes the example headings which are setup as H5 tags. Example #2 is setup to ignore H5 tags, so the example headings are not included.

H2 Heading Block

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed tristique tincidunt augue ullamcorper ultricies. Curabitur lectus felis, dapibus non vulputate id, imperdiet a tellus. Sed id cursus ex, quis aliquam tellus. Aenean imperdiet, dolor nec tincidunt sagittis, nisl lectus elementum velit, in molestie lacus nibh et neque. Integer sollicitudin dolor dolor. Duis ultricies a orci non feugiat. Vivamus tempus tempor euismod. Suspendisse potenti. Sed ac augue quis arcu mattis rutrum. Quisque sed sapien non leo euismod semper vitae sed enim. Quisque commodo, risus ac accumsan viverra, justo ex ultrices augue, ut semper nulla erat vitae metus. Vivamus vehicula lacus a ullamcorper consectetur. Vivamus vel vulputate urna, consectetur ultricies justo. Quisque cursus pharetra vulputate.

H3 Heading Block

Nullam sagittis eget massa vel tempus. Sed vitae diam sed ligula mattis convallis. Ut convallis nisl purus, a fermentum lectus bibendum nec. In ultrices a sapien nec sollicitudin. Proin semper urna vitae velit aliquet imperdiet. Nulla sed neque venenatis, pellentesque lacus in, vehicula eros. Phasellus eget dignissim enim, non consectetur arcu. Nam semper nibh metus, quis lobortis tortor rhoncus a. Nulla nec est ut est tristique mollis id ut odio. Praesent rutrum ex id velit commodo auctor. Nam luctus est nec diam faucibus, viverra molestie orci suscipit. Morbi sit amet ultricies nunc, at iaculis augue.

H4 Heading Block

Pellentesque ac pulvinar mi, quis condimentum risus. Curabitur nulla lorem, interdum ut justo et, sollicitudin porta ligula. Phasellus vitae odio id diam ullamcorper lobortis. Nam accumsan leo sit amet sollicitudin gravida. Vivamus ac cursus sapien. Donec ac tincidunt mi. Etiam aliquet arcu eu lectus luctus faucibus. Vestibulum hendrerit consectetur orci, sed sollicitudin magna molestie non.

Another H4 Heading Block

Nulla laoreet neque blandit dolor mollis, ac egestas tellus convallis. Integer mattis ut neque non suscipit. Praesent felis dolor, scelerisque vitae ullamcorper a, tempus at tortor. Nunc orci est, condimentum in aliquet et, bibendum imperdiet justo. Phasellus nulla ex, scelerisque in nisi nec, commodo bibendum magna.

H5 Heading Block

Integer pretium sem ut eros pretium finibus. Nam venenatis, metus vitae hendrerit aliquam, elit lectus vulputate dui, at tempus augue ligula at elit. Sed malesuada non odio vel congue. Mauris imperdiet faucibus ante rutrum mollis. Interdum et malesuada fames ac ante ipsum primis in faucibus.

Another H2 Heading Block

Fusce dignissim lacus erat, gravida lobortis lorem porta nec. Curabitur feugiat posuere leo elementum maximus. Aliquam id purus ac est porttitor laoreet sit amet quis arcu. Quisque vestibulum semper orci vitae cursus. Nunc at enim a ante condimentum condimentum. Maecenas gravida turpis sed arcu pretium aliquam.

H4 Heading Block After an H2 Block

Sed pellentesque nisl arcu, nec maximus eros mattis sed. Donec ut ipsum vel magna rhoncus pellentesque in vel augue. Praesent nec nulla malesuada, bibendum neque et, feugiat turpis. Phasellus non dignissim magna, a ultricies libero. Suspendisse condimentum suscipit sem, pretium euismod urna commodo ac. Donec metus elit, vulputate tristique laoreet sodales, luctus nec dui. In hac habitasse platea dictumst. Mauris et ipsum est. Suspendisse eros tellus, ornare in tempor id, congue vitae lectus. Nunc feugiat viverra ex, sed mollis ante mattis nec.