Table of Contents Settings
Filter Configuration
At this point, most of the Table of Contents configuration is done in the Table of Contents filter.
This means multiple Input formats allow you to make use of several different configurations.
First, go to the Input formats screen.
Administer » Site configuration » Input formats
In the list, check the Table of Contents filter. The Assign an ID to each header should NOT be selected if you are using the Table of Contents with that filter. Otherwise, each header will be parsed twice (it is safe, computationally and visually, but useless!)
Save your changes, and go back to that Input format (unfortunately, Drupal 6.x takes you out of the Input format when saving the format selection.)
At the top, click on the Configure tab. Among the different configuration, one is the Table of Contents configuration. Open the field set by clicking on the title if it is closed, and choose the different configuration options as described below.
Once done, make sure to Save your changes.
Table of Contents Configuration
The Table of Contents includes many flags and other fields. The following explain each one of them and the possible interactions between the different options.
Table of Contents On/Off features
Hide the table of contents tags
When this flag is checked, all the [toc] tags are removed from the pages using this filter. The tags have no effect.
This feature is used when someone decides to not use tables of contents anymore and does not have the time to edit each page to remove the tags.
All the other settings will be ignored when this flag is turned on.
IMPORTANT NOTES
Remember that this is only in this one filter. If you use multiple filters, you may have to do the same in each filter.
Whether an automatic table of content should be added
By default, no Table of Contents is added to your pages unless you include a [toc] tag.
This option let you choose when a Table of Contents is added to your pages.
The Table of Contents can be placed at the top or at the bottom.
You will have to indicate how many headers need to be defined in your pages before a Table of Contents is added in this way. This option is defined below.
Number of headers before an automatic table of content is added
This option is used only if one of the automatic Table of Contents feature was selected.
This number is used to know whether the Table of Contents should be added to your page or not. The filter first runs through your page to determine the number and add identifiers to all the Header defined in the page. If the result is equal or larger than the Number of headers before an automatic table of content is added, then the Table of Contents is added.
Remove Table of Contents tags from teasers
This is certainly the most controversial feature of the Table of Contents.
This option let you decide whether the module automatically creates the teaser in order to add the option to the teaser. This is important if you do not want to have the Table of Contents include a summary in the teaser. The problem of adding the Table of Contents in the teaser is that it parses the teaser only (not the full node) and thus it is generally quite incomplete.
Note that this feature has the unexpected side effect of creating the teaser and this often throws off the users of Drupal who are not used to see a separate teaser from the rest of the page content. Even me, I seldom use it in some circumstances such as when I define a product with an icon.
If you think that you never ever use the teaser, notice that Drupal will automatically create them for you. If you do not have any links to a place with teasers, then it probably is okay to ignore them and thus not turn on this feature.
Table of Contents Security Options
Allow users to override the settings within the table of contents tag itself
By default, all users will be allowed to override the Table of Contents settings.
Uncheck this flag to prevent users from changing the Table of Contents settings from the [toc] tag itself. The settings will still be read, but ignored.
See the [toc] tag documentation for more information about the available options.
Ensure title is safe (i.e. use check_plain() to avoid XSS attacks.)
This option is set by default and should probably always be left that way on any site where more than one user has edit permissions.
When not checked, and the users are allowed to override settings, then a user can enter a [toc] tag with HTML. Although the HTML should be parsed by your other filters before the Table of Contents is reached, for stronger security, we also call check_plain() by default. This flag prevents the module from calling the check_plain() function.
Table of Contents Box
Table of Contents Title
The Table of Contents has a default title that can be changed here.
It can also be changed within the [toc] tag if you allow your users to do so.
List Type [REMOVED since v3.7, see Numbering below]
Defines the HTML tag used to create the Table of Contents list.
This can be set to Ordered list or Unordered list.
WARNING
The Ordered list feature means that the module generates a list using the <ol> tag. That tag has the side effect of adding numbers in the front of each item. These numbers are automatically added by the user's browser. If you prefer to use the module numbering capabilities, you must select Unordered list here or you will get double numbering (see Can't find doc_table_of_contents_known_issues to include!)
Minimum heading level
Define the minimum heading level used in your Table of Contents.
The default is H2 since that's what expected in your pages, H1 being used for your titles. Some websites may use H2 for another purpose and thus may ask Table of Contents to start at H3 or more.
The minimum heading level must be smaller or equal to the maximum heading level.
IMPORTANT NOTE
This minimum is not taken in account when the headers are automatically numbered by this module. This means numbering starts with the first header encountered and increments as required ignoring the minimum and maximum declarations (see Can't find doc_table_of_contents_known_issues to include!)
Maximum heading level
Define the maximum heading level used in your Table of Contents.
The default is H3 because most often you do not want to show the full depth of your document in your Table of Contents.
The maximum heading level must be larger or equal to the minimum heading level.
IMPORTANT NOTE
This minimum is not taken in account when the headers are automatically numbered by this module. This means numbering starts with the first header encountered and increments as required ignoring the minimum and maximum declarations (see Can't find doc_table_of_contents_known_issues to include!)
Include link to hide/show table of contents
Whether the link used to hide and show the Table of Contents should be included. By default it is.
This feature makes use of some JavaScript. If you write a website that should not make use of JavaScript (or very minimal use of it,) then you should turn this feature off.
IMPORTANT NOTE
The HTML Filter removes <script> tags. This option will not work when the Table of Contents filter is placed before the HTML Filter, or any other similar filter.
Start with the table of content collapsed
When the hide/show capability of the Table of Contents is turned on, it is possible to ask the system to hide the table at the start. Users can then click show to see the table.
This feature makes use of some JavaScript to hide the table on the client's machine. In other words, if the client does not have JavaScript, the Table of Contents will appear opened and the hide/show links not made available.
Table of Contents Headers Handling
Select what is stripped from the header titles
XML allows for many characters in a tag identifier. By default, we remove and replace some of the character in an automated way. You may remove more characters to make the identifier compatible with other sub-systems such as JavaScript or VisualBasic (ASP).
The XML identifiers can be composed of:
ID and NAME tokens must begin with a letter ([A-Za-z]) and
may be followed by any number of letters, digits ([0-9]),
hyphens ("-"), underscores ("_"), colons (":"), and periods (".").
The module ensures that the XML standard is respected. The other characters that you can remove are:
- All the digits (0-9)
- All the dash characters ("-")
- All the period characters (".")
- All the underscore characters ("_")
- All the colon characters (":")
By default, you should not have to chagne these flags. To use the identifier in JavaScript code, make sure that the dash, period and colon characters get removed.
The option uses the text defined between the start and end tag of the header as the default text for an undefined identifier.
WARNING
The module ensures that all the identifiers are unique within the page (if defined in your HTML Drupal template, then it won't be seen.) However, the characters of existing identifiers are not checked for validity. You are responsible for those.
IMPORTANT NOTE
This feature also runs when using the Assign an ID to each header filter. For this reason, you should not assign both filters to the same Input format.
Identifier introducer
When the identifier cannot be generated from the content of the header tag or the feature is turned off, a default identifier is created. That automatic identifier is the concatenation of this identifier introducer and a number.
Identifier and number separator
The identifier introducer is followed by this separator and then a number.
The separator can be set to any character that is a valid HTML identifier character (although at this point the module does not prevent you from using invalid characters.)
If you select the section number as the extension of the identifier introducer, then each section number will also be separated by this separator.
The default separator character is the dash (-). Usual characters are dash (-), underscore (_), period (.) and colon (:).
Use the underscore when these identifiers are also manipulated in JavaScript.
How to generate missing header identifiers
Whenever a header is found, the filter searches for its identifier (id="..."). If undefined, the identifier is automatically generated by the Table of Contents filter.
The possible options are as follow.
Use header title
This option means the module uses the text between the opening and closing header tags. This works for most latin languages since we can transliterate the accentuated letters and double letters such as ß or œ.
However, for Asian languages and any other script language, the transliteration does not work and most of those letters are not allowed in identifiers. In that case, this choice is not a good choice.
Create a random identifier
This option uses the identifier introducer followed by a random number. If you do not number your headers and do not want to have some implied order via the identifiers, this may be a good choice.
WARNING
Each time the page is regenerated, a different identifier will be generated. Users will not be able to create links with to those anchors.
Use the "Identifier introducer" and an incrementing number
This option uses the identifier introducer followed by a number. The number starts at 1 and is incremented by 1 each time an anchor is found.
This is a good choice if you do not otherwise number your anchors.
Use the "Identifier introducer" and the sections
This option is very similar to the previous one, but instead of an incrementing number, the current section numbers are used. Thus, when header 3.5.2 is being parsed, the numbers 3, 5 and 2 are used in the identifier. The identifier separator is used between each number. By default, header 3.5.2 would generate the identifier: header-3-5-2.
Custom: call module_invoke("tableofcontents", $id) -- requires a module or theme that understands this API.
This option uses a callback that another module must implement. At this time, there is no known helper module to generate a header identifier. If you create one, please post a comment below so I can add a link to its project page.
This means this option should not be used at this point.
List of tags allowed in table headers
This option let you specify a list of tags to be kept in the Table of Contents titles. You may clear that list completely to just remove all the tags.
By default, all inline tags are accepted.
NOTE
Some people pointed out that some of the tags listed are deprecated. First, note that most, if not all, browsers support them. Also, if you cannot otherwise use those tags (i.e. FCKeditor uses <strong> instead of <b>) then it does not matter since those tags will not be in your page at all (the Table of Contents does not add those tags to your titles.)
Table of Contents Other Modules Support
[Upload] Show attachments in the table of contents
Whether links to your file attachments should be added at the bottom of your Table of Contents.
The title used when the file was added to the page is used as the title in the Table of Contents. If not available, the filename is used.
[Comments] Add the comments to the table of contents
When this option is selected, the subject of all the comments attached to this page are added at the bottom of your Table of Contents. Note that some of those comments may not appear on your page. Those links may not work properly.
This feature should be used only on websites with a low number of comments.
[Comments] Select header level at which comments start
When you choose to add comments to your Table of Contents, you want to present them in that table as if at a specific level. By default, H2 is chosen which is the same as the minimum level. Any level can be used, although remember that an comment at a level higher than the maximum level allowed in this Table of Contents will not be included.
[Print] Show the table of content on Print pages
Select whether the Table of Contents should be completely removed from Print pages or shown but without links.
The default is to completely hide the Table of Contents from Print pages.
Note that the Back to Top links are always removed.
Table of Contents Back to Top Links
Back to top label
This field let you enter the label to display as the link to go back to the top.
NOTE
At this time, the label uses a CSS background image that cannot be clicked. This should be fixed in a future version by letting users enter HTML in this box, including an image if they wish.
Back to top location
Determine where the Back to top label is inserted.
You may insert right under the header (i.e. <h2>My Title</h2><div>Back to top</div>).
You may insert it right at the end of the block (just before the next header.)
You cannot insert it in both locations since you'd then have one right before and one right after each header.
Minimum level where Back to Top appears
The system checks whether the current level being closed is smaller than this value. If so, no link is added. For instance, if you have headers from H1 to H4, you may want to add links only at level H2 and H3. This option would be set to H2 for this purpose.
Maximum level where Back to Top appears
The system checks whether the current level being closed is larger than this value. If so, no link is added. For instance, if you have headers from H1 to H4, you may want to add links only at level H2 and H3. This option would be set to H3 for this purpose.
NOTE
If the Maximum is set to a value smaller than the Minimum, then no Back to Top link will be added. This is another way to turn off this feature.
Back to top anchor
By default, the Back to top link sends you back at the very top of the Table of Contents. However, it may be preferable to send users a little higher. If you are using only one theme on your website, and it has an identifier such as node-content, then you can specify that name in this box.
To know what names are available, right click on your page and select See Page Source. Look at the HTML tags before the Table of Contents and choose the name defined in the id="..." parameter.
Scroll back to the table of contents
jQuery allows for scrolling your pages. This flag let you choose to do so with your Back to top links.
If you audience is likely to have lower end computers, then it is discourage to use such a feature.
Table of Contents Numbering
Numbering method
Choose how your headers and titles in your Table of Contents will be numbered.
Note that a flag needs to be turned on for the headers to also be numbered.
The numbering method cannot be changed in the [toc] tag.
WARNING
The Ordered list feature means that the module generates a list using the <ol> tag. That tag has the side effect of adding numbers in the front of each item. These numbers are automatically added by the user's browser. If you prefer to use the Numbering method, you must select Unordered list in the List Type or you will get double numbering (see Can't find doc_table_of_contents_known_issues to include!)
No number
Do not number headers or titles.
Browser numbering (<ol> tag)
Use the <ol> tag (instead of <ul>) and let the browser add numbers. There is no good control for those, but in some cases this may be preferable.
Numbers 1., 2., 3. (like <ol>)
This numbering is just what you'd get with the <ol> tag. However, this enables the module to also number the headers.
Sub-numbers 1., 1.1, 1.2, 2., 2.1, 2.2, etc.
Advanced numbering without the zero. In other words, 1., 2., 3., etc. do not have an ending zero.
The numbering is what you'd otherwise expect. Note that the depth is not limited. So all 6 header levels may be used.
Sub-numbers with zero 1.0, 1.1, 1.2, 2.0, 2.1, 2.2, etc.
Advanced numbering with the zero. As you can see 1.0, 2.0, 3.0, etc. have an ending zero.
The numbering is what you'd otherwise expect. Note that the depth is not limited. So all 6 header levels may be used.
Add the number to the headers
When using an option other than No Number in your Numbering method, you can also have the module add those numbers to your headers.
Note that this does not work with the Ordered list option of the List Type settings. You need to make sure you selected Unordered list instead.
Numbering mode
Choose the type of numbers you want to use for your sections.
You can choose between, decimal, roman, letters, and hexadecimal. The roman characters and letters can be either lower or upper case.
IMPORTANT NOTE
At this time, you can only specify one numbering mode. If you have needs for different numbering schemes at different levels, then this feature is not (yet) enough.
Numbering prefix
Enter the character you want at the beginning of your numbers. This could be a bullet point, an arrow, an opening parenthesis or square bracket, or nothing (the default.)
Numbering separator
Enter the character you want between each number. In most cases, you want to use a period. Some Table of Contents use a dash (-), colon (:), or an underscore (_). When the prefix is an opening parenthesis and the suffix is a closing parenthesis, you could use a slash as the separator: (1/2/3).
Numbering suffix
Enter the character you want after all the numbers. The default is a period. A usual character is a closing parenthesis, especially if you used an opening parenthesis as the numbering prefix.
