216 строки
7.1 KiB
Markdown
216 строки
7.1 KiB
Markdown
PHP TOC Generator
|
|
=================
|
|
|
|
Geneates Table of Contents from H1...H6 Tags in HTML Content
|
|
------------------------------------------------------------
|
|
|
|
[](https://travis-ci.org/caseyamcl/toc.png)
|
|
|
|
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](https://github.com/KnpLabs/KnpMenu) 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](http://getcomposer.org/) by including the following in your `composer.json` file:
|
|
|
|
{
|
|
"require": {
|
|
"caseyamcl/toc": "~1.0",
|
|
}
|
|
}
|
|
|
|
Or, drop the `src` folder into your application and use a [PSR-4 autoloader](http://www.php-fig.org/psr/psr-4/) 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:
|
|
|
|
```php
|
|
$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](http://twig.sensiolabs.org) 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:
|
|
|
|
```twig
|
|
{# 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:
|
|
|
|
```twig
|
|
{# 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:
|
|
|
|
```twig
|
|
{% 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:
|
|
|
|
```php
|
|
$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:
|
|
|
|
```php
|
|
$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:
|
|
|
|
```php
|
|
$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:
|
|
|
|
```twig
|
|
{# 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](https://github.com/KnpLabs/KnpMenu/blob/master/src/Knp/Menu/Renderer/ListRenderer.php) 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`](https://github.com/KnpLabs/KnpMenu/blob/master/src/Knp/Menu/Renderer/RendererInterface.php)).
|
|
|
|
For example, you may wish to use different CSS classes for your list items:
|
|
|
|
```php
|
|
|
|
$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](http://twig.sensiolabs.org/)
|
|
than is offered by default with this library. You can take advantage of it by using the [TwigRenderer](https://github.com/KnpLabs/KnpMenu/blob/master/doc/02-Twig-Integration.markdown#using-the-twigrenderer)
|
|
that is bundled with KnpMenu:
|
|
|
|
```php
|
|
|
|
$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));
|
|
|
|
```
|