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 param1=valuea; param2:valueb; param3: valuec;]

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)

Example
[toc hidden=true;]

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>;

Example
[toc title=Summary;]

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>;

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

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.