soo_toc Page 1 of 3 »
Textpattern plugin that automatically generates tables of contents for articles.
Downloadsoo_toc version 0.1.5, 2.1 KB
(If it won’t install try the compressed version)
This is a Textpattern plugin. It contains one tag,
<txp:soo_toc />. This tag can be placed just about anywhere and will automatically generate a table of contents for any article it finds, so long as that article contains HTML headings (h1, h2, etc.) with id attributes. Of course it requires an article context, either list or individual.
It’s much like the
cbs_article_index plugin. However,
<txp:soo_toc /> offers nested list output, heading-level filtering, and a choice of relative or absolute URLs. If you don’t need those features, you might prefer
cbs_article_index for its lighter footprint.
The first five are standard Textpattern attributes; only the last two (
full_url) are plugin-specific.
Label to precede the contents list. Optional; default is unset.
(X)HTML element (without brackets) for the label. Optional; default is unset.
(X)HTML element (without brackets) or text for separating list items. Optional; default is
li. If you change this, you should also change the
(X)HTML element for enclosing the list. Optional; default is
ul. If you change this to something other than
ol, you should also change the
(X)HTML class attribute to be applied to
wraptag. Optional; default is
Number in the range 1–6, indicating the highest heading level to include in the table of contents (see Level, below). Required; default is
6(include all headings).
true, use absolute instead of relative URLs. Optional (but see Relative vs. Absolute URLs, below); default is unset (false).
Can be used in an article body, in a page, or in a form. If used with relative URLs (the default setting) it requires an individual article context. If used in an article list, or on a page in which the
base element indicates anything other than current page, the
full_url attribute must be set to
true (or anything other than
0). (See Relative vs. Absolute URLs, below.)
The article headings
Only headings that have an
id attribute will be included. This is to give the links in the table of contents something to point to. In Textile, you can apply the
id attribute like this:
level attribute allows you to restrict which heading levels to include in the table of contents. For example,
level="3" will restrict output to
h3 headings. The default value is
6, show all headings.
Relative vs. absolute URLs
The default output uses same-page relative URLs (e.g.
href="#id_name"), which will only work correctly in an individual article context. To get absolute (full) URLs instead, set the
full_url attribute to
true (or any value other than
If you use a
base tag to point to the site root (or anything other than the current page), you will also need to use full URLs. (N. B., such usage of
base is, strictly speaking, incorrect.)
ul (the default value) or
ol, and if the article has different levels of headings, the table of contents will be a nested list. For example, given the following article headings (shown in Textile):
h2(#foo). Foo ... h3(#bar). Bar
the plugin will produce, using default attributes:
<ul class="toc"> <li><a href="#foo">Foo</a> <ul> <li><a href="#bar">Bar</a></li> </ul></li> </ul>
For this nested output to make sense, the article’s heading structure must also make sense. In particular:
- do not jump upwards more than one heading level at a time (e.g., go directly from
- the first heading should be at the lowest heading level (e.g., if the first heading in the article body is
h2, there should not be any
h1s in the article body)
Because the plugin ignores headings with no id attribute, you could get unexpected results (and possibly XHTML validation errors) if you are inconsistent about assigning id to headings.
The plugin runs a
preg_match_all search on the article’s HTML body, and another
preg_match on each heading. Theoretically this could be a performance concern in some situations, particularly in an article list context.
This plugin is very similar to the
cbs_article_index plugin (didn’t realize this when I wrote it), but with more options for output and control.
Version 0.1.5, 2017-02-15
- Textpattern 4.6 compatibility update
Version 0.1.4, 2009.4.26
- Minor code cleaning
Version 0.1.3, 2008.2.03
- Code cleaning, plus valid XHTML output even for articles with unsemantic heading structure
Version 0.1.2, 2008.2.03
- Fixed bug (design flaw, actually) re nested list output: thanks to Dejan for spotting this
Version 0.1.1, 2008.1.29
- Fixed bug re headings containing HTML tags
Version 0.1, 2008.1.26
- Automatically generate a linked table of contents for an article
- Nested output for (X)HTML lists
- Option to filter results with the
- Option to use full URLs