Web pages can get very long, especially in areas such as reporting or documentation. Sometimes, dividing long pages into subpages improves the readability, but it may also be counterproductive, e.g. with API documentation articles whose readers don’t want to jump back and forth to find the pieces of information they need.

To improve the usability of long pages, the first thing that comes to mind is anchor navigations. Such link lists at the top of a page (or wherever appropriate) enable readers to obtain an overview of the page contents and navigate to any of the sections starting with a headline. As an editor, you don’t want to build and maintain such navigations manually, do you?

This tutorial provides you with an automatic anchor navigation widget. It determines the headlines on the page to which it is added, and creates a link list from their content and anchor IDs. Editors can specify the style of the headlines the widget should take account of (e.g. “Heading 2”), and it also makes some basic styling options available.

Our widget is based on the Scrivito Example App, of course, but can be easily adapted to fit into any Scrivito-based web application that offers headlines (which don’t?).

Let’s start by providing the widget class and specifying the attributes we want the widget instances to have, a style attribute (in accordance with the HeadlineWidget’s style) for filtering the headlines by their hierarchy level, plus a small, a bold and a bullets attribute for letting editors adjust the appearance of the links:

If you additionally require navigations derived from headlines on deeper levels (e.g. “h4”), just add them to the values array of the style attribute as well as to the editing configuration below.

Next, for editors to be able to use the above settings, here’s the editing configuration that makes them available:

Now, let us explain how our widget component achieves what it is meant to. As indicated in the introduction, it first determines the headline widgets on the page concerned. It does this by calling getHeadlineWidgets.

Usually, all the widgets on a page are contained in a single attribute of the widgetlist type. Following a generic approach, getHeadlineWidgets first determines this attribute using the attributeDefinitions API. It then iterates this widgetlist to single out those headline widgets that have the specified style. On its way through the widgetlist, getHeadlineWidgets also takes care of embedded widgetlist attributes (of boxes, columns, etc.) and processes them recursively.

After determining the list of headline widgets that match the specified style and making sure that the list isn’t empty, the component renders the headlines inside a <ul> element in which it outputs a linked <li> item for each of them.

Congratulations, you’re done! Your “Anchor Navigation” widget should now be ready to be used.

For the generated link list to include headlines of more than one style, e.g. <h2> as well as <h3> headlines, you can use a multienum instead of an enum attribute and adapt the style condition in getHeadlineWidgets accordingly.