%META:TOPICINFO{author="RonDuPlain" date="1106768760" format="1.0" version="1.1"}% %META:TOPICPARENT{name="TWikiVariables"}%

%TOC% Variable Issue

• The Variable
• The Problem
• A Workaround
• Note (A Potential Gotcha)

The Variable

The %TOC% variable is excellent for quickly providing (and updating) navigation links for a document. There is, however, one issue that I experienced when using it. Suppose you have a document that lists properties of similar objects, and you wish to use WikiSyntax headers in conjunction with %TOC%.

It seems simple enough at first. You type out your headers for each object:

---+!!Staff List

%TOC%

---+++Joe

---+++Sally

---+++Ron

Then, you add subheaders for information that you are going to add for each object.

---+++Joe
---++++Basic Information

---++++Specialty

---++++Notes

Filling in the information for each object, you have a completed document in no time.

The Problem

If you look closely, you may find that the links in your table of contents may not perform as you expected. If you click "Basic Information" under Sally's listing in the table, you may end up at Joe's entry. %TOC% creates its links from automatic anchors that are created from the WikiSyntax headers. Since both Joe and Sally have a subheader titled "Basic Information," the anchors have the same name, and web navigation will take you to the first anchor with a name that matches. The example below allows you to see the table of contents in action. Notice the issue with the anchors (which was present at the time of publication).

Staff List

• Joe
  • Basic Information
  • Specialty
  • Notes
• Sally
  • Basic Information
  • Specialty
  • Notes
• Ron
  • Basic Information
  • Specialty
  • Notes

Joe

Basic Information

Specialty

Notes

Sally

Basic Information

Specialty

Notes

Ron

Basic Information

Specialty

Notes

A Workaround

I am not certain if there is an official TWiki approach to this issue, but there are some workarounds that you can use.

An obvious workaround for this issue is to create your documents with only unique headers when using the %TOC% variable. However, perhaps you had planned your document to have similar subheaders and do not wish to change it. One possible workaround is to put comments after the subheaders in HTML syntax ("<!-- comment -->").

---+++Joe
---++++Basic Information<!--Joe Schmoe-->

---++++Specialty<!--Joe Schmoe-->

---++++Notes<!--Joe Schmoe-->

This will cause each anchor to have it's own label without adding any text to the document, allowing it to retain similar subheaders for each header and use the %TOC% variable. The example below shows the same page using this workaround. Notice the issue is no longer present with the table of contents.

Staff List

• Joe
  • Basic Information
  • Specialty
  • Notes
• Sally
  • Basic Information
  • Specialty
  • Notes
• Ron
  • Basic Information
  • Specialty
  • Notes

Joe

Basic Information

Specialty

Notes

Sally

Basic Information

Specialty

Notes

Ron

Basic Information

Specialty

Notes

Note (A Potential Gotcha)

Be careful using the anchors that TWiki creates automatically from the headers you make with this workaround.

example: [[#Notes_Joe_Schmoe_][See Joe's Notes]]

-- RonDuPlain - 26 Jan 2005