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 é (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.