Example: Hierarchical and Sequential TOCs

www.altova.com Expand/Collapse All Print this Topic Previous Page Up One Level Next page

Home >  SPS File: Advanced Features > Table of Contents, Referencing, Bookmarks >

Example: Hierarchical and Sequential TOCs

An example SPS file to demonstrate the use of TOCs, called Chapters.sps, is in the (My) Documents folder, C:\Documents and Settings\<username>\My Documents\Altova\StyleVision2019\StyleVisionExamples\Tutorial\TOC. This SPS is based on a schema that defines the content model of a large chapter-based document. The schema structure is shown in the screenshot below and can be viewed in the Schema Tree window of StyleVision when you open Chapters.sps.




The document element is helpproject, which contains a child topics element. The topics element can contain an unlimited number of topic elements, each of which can in turn contain descendant topic elements. The first level of topic elements can be considered to be the chapters of the document, while descendant topic elements are sections, sub-sections, and so on.


The SPS contains three TOCs, located at the top of the document, in the following order:


1.Chapters at a glance, which lists the names of each chapter (the first-level topics).
2.Chapters and their sections, which lists each chapter with its descendants sections (first-level topics, plus each topic's hierarchy of sub-topics down to the lowest-level topic, which in the accompanying XML document, chapters.xml, is the third-level topic)
3.List of images, which is a flat list of all images in the document (except the first), listed by file name.


SPS structure

Before considering the TOCs in detail, take a look at the structure of the design. Notice that the main template (with the green $XML tags) contains the TOCs. The rest of the main template specifies, through the rest-of-contents instruction, that global and default templates are to be applied.


The TOC definitions are in the global templates for topic and image. In the global template for topic (screenshot below), a TOC level has been created on the topic element, and a TOC bookmark has been created within the header child element (but outside the para element).




Since the topic element is recursive, the TOC level and the TOC bookmark will also recurse. This means that, at the first recursion, a new hierarchically subordinate TOC level and and a new TOC bookmark is created. This process continues for each descendant topic, thus creating a hierarchy of descendant TOC levels, each with a corresponding TOC bookmark. Since the formatting of the header (the topic title) for each TOC level is to be different, we have enclosed each level within a separate branch of a condition with three branches. Each branch tests for the TOC level at which a topic occurs: first, second, or third level.


Notice that hierarchical numbering (num-lvl) has been inserted within the level. This is done by right-clicking at the required location and selecting Insert Table of Contents | Hierarchical Numbering. The effect is to insert the correct hierarchical number before each topic title in the document's text flow, for example, 3.1 or 4.2.3.


TOC descriptions

Given below is a brief description of each TOC and the points to note about them.


Chapters at a glance: Select the TOC bookmark in the global template for topic. In the Properties sidebar (screenshot below), notice that the entry text has been set to be constructed using an XPath expression. When you click the Edit button in the value field of the Text from property, you will see that the XPath expression has been defined as para. This means that the contents of the para child of header (since the TOC bookmark has been inserted within the header element) will be used as the text of the TOC item.




The TOC template itself (screenshot below) contains one level reference (levelref) tag_TOCRefLevelTag, and the TOCref within that levelref tag_TOCRef3 has been set to select TOC bookmarks named MyTOC within the scope of the current level only—which is the first level. As a result, TOC items will be created only for first-level topics.




Notice also that the numbering has been defined as hierarchical numbering.


Chapters and their sections: In this TOC (screenshot below), notice that three nested levelrefs have been defined, each containing a TOCref for which the scope is the current level.




Since each TOC item is contained in a div block, formatting properties (including indentation) can be set for the block.


List of images: The list of images is a flat list. First of all, consider within which levels images will occur in the instantiated document. The image element is a child of the para element. Since levels have been created on topic elements, image elements will occur within the first, second, and/or third levels of the document. There is therefore no need to create any level for the image element.


In the global template for image, the condition (see screenshot below) enables separate processing for (i) the first image (which is presented in this example), and (ii) the other images (which, for purposes of economy, are not presented in this example).




Notice that the TOC bookmark is placed only within the second branch of the condition; this means that the images selected in the first branch are not bookmarked. Also, the sequential numbering (num-seq) of the images, inserted with Insert Table of Contents | Sequential Numbering, will start with the second image (because the first image is selected in the first branch of the condition). Another feature to note is that the numbering can be formatted, as has been done in this case. To see the formatting, right-click (num-seq), and select Edit Format. In the dialog box that pops up, you will see that the formatting has been set to 01, indicating that a 0 will be inserted in front of single-digit numbers.


In the TOC template for images (screenshot below), notice that there is a single TOCref identifying bookmarks named images, and that this TOCref is within a single levelref. The scope of the TOCref (editable in the Properties window when the TOCref is selected) has been set to: current level and below. The current level, determined by the levelref, is the first level. The levels below will be the second, third, and so on. In this way, all images from the first level downward are selected as items in the TOC.




Since the selected numbering is sequential, the images are numbered sequentially in a flat list.




© 2019 Altova GmbH