This Joomla! 1.5.x plugin displays a table of contents for articles that are structured using headings.
New features in version 1.2:
- Headings are now allowed to contain extra markup/newlines
- The plugin can be disabled on a per-article basis
- ToC items are indented to match the heading hierarchy
- A new option allows to replace the ToC by a drop-down menu
Direct link: plugin-content-toc-1.2.zip
If you enjoy this plugin, please take the time to post a review on the Joomla! Extension Directory!
Install this extension like any other in the Extensions > Install / Uninstall screen (see illustrations below). Joomla! extensions can be uploaded as a package or installed directly from a remote location (which is the easiest).
2.2. Enabling the Plugin
Joomla! does not enable the freshly installed extensions by default. In Extensions > Plugin Manager, just click on the disabled red icon in the plugin list to fix that.
At this point the plugin is functional and you can see its effects on articles that have headings. Headings mean that instead of manually formatting titles and subtitles in your documents (bold, larger font), you declare them as such and let the site theme style them. This is smarter for several reasons:
- You focus on the structure of your documents, not how they look
- You can change the look 'n feel of your site in a single place rather than going through every article
- Automated tools such as this plugin or Google understand the structure of your documents and can act on it properly
How to add headings to your documents? In the default TinyMCE editor, this is done using the --Format-- menu and one of the Heading X entries. If you are not using TinyMCE, use whatever produces h1, h2, ... tags in the underlying HTML.
The results are shown only on the user site, not in the preview window. By default, the following happens (these effects can be customized in the plugin configuration page):
- Headings are numbered by level, starting at 1.
- The Table of Contents is shown in the top-right corner of the article area with the caption Article index. It is built from the article structure with links to the corresponding headings.
2.4. Global Configuration
If you follow the steps outlined in Enabling the plugin but click on the plugin name rather than on the enable/disable icon, you will reach the plugin configuration page. There, the Plugin Parameters box on the right allows the enable or disable part of the plugin features. By default, all are enabled.
2.4.1. Enable Plugin
Globally enable or disable all the the plugin effects at once.
2.4.2. Add Numbering to Headings
Edit the headings in the ToC and article body, prefixing them with a numbering reflecting the hierarchy (see this article for an example.)
2.4.3. Display the ToC
If you want Article ToC to only add numbering to your articles, you can hide the ToC block completely.
2.4.4. Indent the ToC items
A new feature of version 1.2 is to indent the headings in the ToC block to reflect the hierarchy. If you prefer the old behavior, this is how to disable it.
2.4.5. Display Mode
Some users have requested to provide the ToC as a drop-down menu instead of a large block of links.
2.5. Per-Article Configuration
2.5.1. Disabling the Plugin
The plugin can be entirely disabled for a single article by adding the following line to your HTML source:
<!-- ArticleToC: enabled=no -->
3. Bugs and Limitations
3.1. Incompatibility with Other ToC Plugins
The article index box is a single Joomla! feature used by any number of plugins. In other words, other plugins like Content - Page Navigation will not play nice with this one if more than one triggers for a given article.
Both can be enabled however, as long as they don't do anything - for Page Navigation this means not finding a Pagebreak tag (hr), for Article ToC this means no heading, etc.
3.2. Crude per-Article Options
The mechanism for per-article options (adding special comments to your HTML source) is a hack. We did not manage within a reasonnable timeframe to find how to add extra article parameters, displayed in the menu (is that even possible?) Send us a patch if you know better!
4. Authors and Copyright
Article Table of Contents is copyright Straton IT, released under the GPLv2.
Article Table of Contents version 1.2 has been brought to you by Alexandre Storoz and
5. Version and History
This article documents Article Table of Contents version 1.2, released in October 2009.