## 3.1.1 Navigation and Links

The `plasTeX.Base.LaTeX.Sectioning.SectionUtils` class has a property named `links` that contains a dictionary of many useful objects that assist in creating navigation bars and breadcrumb trails in the rendered output. This dictionary was modeled after the links described at http://fantasai.tripod.com/qref/Appendix/LinkTypes/ltdef.html. Some of the objects in this dictionary are created automatically, others are created with the help of the `linkType` attribute on the document nodes, and yet others can be added manually from a configuration file or command-line options. The automatically generated values are listed in the following table.

Name&Purpose
begin&the first section of the document
breadcrumbs&a list containing the entire parentage of the current section (including the current section)
chapter&the current chapter node
child&a list of the subsections
contents&the section that contains the top-level table of contents
document&the document level node
end&the last section of the document
first&the first section of the document
home&the first section of the document
home&the first section of the document
last&the last section of the document
navigator&the section that contains the top-level table of contents
next&the next section in the document
origin&the section that contains the top-level table of contents
parent&the parent node
part&the current part node
prev&the previous section in the document
previous&the previous section in the document
section&the current section
sibling&a list of the section siblings
subsection&the current subsection
start&the first section of the document
toc&the section that contains the top-level table of contents
top&the first section of the document
up&the parent section

Note: The keys in every case are simply strings. Note: Each of the elements in the table above is either a section node or a list of section nodes. Of course, once you have a reference to a node you can acces the attributes and methods of that object for further introspection. An example of accessing these objects from a section instance is shown below.

    previousnode = sectionnode.links['prev']
    nextnode = sectionnode.links['next']

The next method of populating the links table is semi-automatic and uses the `linkType` attribute on the Python macro class. There are certain parts of a document that only occur once such as an index, glossary, or bibliography. You can set the `linkType` attribute on the Python macro class to a string that corresponds to that sections role in the document (i.e. ‘index’ for the index, ‘glossary’ for the glossary, ‘bibliography’ for the bibliography). When a node with a special link type is created, it is inserted into the dictionary of links with the given name. This allows you to have links to indexes, glossaries, etc. appear in the links object only when they are in the current document. The example below shows the `theindex` environment being configured to show up under the ‘index’ key in the links dictionary.

    class theindex(Environment, SectionUtils):
        nodeType = 'index'
        level = Environment.SECTION_LEVEL

Note: These links are actually stored under the ‘links’ key of the owner document’s userdata dictionary (i.e. `self.ownerDocument.userdata[’links’])`. Other objects can be added to this dictionary manually.

The final way of getting objects into the links dictionary is through a configuration file or command-line options. This method is described fully in section 2.1.4.