Simple Table-of-Contents Generator for PHP. Generates TOCs based off H1...H6 tags

1.0 2015-02-04 20:43 UTC

README

Geneates Table of Contents from H1...H6 Tags in HTML Content

Build Status

This package provides a simple, framework-agnostic library to build a Table-of-Contents from HTML markup. It does so by parsing H1...H6 tags. It can also automatically add appropriate id anchor attributes to header tags.

Features:

  • Generates HTML menus and KnpMenu Item Menus
  • Can add anchor ID attributes to H1...H6 tags in your content where they do not already exist
  • You can specify which H1...H6 heading tag levels to include in the TOC
  • Includes a Twig Extension for generating TOC lists and compatible markup directly from templates
  • Uses the flexible KnpMenu Library to generate menus
  • PSR-0 thru PSR-2 Compliant
  • Composer-compatible
  • Unit-tested

In the spirit of KISS philosophy, this library makes a few assumptions:

  1. The hierarchy of your content is defined solely by the header (H1...H6) tags. All other tags are ignored.
  2. The link titles in the Table of Contents match either the title attribute of the header tag, or if there is no title, the plaintext body of the header tag.

Installation Options

Install via Composer by including the following in your composer.json file:

{
    "require": {
        "igorvbelousov/toc": "~1.0",
    }
}

Or, drop the src folder into your application and use a PSR-4 autoloader to include the files.

Usage

This package contains two basic classes:

  1. TOC\MarkupFixer: Adds id anchor attributes to any H1...H6 tags that do not already have any (you can customize the header levels).
  2. TOC\TocGenerator: Generates an HTML (or KnpMenu) Table of Contents.

Basic Example:

$myHtmlContent = <<<END
    <h1>This is a header tag with no anchor id</h1>
    <p>Lorum ipsum doler sit amet</p>
    <h2 id='foo'>This is a header tag with an anchor id</h2>
    <p>Stuff here</p>
    <h3 id='bar'>This is a header tag with an anchor id</h3>
END;

$markupFixer  = new TOC\MarkupFixer();
$tocGenerator = new TOC\TocGenerator();

// This ensures that all header tags have `id` attributes so they can be used as anchors
$htmlOut  = "<div class='content'>" . $markupFixer->fix($myHtmlContent) . "</div>";

// This generates the Table of Contents List
$htmlOut .= "<div class='toc'><ul>" . $tocGenerator->getHtmlMenu($myHtmlContent) . "</ul></div>";

echo $htmlOut;

Twig Integration

This library includes a Twig extension that enables you to load TOC lists and add anchors to markup from your Twig templates.

Specifically, the extension adds a Twig function for generating Table of Contents HTML:

{# Generates HTML markup for given htmlContent #}
<ul>{{ toc(htmlContent) }}</ul>

It also adds one function and one filter for ensuring that your content includes anchors for all HTML header tags:

{# Adds anchor links (id tags) for given htmlContent #}
{{ add_anchors(htmlContent)

{# You can also use it as a filter #}
<div class='my_content'>
    {{ htmlContent | add_anchors }}
</div>

You may have content in hard-coded in your Twig Template that you want to generate a TOC for. An easy way to do this is to make sure the content is surrounded by {% block %}...{% endblock %} tags, and then just pass in that block to the toc function.

For example:

{% extends 'base.html.twig' %}
{% block page_content %}
<div class='page_sidebar'>
   {{ toc(add_anchors(block('my_writeup'))) }}
</div>

<div class='page_content'>
   {{ add_anchors(block('my_writeup')) }}
</div>
{% endblock %}

{% block my_writeup %}
<h1>Hi There</h1>
<p>Lorum ipsum baz biz etecetra</p>
<h2>This is some content</h2>
<p>More content here.  Blah blah</p>
{% endblock %}

In order to enable Twig integration, you must register the TocTwigExtension with your Twig environment:

$myTwig = new \Twig_Environment();
$myTwig->addExtension(new TOC\TocTwigExtension());

Specifying Heading Levels to Include

You can choose to include only specific h1...h6 heading levels in your TOC. To do this, pass two additional arguments to the TocGenerator::getHtmlMenu() method: $topLevel and $depth. For example:

$tocGenerator = new TOC\TocGenerator();

// Get TOC using h2, h3, h4
$toc->getHtmlMenu($someHtmlContent, 2, 3);

// Get TOC using h1, h2
$toc->getHtmlMenu($someHtmlContent, 1, 2);

// Get TOC using h4, h5, h6
$toc->getHtmlMenu($someHtmlContent, 4, 3);

Most other methods in the package take this arguments as well:

$tocGenerator = new TOC\TocGenerator();
$markupFixer = new TOC\MarkupFixer();

// Get KnpMenu using h1, h2, h3
$tocGenerator->getMenu($someHtmlContent, 1, 3);

// Fix markup for h3, h4 tags only
$markupFixer->fix($someHtmlContent, 3, 2);

Twig functions and filters accept this arguments too:

{# Generate TOC using h2, h3 tags #}
{{ toc(my_content, 2, 3) }}

{# Add anchors to h4, h5, h6 tags #}
{{ my_content | add_anchors(4, 3) }}

Customizing Menu Output

You can customize the rendering of lists that the TocGenerator class outputs. By default, TocGenerator uses the KnpMenu ListRenderer class to output the HTML.

You can pass your own instance of the ListRenderer class to TocGenerator::getHtmlMenu(). Or, you can pass in your own renderer (implements Knp\Menu\Renderer\RendererInterface).

For example, you may wish to use different CSS classes for your list items:


$options = [
    'currentAsLink' => false,
    'currentClass'  => 'curr_page',
    'ancestorClass' => 'curr_ancestor',
    'branch_class'  => 'branch
];

$renderer = new Knp\Menu\Renderer\ListRenderer(new Knp\Menu\Matcher\Matcher(), $options);

// Render the list
$tocGenerator = new TOC\TocGenerator();
$listHtml = $tocGenerator->getHtmlMenu($someHtmlContent, 1, 6, $renderer);

Customizing with Twig

The KnpMenu library offers more robust integration with the Twig Templating System than is offered by default with this library. You can take advantage of it by using the TwigRenderer that is bundled with KnpMenu:


$twigLoader = new \Twig_Loader_Filesystem(array(
    __DIR__.'/vendor/KnpMenu/src/Knp/Menu/Resources/views',
    // ...paths to your own Twig templates that render KnpMenus...
));

$twig = new \Twig_Environment($twigLoader);
$itemMatcher = \Knp\Menu\Matcher\Matcher();
$menuRenderer = new \Knp\Menu\Renderer\TwigRenderer($twig, 'knp_menu.html.twig', $itemMatcher);


$tocGenerator = new TOC\TocGenerator();

// Output the Menu using the template 
echo $menuRenderer->render($tocGenerator->getMenu($someHtmlContent));