Pier Table of Contents

Pier Table of Contents Contents:


Problem Description

Pages in Pier can have a table-of-contents based on the header items (such as Problem Description on this page). Another TOC is at the top of this page.

As pages get larger, it makes sense to break them up into both separate pages as well as sections with their own heading. Unfortunately the TOC widget doesn't always work for the page that it calls home.

Large Page Example

Consider the following large page:

*value:toc*
!Problem Description
Text
!!Sub Problem
Text describing what else is wrong.
!!Another Related Problem
Text and links to different problems
!Failed Solution 1
What didn't work
!Failed Solution 2
What else didn't work
!Working Solution
The quick answer.

If Problem Description needs to be broken into another page with the sub-problems, it would be useful to have a way to step into the sub-problems in the table-of-contents.

Existing Behavior

Unfortunately when a page is broken up, a TOC on a sub-page when embedded in the larger page does not display the TOC for the sub-page. If the large page example above is broken up as:

*value:toc*
!Problem Description
*Problem Description|embedded=true*
!Failed solution 1
What didn't work
!Failed Solution 2
What else didn't work
!Working Solution
The quick answer.

With the page Problem Description having:

*value:toc*
Text
!Sub Problem
Text describing what else is wrong.
!Another Related Problem
Text and links to different problems

Then the page will be displayed as:

  • 1 Problem Description
  • 2 Failed Solution 1
  • 3 Failed Solution 2
  • 4 Working Solution

Problem Description

  • 1 Problem Description
  • 2 Failed Solution 1
  • 3 Failed Solution 2
  • 4 Working Solution

Text

Sub Problem

Text describing what else is wrong.

Another Related Problem

Text and links to different problems

Failed Solution 1

What didn't work

Failed Solution 2

What else didn't work

Working Solution

The quick answer.

The problem is that the TOC is listed twice because the PRTocRenderer runs over the main page twice.

Failed Attempt

A first attempt was to update the renderer to always assign visitors to start on their owner. This caused a walkback on displaying a simple page.

Another Solution

Another attempt was to add PRTocRenderer>>start:in:on: so it starts on the in: argument's owner and ignores the original start argument. So far the test pass and pages are displayed correctly.

Posted by John Borden at 24 December 2019, 4:52 pm with tags Pier link