Menus and tabs

For notes on Forrest layout, see the Forrest Layout document.

Menus and tabs are closely intertwined in forrest, but they are defined in separate places.

Menu configuration is defined in the files xtdoc/sd/src/documentation/content/xdocs/site.xml and xtdoc/sd/src/documentation/content/xdocs/doc/site-frag.xml.

Tab configuration is defined in the files xtdoc/sd/src/documentation/content/xdocs/tabs.xml and xtdoc/sd/src/documentation/content/xdocs/doc/tabs-frag.xml

site.xml og tabs.xml respectively define the menus and the tabs in the main site.

site-frag.xml and tabs-frag.xml define the menus and the tabs for the technical documentation. The site-frag.xml file is included into the site layout using the following line in the site.xml file:

<xi:include href="doc/site-frag.xml#xpointer(/tech/*)"
xmlns:xi="http://www.w3.org/2001/XInclude"/>

The same method is used to incorporate the tabs-frag.xml into the site layout, using the following line in tabs.xml

<xi:include href="doc/tabs-frag.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"/>

Defining a tab

A single tab is defined like this: <tab dir="" id="northern-sami" label="Davvisámegiella" indexfile="index_sme.html" />

• An entry has to start with the tab tag.
• The id attribute has to be a unique name, which identifies the tab.
• The dir attribute tells which folder is the working folder of tab.
• The label attribute defines the name of the tab.
• The indexfile attribute tells which file should be opened when clicking the tab.

Subtabs

It is possible to define two levels of tabs in forrest. The following example is fetched from the tabs-frag.xml file.

<tab dir="doc" id="TechDoc" label="Tech. doc" indexfile="intro.html" >
    <tab dir="doc/admin" id="admin" label="Admin" indexfile="workplan.html" />
    <tab dir="doc/infra" id="infra" label="Infrastucture" indexfile="Infrastructure.html" />
    <tab dir="doc/lang"  id="lang"  label="Languages" indexfile="index.html" />
    <tab dir="doc/ling"  id="ling"  label="Linguistics" indexfile="index.html" />
    <tab dir="doc/tools" id="tools" label="Tools" indexfile="tools.html" />
</tab>

This stanza defines the tab labeled “Tech. Doc”, with the subtabs “Admin”, “Infrastucture”, “Languages”, “Linguistics” and “Tools”.

The way the subtabs are defined above, means that we can bind specific menus to them. If you don’t want that behaviour, then you can omit the id attribute in the subtabs.

The id attribute is referred to from the menus, and this binds the tab and the menu together.

Defining a menu

This piece of code is fetched from from xtdoc/src/documentation/content/xdocs/site.xml, and defines the introductory menu:

<about label="About" tab="Home" >
    <index   href="index.html" label="Index" description="Welcome to divvun.no" />
    <changes href="changes.html" label="Changes" description="The projects history" />
    <todo    href="todo.html" label="Todo" description="The plan for the project" />
</about>

A single menu entry contains a tag you define yourself (e.g. index, changes, todo, whatever …), a href (some internet adress), and an optional description.

These entries are surrounded by the “about” tag. As stated above, we could replace “about” with something else. The label attribute defines the name of the menu entry, and the tab attribute defines which tab should be highlighted when pressing this link.

Further examples

The next example is from the file gt/doc/site-frag.xml. This is a part of the menu that appears when clicking first the Tech. Doc tab, and the Admin subtab.

<admin href="docslashadminslash" label="Project" tab="admin" >
    <worktodo href="workplan.html" label="Work Plan" />
    <adr href="adr.html" label="Project workers" />
    ...
</admin>

It has the same structure as the previous example, with one notable exception, the href that points to the directory doc/admin/.

This means that the hrefs defined in the menu entries inside this one, will point to files in this folder.

One crucial detail in the href is the final /. This one has to be there, so that the submenu of the chosen tab shows. If the final / is omitted, then all the menus defined in site.xml will be shown.