6.3 Customization of the navigation panels buttons

A lot of customization of the navigation panel may be achieved without redefining functions, with variables redefinition. In case it isn't enough, it is also possible to redefine the function doing the navigation panel formatting.

6.3.1 Controlling the navigation panel panel at a high level

The global formatting of the navigation panels may be changed with the following variables:

$VERTICAL_HEAD_NAVIGATION

A vertical navigation panel will be used for the header navigation panel if this variable is true.

$ICONS

Icons are used instead of textual buttons if this variable is true.

$SECTION_NAVIGATION

If this variable is false there is no section navigation, no navigation panels for the elements within the pages, only at the beginning and the end of the page (see section Page layout related command line options).

6.3.2 Specifying the buttons formatting

Several arrays and hashes enable a precise control on the buttons and their display. The following arrays determine the buttons present in navigation panels:

@SECTION_BUTTONS

This array is used for the navigation panel buttons present at the begining of sectioning elements. If split at node or section they are also used at the page footer, and in the case of section navigation at the page header.

@SECTION_FOOTER_BUTTONS

@NODE_FOOTER_BUTTONS

This array is used for the navigation panel buttons present at the footer of pages when split at node or at section.

If $WORDS_IN_PAGE is set and the output is split at nodes, these buttons are only present if there are more than $WORDS_IN_PAGE words in the sectioning element text. This counting is very rough and include punctuation marks, html elements, numbers. The default is to include the buttons after 300 words.

@CHAPTER_BUTTONS

This array is used for the buttons appearing at the page footer if split at chapter, and at the page header if split at chapter and there is no section navigation.

@MISC_BUTTONS

These buttons appear at the beginning of special and sections and at the end of these section pages if the output is split.

The array specify the buttons displayed in navigation panels, and how the button is displayed. Each element is associated with a button of the navigation panel from left to right. The signification of the array element value is the following:

reference on a function

The function is called with first argument a filehandle reference on the current file and second argument a boolean true if the navigation panel should be vertical.

reference on a scalar

The scalar value is printed. For some possibly usefull scalars, Accessing elements informations.

reference on an array

In this case the first array element should be a reference on text and the second element an element label. In that case a link to the element associated with the element label with the scalar value text is generated.

For example if the buttons array element is

[ 'Next', \$Texi2HTML::NODE{Next} ]

The button will be a link to the next section with text $Texi2HTML::NODE{Next}.

element label

If icons are not used, the button is a link to the corresponding element which text is defined by the value associated with the element label in the %NAVIGATION_TEXT hash, surrounded by ‘[’ and ‘]’. If the element label is ‘ ’, there is no ‘[’ and ‘]’. The element of the %NAVIGATION_TEXT hash are defined dynamically, in the init_out function reference (see section Preparing the output).

If icons are used, the button is an image with file determined by the value associated with the element label in the %ACTIVE_ICONS hash if the the link really leads to an element, or in the %PASSIVE_ICONS hash if there is no element to link to. Of course if there is a link to the element the icon links to that element. The button name and the button description are used in HTML attributes to have a textual description of the icon. The corresponding strings are in %BUTTONS_NAME for the button name and %NAVIGATION_TEXT for the description.

6.3.3 Changing the navigation panel formatting

If you are not satisfied with this scheme, it is possible to control exactly the formatting of navigation panels by redefining a function reference. The function controlling the display of navigation panel is associated with the following function reference:

Function Reference: print_navigation $filehandle \@buttons $vertical

$filehandle is the opened filehandle the function should write to. \@buttons is an array reference which should hold the specification of the buttons for that navigation panel. $vertical is true if the navigation panel should be vertical.

Doku-Base