Skip to content

Latest commit

 

History

History
81 lines (63 loc) · 3.17 KB

usage.md

File metadata and controls

81 lines (63 loc) · 3.17 KB

Usage

silverstripe-autotoc is basically a SilverStripe 4 module that extends a controller (if the CMS is present the ContentController will be extended out of the box) to provide:

  • the $Autotoc tag, containing the table of contents dynamically generated from the content of the current page. The tree is provided as a mixture of ArrayData and ArrayList, ready to be consumed by templates;
  • the $ContentField tag, containing the HTML content properly augmented with the destinations of the TOC links;
  • the $OriginalContentField tag, for accessing the original (non-augmented) content field;
  • an automatic override of the value of the content field ($Content by default): accessing that field will automatically return the augmented HTML. Use $OriginalContentField to access the non-augmented content, if needed.

You will need to modify your templates for embedding the $Autotoc tag (see AutoTOC format for the gory details) or directly include the sample template, e.g.:

<% include Autotoc %>

Specifying the content field

If you want to tocify a field different from Content, set the desired name in the content_field property, e.g.:

ContentController:
    content_field: 'Content' # Bogus: this is the default
ProductPage_Controller:
    content_field: 'Details'
AuthorHandler:
    content_field: 'Biography'

WARNING: the content field is not expected to be changed dynamically, so it should be properly set before the first instantiation of the bound object.

Augmenting algorithm

By default the HTML is augmented by setting the id attribute directly on the destination element (see Tocifier::setId for the exact implementation). Any preexisting id will be overwritten.

The old behavior instead was to inject anchors (<a> elements with the id attribute but without href) just before the destination element. It is still possible to enable it by changing the augment callback to Tocifier::prependAnchor. Just add the following to your YAML config:

eNTiDi\Autotoc\Autotoc:
    augment_callback: eNTiDi\Autotoc\Tocifier::prependAnchor

You can leverage this option to run your own callbacks too, e.g.:

eNTiDi\Autotoc\Autotoc:
    augment_callback: 'Page::defaultCallback'
Page:
    augment_callback: 'Page::specificCallback'

The callback receives three arguments: the main DOMDocument instance, the DOMElement to augment and a string with the ID the element must refer to.

Excluding items from the TOC

If for some reasons you do not want to include some sections in the TOC, just specify the data-hide-from-toc attribute, e.g.:

<h2>First section</h2>
<h2>Second section</h2>
<h2 data-hide-from-toc>This section will be skipped</h2>
<h2>Last section</h2>