Table of Contents Overview

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.

Table of Contents tags and parameters

Syntax

Supported Tags

The module supports 3 tags that all generate a Table of Contents.

The most popular is now [toc] since it is easy to type and works in WYSIWYG editors.

The old tag was a comment: <!--tableofcontents-->. This is a very good choice if you are not using a WYSIWYG editor because if you turn off the Table of Contents module, the tags disappear automatically. Contrary to the other tags, this one can include spaces before the name. So <!-- tableofcontents --> works too.

IMPORTANT NOTE

This tag will NOT work when written as is in your WYSIWYG editor since the < and > characters are transformed to &lt; and &gt; identities. In other words, they won't be recognized as introducer and closer by the module.

The last tag supported is the capitilized [[TOC]] tag. This is to support pages coming from a Wiki like system where that very tag is used. That way, those pages are supported as is in Drupal.

Parameter Syntax

The <!--tableofcontents--> and [[TOC]] tags are automatically transformed in a [toc] by the filter prepare callback function. This is why the rest of the documentation references that tag and not the others. In all cases, the tag can be followed by a set of parameters (including the [[TOC]] tag although it is not conventional in the other system.)

Parameters are keywords. All the parameters must be followed by a value. The value is defined after an equal sign (=) or a colon (:) and ended by a semi-colon. Note that all spaces between the equal sign or colon up to the value are ignored.

The syntax is as follow:

   [toc param₁=value_a; param₂:value_b; param₃: value_c;]

The parameters and their possible values are described below.

Type of Values

Boolean (bool)

A boolean value represents TRUE or FALSE. You may use any one of the following values to represent TRUE or FALSE:

	TRUE	FALSE
Integer	1	0
Name	true	false

Integer

Any valid value such as 123. Most parameters do not accept negative values although they are otherwise accepted (i.e. -123).

String

Strings are currently accepted as is. Note that a string cannot include a semi-colon. However, it may include a square brackets ([ or ]) when used with the new tag (i.e. [toc].)

Note that when used with the comment tag, you cannot use the end of a comment combination: -->.

Mode

Modes are specific strings. The parameter defines the list of modes that work with it. For instance, a list can be set to ordered or unordered.

Supported Parameters

The following list was started as of 3.6. Some of the parameters may or may not be available in older versions.

NOTE

In this documentation, the parameters are always presented in lowercase. However, the case is ignored. Thus hidden, Hidden and HIDDEN all work.

hidden=<bool>; (synonym: hide)

The hidden parameter is used by the system to create a tag in the page teaser that hides the Table of Contents.

It is generally not useful in your pages unless the automatic Table of Contents option kicks in when you do not want it. This attribute prevents any other action and thus the headers will not be changed in anyway.

id=<string>;

The main identifier to use with the Table of Contents box. The default is "toc".

IMPORTANT NOTE

There can be only one item with the same identifier. The very first [toc] will get this identifier. Any others will not have any identifier.

title=<string>;

Set the name of the Table of Contents. This string appears at the top of the Table of Contents box.

In order to remove the title, set it to the special value <none>. Note that in this case the hide/show link is also removed.

hideshow=<bool>;

The Table of Contents uses a small JavaScript to hide and show the list of labels. It is possible to remove that link by setting this parameter to false.

collapsed=<bool>;

The Table of Contents can start collapsed. This works with the hideshow capability. Note that the module uses JavaScript to actually collapse the box. In other words, users who do not have JavaScript still see the box non-collapsed.

list=<mode>; [DEPRECATED in v3.7]

Set the list mode of the Table of Contents. This option will get deprecated in a future version once the other feature removes the need for this option.

The <mode> can be one of:

• ordered (synonym: ol)
• unordered (synonym: ul)

This mode defines whether the Browser generates numbers (ol) or not (ul).

IMPORTANT NOTE

Since version 3.7 this parameter is accepted by ignored.

attachments=<bool>;

Defines whether attachments should be listed in the Table of Contents.

minlevel=<integer>; & maxlevel=<integer>;

Defines the range of headers accepted in the Table of Contents. This has no effect on which headers are assigned an identifier in your page: all headers are always assigned an identifier (and are numbered when that option is turned on.)

<integer> is limited to a number from 1 to 6.

Limits

If there is a parameter that you think should be added, feel free to post an issue. Note that all parameters available in the Input filters configuration screen cannot be added to the tag. Especially, the automatic feature, putting the tag at the top or bottom (you can do that yourself with the tag anyway,) and whether overriding parameters is acceptable.

Only add identifiers and optionally numbers to my headers

Proposition

The Table of Contents module uses the headers to get generated. Each header gets a unique identifier when none were assigned manually. The Table of Contents module uses the text between the start and end tags as the title to show in the table of contents.

Very good!

Now, you may not want the Table of Contents itself, but you like the idea to have identifiers in all your headers. This can be useful to create in-page links (a link with an anchor, i.e. #some-name at the end of your URL.) It is generally annoying to have to enter the identifiers by hand for each header and you may make mistakes.

Another side effect from the Table of Contents module: it can be setup to assign a number to each one of your header. It starts at 1) and moves forward to 1.1), 1.2), 2), 2.1), etc. Note that you can select your own style as well.

Solution

The solution: use the Assign an ID to each header filter. Once the Table of Contents is installed, that filter will be available in each one of your Input format. Select it and you will get the similar features as with the Table of Contents filter.

NOTE

This is what needs to be done whenever you want to use Table of Contents Block (unless you want include an identifier by hand, in each one of your headers, for every page...)

Nice Hack1

If you want a Table of Contents on a few pages, but not that often, and also want to have identifiers assigned to headers, set both, the minimum and maximum headers, to H12.

Now the headers will be transformed by the Table of Contents filter but the resulting table will be empty (because none of the headers will match your default selection.)

Finally, when you have a page where you want to show a Table of Contents, enter the tag with the minlevel and maxlevel parameters set to values such as 2 and 3 respectively.

• 1. This is just a side effect of the different options offered by this module. It is not hacking the code, CSS or anything of the sort.
• 2. H1 is often used for your main page title and should not appear in your page content. You could also use H6 which is rather rarely used except in advanced references...

Create a Table of Contents from a View

Setup

There are, I'm sure, many different ways to handle views with the Table of contents.

Here is what I think is the easiest at the moment:

1. Create a view and include a Title field (which generates a header for the title, most likely <H2>)

2. Create a node and include the view in the node using the Insert view filter1

3. Select a filter on this node that includes support for Insert views and Table of contents

4. If the filter is not setup to auto-generate the table of contents, insert a toc tag in the content

Save the node and verify that the table of content appears.

IMPORTANT

a) The auto-generate features may require more headers before it generates your Table of Contents.

b) The Table of Contents setup may ignore the <H2> tag, make sure it incorporate the headers that are required with your view.

NOTE

This method assumes that the view being used does not require dynamically defined parameters.

• 1. Note that the Insert view filter was found to have some security issues. Use with care. The project home page has additional information about this module.

Adding a Table of Contents to a view with parameters

It is possible to add a Table of Contents to a view that has to accept parameters1.

In this case, you do not want to use the solution of including the view in a node (with the Insert view filter, see Can't find doc_table_of_contents_for_views to include!) because then you lose the capability of assigning different parameters to your view (although, if the number of parameters is relatively limited, you could create one page per set of parameters supported.)

So, here, we offer a solution for you to include a Table of Contents using your view template. Basically, it reformats the view output by passing it through the Table of Content filter. The filter requires a format number and the text to be filtered.

These two lines of code will prepend a Table of Content to the $rows text. The $rows text comes from the Views.

To append a Table of Contents, simply move the '[toc]' string after the $rows reference as in: $rows.'[toc]'

The module_load_include() call is necessary in case the tableofcontents.pages.inc file was not loaded.

The number 2 in the call to the _tableofcontest_replace_toc() function is the format identifier. The one main reason why you'd want to enter a specific format is to gain the flexibility of changing the Table of Content setup from the Drupal interface (from your Administer » Site configuration » Input format settings form.) Use the number 0 if you just want to use the default settings and what you specify in the view template, since it is possible to include parameters along the [toc] tag such as the title.

In this example I show how the table can be given the name My View and use <H2> as the minimum level.

• 1. Note that you need to write some PHP code. If you do not know how to do that, I'm afraid that this won't work for you. You may want to check out the Table of Contents and Insert view solution instead.

Upgrade from Table of Contents 2.x to 3.x

Make a Backup

DO NOT FORGET TO MAKE A BACKUP OF YOUR DATABASE & CODE.

That way you can come back to your previous version if anything goes wrong. So far, no one told me that they had a problem upgrading. Although version 2.x did not have any schema, the new module may modify nodes and generate incompatible tags.

Show stopper

Version 3.x has a new theme() scheme. It is much more powerful has it allows you to create your own header numbering, etc. However, if you already had a theme() overload in your theme, it will stop working until fixed.

Please, in this case, make sure to upgrade on a test system and see how and whether changes are required.

Upgrade procedure

Please, follow these steps one by one.

1. Did you make a backup of your database?

2. Disable the module from your website1

3. DELETE your existing tableofcontents folder

4. Extract the new version of the module

5. Enable the Table of Contents module on your website2

Enjoy!

• 1. Do no remove the tags from your nodes unless you do not want the table to appear there! You can safely keep those!
• 2. The Anchors module is gone. There are two modules: Table of Contents Filters and Table of Contents Block (new!) The Anchors filter is still available for those who want to use the Block. Otherwise, do NOT use it, it is a waste of processing time. That filter is named: Assign an ID to each header.

Table of Contents Known Issues

Various known issues with the Table of Contents module.

Teaser appear, FCKeditor accentuated letters,  Back to top arrow, Filters interaction (JavaScript removal,) headers numbering, double numbering...

A teaser was created automatically?!

One of the features in the Table of Contents filter configuration settings is named:

Remove Table of Contents tags from teasers

This box should NOT be set if you do not want the teasers to automatically be created.

The other two main reasons to get the tag automatically added are:

• The use of the If no [toc], then create the table automatically, and
• The [toc] tag is present at the start (in the auto-teaser area1) of your page.

There are several tests before the module adds the teaser to the node and happen the [toc hidden=1] tag to it.

1. Is this very flag Turned Off?
2. Is there a teaser already?
3. Is the Table of Contents filter not selected on that page? (i.e. page uses a format including the Table of Contents filter.)
4. Is there already a [toc] tag in the teaser, if not, is the [toc] tag manual only generated?

If the last answer to any one of these questions is YES, then the teaser is not added.

For instance, if you did not include a [toc] tag in your body and the process requires the tag to insert a table of content (i.e. the automatic table of contents addition is not turned on,) then the teaser will not be created.

FCKeditor and Accentuated Characters

Users of the FCKeditor2 who use accentuated characters, may run in that problem where the editor changes letters such as é into &eacute; (their HTML entity.)

Those changes by the editor interfere with the code used to generate the header identifiers.

To fix the problem, change the ProcessHTMLEntities as following:

  FCKConfig.ProcessHTMLEntities = false;

Similarly, for the CKEditor3 you want the following:

  CKEDITOR.config.entities = false;
  CKEDITOR.config.entities_latin = false;
  CKEDITOR.config.entities_greek = false;

More info: ProcessHTMLEntities.

Back to top arrow

At this time, I use a background image via CSS to add the Back to top arrow.

This allow for you to easily switch the image, but it means the image cannot be clicked to go back to the top.

A later fix will be to offer you a text area where you can enter the Back to top HTML code. In that case, you could point to whatever image you'd like and the whole thing can be wrapped in an anchor so a user can click the arrow (or whatever other graphics) too.

Filters interaction & the [hide]/[show] feature

The Table of Contents module makes use of a small JavaScript snippet to get the [hide]/[show] link to work. Some filters will remove the JavaScript code for your safety...

Especially, the HTML Filter will remove most of the HTML tags that are not considered safe.

In order to avoid this problem, go to Administer » Site configuration » Input format, click on the format using the Table of Contents filter, click on the Rearrange, and move the Table of Contents filter after the HTML Filter or any other offending filter. Don't forget to Save once the filters are properly ordered.

Headers numbering

When asking the Table of Contents filter to add numbering to your headers (tags H1 to H6 found in your page,) it will do so to all the headers whether or not the [toc] tag or the Table of Contents settings specify a minimum and maximum header.

This means the resulting numbers in your Table of Contents may not look as expected (although they will be correct in the sense that the corresponding numbers will be used.)

For example, if the minimum level is set to H2, and you have one H1 tag at the start of your page. In your Table of Contents, the number start at 1.1 instead of 1.0, and the next H2 header is shown as 1.2, instead of 2.0 as you would otherwise expect. To palliate to this problem, remove the H1 tag or change the minimum level.

Note that the title of the page (often presented using H1) is not included in your Table of Contents, so that should have no effect here.

Levels mismatch

Note that the module expects your document to be well formatted. This means the headers should start at a given level, the level should increase one by one and never decrease to less than the first header found. Thus, if the first header is an H3, we should not find an H2 later.

At this time, there is no real way to avoid these two problems other than looking at your table of contents for consistency. Later, we may add some code to generate a warning whenever such malformed pages are detected.

Double numbering

The problem

I will probably fix this problem at some point, but to keep the old system working as it was, I kept the option to choose between <ul> and <ol> separate from the advanced module auto-numbering feature.

This means you may choose two numbering systems at the same time: the <ol> + the module numbering. This means you will see the numbers overlap. The black numbers are the <ol> numbers added by the browser. Those numbers are not active and thus you cannot click on them to go to the specified point.

The blue numbers are part of the link and were added by the PHP code of the module. It is much more powerful as you can add several levels (1.0, 1.2, 1.2.3, 1.2.3.4, etc.) However, the module does not (yet) detect whether both options are used simultaneously. Therefore, the administrator has to do the setup properly.

The Solution

This was fixed in the newest version of the module. Upgrading may be your best solution.

There are two places in the table configuration that let you choose the type of list that you want.

Remember that the table of contents settings are found with the Input format configuration screen. This is found under Administer » Site configuration » Input formats, in that screen, click on the format using the table of content filter, then click on the Configuration tab.

The first is near the top. When that one says Ordered list, the module uses the <ol> tag. This means your browser will add the black numbers. Note that the Ordered list numbering capability only happen in the Table of Contents. The headers will not be numbered with this option.

The Unordered list makes use of the <ul> tag. This means your browser adds a bullet point instead of a number. However, the CSS coming with the module will automatically remove the bullet points for you. The result is a list without any bullet or numbers as far as the browser is concerned.

Further below in the Table of Contents settings, you will find the Numbering method entry.

This entry can be set to No Numbers. That is the selection that you want if you used the Ordered list in the previous selector. This means only the Browser numbers will appear.

The Numbering method can be set to anything else when the List Type was set to Unordered list. In this case you can also ask the module to attach the numbers to the headers in your page.

When the Numbering method is set to No Numbers, and the List Type is set to Unordered list, then absolutly no numbers are assigned to each entry.

In our case, we changeed the List Type from Ordered list to Unordered list and got this result:

No Table of Contents appears

The minimum and maximum header specifications may exclude all the headers that exist in your page. In that case, the Table of Contents would be empty and thus the filter outputs nothing.

Please, verify all your settings to see whether you have headers at all levels and if not try to add others to trigger some output. You may also use the minimum and maximum parameters:

   [toc ... minlevel=1; maxlevel=6;]

That will resolve the problem on the very page. The default minimum and maximum levels can be changed in your Input filter settings.

Header Level Mismatch (Older versions)

In older versions (2.x and older,) there was a problem with the table generation and different levels.

In fact, if you told the module that the minimum level was H3, but the modules finds an H2 tag, then you would have a negative level.

Similarly, if you said that the minimum level was H3, but the first header was an H4, then the table title entry for that H4 would be improperly indented.

Please check out the README documentation coming with the module for more detailed information on this problem.

Table of Contents errors appear, why?

If you are using a WYSIWYG editor, you may enter some invisible HTML code inside your [toc ...] tag. For instance, the HTML could end up looking like this:

   <p>[toc ... minlevel=1; maxlevel=6;<div style="display: none;">&nbsp;</div>]</p>

The <p> tag is normal, it should automatically be removed by the Table of Contents module. However, the <div> tag is there, but hidden. It will generate errors because the Table of Contents will detect what looks like parameters. To fix the problem, verify your page HTML code and delete anything that appears within the square brackets ([ and ]) and does not belong.

Tweaking the order of my filters has no effect, why?

The Table of Contents module uses the parser in three cases:

• Filtering

The filter is the default expected use of this filter. In most cases this is enough and works well. In this case, the order of your filters will affect the final outcome of your content.

• [vtoc] tag

The "v" tag is parsed by the tableofcontents_nodeapi() function when called with the 'view' operation. This means it happens after all the filters. Obviously, this means the order of your filters has no bearing on when the parser is applied in this case.

If you have a problem with a [vtoc] tag, you can try to change the module weight (that's the weight value found in the system module.) This may have other side effects though.

• Block

When using the Table of Contents block extension, it calls the parser too. The parser does not add a table of contents to the node, however, it adds the header numbers.

• 1. You can change the size of your automatic teaser from the default 600 characters to something smaller. (Look under Administer » Content management » Post settings) Although, in general, it is rare that you'd write so much before your Table of Contents. Some people also like to add the table at the bottom of the page. In that case, pages that are long enough will have their tag so far below that it will never appear in the teaser. Note that does not prevent the teaser creation if the automatic table feature is used.
• 2. The FCKeditor may not be the only editor affected by this problem. Other WYSIWYG editors may transform some characters in unexpected ways. So far, though, no one reported such a problem here.
• 3. The CKEditor is the new version of the FCKeditor and is now available for Drupal 6.x.