Template:Navlist/Doc

These templates are meant to simplify maintenance of a book whose modules are meant to be read in a particular order. The order of the modules is specified in just one place, a page called a navlist, in a format that can be used by this template family to retrieve information in a usable form. By default, the navlist page is Template:{{NAIVEBOOKNAME}}/Navlist.

When you modify the navlist, your changes automatically appear in the table of contents on the book's main page, and in the navboxes at the tops and bottoms of the book's module pages — but these changes to any given page (the main page, or a module page) might not appear instantly, because just reloading a page doesn't always cause the system to recompute the template calls on that page; on its own, the system might not recompute them for hours, or days. You can force the system to recompute all the template calls on a page by doing a "null edit" of that page: click the "edit this page" tab, then on the "editing" page just click the "save page" button. Since you didn't actually do anything to the page, this doesn't even show up on the edit history of the page — but it does cause the system to recompute all template calls on the page.

The table of contents can be laid out as a list (the default format) or as a table (called block format).

Client templates

There are three principal templates that are called by pages in the book:

• {{Navlist/Contents}} should be called on the main page of the book, to generate the book's table of contents.
• {{Navlist/Top}} should be called at the top of each module, to generate a navbox with links to the next and previous modules.
• {{Navlist/Bottom}} should be called at the bottom of each module, to generate a navbox with a link to the next module.

Each of these principal templates takes an optional named parameter {{{navlist}}}, whose value is a page to use as the navlist instead of Template:{{BOOKNAME}}/Navlist. When a {{{navlist}}} is provided, but does not specify a namespace, the navlist page is assumed to be in mainspace (rather than template space). (Thus, if {{NAMESPACE}} is not mainspace, then navlist={{BOOKNAME}}/Navlist is not the same as using the default navlist page.)

Calls to these principal templates may also generate some incidental administrative directives expected to be useful to the pages from which they are called. Calling {{Navlist/Contents}} may incidentally generate a __NOTOC__ directive. Calling {{Navlist/Top}} or {{Navlist/Bottom}} incidentally generates a call to template {{BookCat}}.

An additional template is provided for use by the client book:

• {{Navlist/Transcluded section|...}} generates a section heading whose [edit] link actually edits a specified page. It should be used on a page with __NOTOC__. There are various options: the [edit] link may be omitted, a [help] link may also be provided, the name of the section may be specified or may be the subpagename of the [edit] target page, and the heading may be a subsection or subsubsection.

The navlist page

This page, usually located in mainspace, describes the contents of the book in the form of a template that takes, as its sole parameter, the name of another template (usually in template namespace). The navlist template then calls its parameter once for each module in the book, and passes all of those results as parameters to another call to the parameter.

The sole parameter passed to the navlist is named by the empty string; thus, the code to call the navlist with parameter template (assuming the default page name for the navlist) is {{Template:{{NAIVEBOOKNAME}}/Navlist|=template}}, and template is invoked in the body of Template:{{NAIVEBOOKNAME}}/Navlist by the name {{{}}}.

The entire body of the navlist is a single call to {{{}}}, with one required named parameter level=top, optionally some other named parameters, and all other parameters unnamed with values that are themselves calls to {{{}}}. It is recommended that the single call have default value {{Navlist/Default}}, which is provided for just this purpose (so that when editing the navlist, previews will present useful information). Thus:

{{{{{|Navlist/Default}}}|level=top
|{{{{{}}} ... }}
|{{{{{}}} ... }}
...
|{{{{{}}} ... }}
|{{{{{}}} ... }}
}}

For the rest of this discussion, we will refer to the single overarching call to {{{}}} as the outer call, and the unnamed-parameter-value calls to {{{}}} as the inner calls.

There are four optional named parameters to the outer call: {{{stage}}}, {{{background}}}, {{{border}}}, and {{{subpages}}}. If stage=left, the {{stage short}} icon for each module in the table of contents will appear to the left of the link to the module, otherwise that icon will appear to the right of the link. {{{background}}} and {{{border}}} specify the default colors for the background and border of navboxes. If {{{background}}} isn't provided, the default background color is #fffff (i.e., white); if {{{border}}} isn't provided the default border color is #000000 (i.e., black). These default colors can be overridden for any particular navbox by a named parameter to the template call that generates that navbox ({{Navlist/Top}} or {{Navlist/Bottom}}). {{{subpages}}} names one or more optional subpages of each book module, separated by slash; {{Navlist/Bottom}} looks for these subpages, and if present, links them in the righthand bottom corner of the page.

Each of the inner calls describes either a module, or a section heading in the table of contents, or a logical grouping of modules.

Modules

An inner call describing a module takes four unnamed parameters, the first and last of which are optional (that is, they may be blank or omitted). The arguments are

• a degree-of-completion icon generated by template {{stage short}}. If this is blank or omitted, no default value is assumed.

• an indentation code to be used when displaying the module in the table of contents. For example, one might use "*" for sections, "**" for subsections, "***" for subsubsections; or "" (empty) for sections, ":" for subsections, "::" for subsubsections.

• the page name of the module, omitting the namespace and bookname and starting with a slash. (The namespace and bookname are assumed to be {{NAMESPACE}} and {{ROOTPAGENAME}} — which depend on the client page, not on the navlist.)

• the name of the module as it should appear in the table of contents. If this is blank or omitted, it defaults to the last part of the page name (the part following the last slash). For example, a navlist (here) containing

{{{{{|Navlist/Default}}}|level=top|stage=left
|{{{{{}}}|{{stage short|75%|January 14, 2009}} ||/Foo}}
|{{{{{}}}|{{stage short|50%|January 14, 2009}} ||/Bar}}
|{{{{{}}}|{{stage short|25%|January 14, 2009}} |:|/Bar/Alpha}}
|{{{{{}}}|{{stage short|100%|January 14, 2009}}|:|/Bar/Beta}}
|{{{{{}}}|{{stage short|50%|January 14, 2009}} ||/Baz|Quux}}
}}

would produce outline

{{stage short|75%|January 14, 2009}} [[:{{NAIVEBOOKNAME}}/Foo|Foo]]<br/>
{{stage short|50%|January 14, 2009}} [[:{{NAIVEBOOKNAME}}/Bar|Bar]]<br/>
: {{stage short|25%|January 14, 2009}} [[:{{NAIVEBOOKNAME}}/Bar/Alpha|Alpha]]<br/>
: {{stage short|100%|January 14, 2009}} [[:{{NAIVEBOOKNAME}}/Bar/Beta|Beta]]<br/>
{{stage short|50%|January 14, 2009}} [[:{{NAIVEBOOKNAME}}/Baz|Quux]]<br/>

which would look like this in list format:

Foo
Bar

Alpha

Beta

Quux

or in block format,

Foo Bar Alpha Beta Quux

Section headings

An inner call describing a section heading takes a single parameter section=Heading. It produces a subsection heading within the table of contents, with title Heading. For example, a navlist (here) containing

{{{{{|Navlist/Default}}}|level=top
|{{{{{}}}|section=Alpha}}
|{{{{{}}}|{{stage short|75%|January 14, 2009}} |*|/Top}}
|{{{{{}}}|{{stage short|50%|January 14, 2009}} |*|/Right}}
|{{{{{}}}|section=Beta}}
|{{{{{}}}|{{stage short|25%|January 14, 2009}} |*|/Left}}
|{{{{{}}}|{{stage short|50%|January 14, 2009}} |*|/Bottom}}
}}

would produce outline

<h3>Alpha</h3>
* [[{{NAIVEBOOKNAME}}/Top|Top]] {{stage short|75%|January 14, 2009}} <br/>
* [[{{NAIVEBOOKNAME}}/Right|Right]] {{stage short|50%|January 14, 2009}} <br/>
<h3>Beta</h3>
* [[{{NAIVEBOOKNAME}}/Left|Left]] {{stage short|25%|January 14, 2009}}<br/>
* [[{{NAIVEBOOKNAME}}/Bottom|Bottom]] {{stage short|50%|January 14, 2009}}<br/>

which would look like this in list format:

Alpha

• Top
  
• Right
  

Beta

• Left
  
• Bottom
  

or, in block format,

Alpha	Top Right
Beta	Left Bottom

Logical grouping of modules

If an inner call has no {{{section}}} parameter and a blank or omitted page name (parameter {{{3}}}), an unlinked, bold module name is shown in place of a link. The module name (fourth parameter) must be provided. This can be used to identify a logical grouping of modules for which no page has been provided. For example, a navlist (here) containing

{{{{{|Navlist/Default}}}|level=top|stage=left
|{{{{{}}}| {{stage short|75%|January 14, 2009}} |:|/Bottom}}
|{{{{{}}}| {{stage short|50%|January 14, 2009}} |:||Foo}}
|{{{{{}}}| {{stage short|25%|January 14, 2009}} |::|/Foo/Right}}
|{{{{{}}}| {{stage short|100%|January 14, 2009}}|::|/Foo/Left}}
|{{{{{}}}| {{stage short|50%|January 14, 2009}} |:|/Top|Quux}}
}}

would produce outline

:  {{stage short|75%|January 14, 2009}} [[:{{NAIVEBOOKNAME}}/Bottom|Bottom]]<br/>
:  {{stage short|50%|January 14, 2009}} '''Foo'''<br/>
::  {{stage short|25%|January 14, 2009}} [[:{{NAIVEBOOKNAME}}/Foo/Right|Right]]<br/>
::  {{stage short|100%|January 14, 2009}} [[:{{NAIVEBOOKNAME}}/Foo/Left|Left]]<br/>
:  {{stage short|50%|January 14, 2009}} [[:{{NAIVEBOOKNAME}}/Top|Quux]]<br/>

which would look like this (in list format):

  Bottom

  Foo

  Right

  Left

  Quux

or, in block format,

Bottom   Foo   Right   Left   Quux

Size bounds

As the family is currently implemented, the navlist should not have more than 128 inner calls; each pair of consecutive module entries in the navlist should have at most two non-module entries between them; and if there are more than three possible subpage names provided, only the first three are processed. Any of these bounds could be increased, by modifying various templates in the family. (The 128-entry bound is built into the internal map templates; the two-consecutive-non-module bound is built into {{Navlist/Map/Prev page}} and {{Navlist/Map/Next page}}; and the three-subpage bound is built into {{Navlist/Link subpages}} and {{Navlist/Vertical stack}}.)

Other templates provided

These templates are simple tools that don't use the navlist, but are included in the family because they are used directly or indirectly by those that do.

{{Navlist/Subpagename|page}} generates the part of page after the last slash (thus, "Chapter/Book/Section" would become "Section"), or, when given a named parameter {{{mode}}}, performs other transformations on page.

{{Navlist/Link|page}} generates a link to page, where the visible name of the link is {{Navlist/Subpagename|page}}. Optional named parameters {{{left}}} and {{{right}}} put some text before or after the link, and optional parameter {{{mode}}} is passed on to Navlist/Subpagename to vary the visible name of the link; and if page is omitted, nothing at all is generated.

{{Navlist/Vertical stack|...}} echoes any of its first three parameter that are non-blank, separated by linebreaks (<br/>). Blank parameters are not separated, so the number of linebreaks is one less than the number of non-blank parameters.

{{Navlist/Link subpage|subpage}} generates a link to the named subpage of the current page, {{FULLPAGENAME}}/subpage, only if the the subpage exists; if the subpage does not exist, or if subpage is blank, generates no characters (not even whitespace).

{{Navlist/Link subpages|subpages}} parses its single parameter subpages as a slash-separated list of up to three subpage names, discarding any names beyond the third, and generates a vertical stack of links to existing subpages (using {{Navlist/Link subpage}} and {{Navlist/Vertical stack}}).

Internally used map templates

These are the templates whose names are passed as parameter {{{}}} to the navlist. The behavior of each has two major branches:

• behavior of the inner calls, of which there is one for each entry in the navlist, and
• behavior of the outer call, whose unnamed parameters are the results generated by all the inner calls.

The essential design principle here is that each operation on the navlist is partitioned so that each call only needs to know about its own parameters (as specified by the navlist): the outer call only needs to know about its named parameters and whatever is generated by the inner calls, while each inner call only needs to know about its own parameters (never about any parameter to the outer call, nor to any other inner call). In particular, neither outer nor inner calls have any way of knowing what parameters were passed to the principal client template (see above) that called the navlist. There are three patterns that these operations generally follow:

• The inner calls generate parts of the end product, which parts the outer call coordinates but does not analyze. This pattern is followed by tools that generate a Table of Contents.

{{Navlist/Map/Contents}} does most of the subtasks for {{Navlist/Contents}}. Each inner call generates a line in the table of contents, as described above. The outer call simply concatenates together all the inner results.

{{Navlist/Map/Contents block}} as {{Navlist/Map/Contents}}, but the generated text is the content for a wiki-markup table. Only content within the table is generated: the caller, {{Navlist/Contents}}, is responsible for markup at the beginning and end of the table. In particular, the color of background shading for the cells of the table is known only to {{Navlist/Contents}}, not to the outer and inner calls by the navlist, so the table has to be arranged so that the background color only has to be specified at the top of the table.

{{Navlist/Map/Contents left}} is almost identical to {{Navlist/Map/Contents}}, except that it puts the {{stage short}} icon to the left of each module link instead of to the right.

{{Navlist/Map/Contents block left}} is almost identical to {{Navlist/Map/Contents block}}, except that it puts the {{stage short}} icon to the left of each module link instead of to the right.

• The inner calls generate information to be analyzed by the outer call. This pattern is followed by the tools that determine the predecessor and successor of the current module (because these tools must recognize the position of the current module in the navlist, and use it to select the contents of another entry).

{{Navlist/Map/Next page}} generates the page name of the module listed just after {{PAGENAME}} in the navlist. Each inner call generates the page name of the module, or blank if the entry is a section heading or logical grouping. The outer call tests each of these page names successively until it finds one equal to {{PAGENAME}}, and then returns the next non-blank page name after that (skipping over one or two blanks; if the next three parameter values are all blank, it gives up and returns blank).

{{Navlist/Map/Prev page}} generates the page name of the module listed just before {{PAGENAME}} in the navlist. Works similarly to {{Navlist/Map/Next page}}.

• The inner calls do nothing. This pattern is followed by tools that extract named parameters from the outer call of the navlist.

{{Navlist/Map/Stage}} generates the value of named parameter {{{stage}}} specified in the navlist. If unspecified, defaults to blank.

{{Navlist/Map/Background}} generates the value of named parameter {{{background}}} specified in the navlist. If unspecified, defaults to ffffff (i.e., white).

{{Navlist/Map/Border}} generates the value of named parameter {{{border}}} specified in the navlist. If unspecified, defaults to 000000 (i.e., black).

{{Navlist/Map/Subpages}} geenrates the value of named parameter {{{subpages}}} specifies in the navlist. If unspecified, defaults to blank.

{{Navlist/Map/Initial section}} doesn't quite fit this pattern, though it's close; it is a tool for extracting a named parameter of an inner call of the navlist. It generates the value of named parameter {{{section}}} of the first inner call, defaulting to blank if the first inner call has no such named parameter.

Note on editing the templates

When editing each of these templates, some tricks are needed to make the examples in the documentation reflect the changes made.

• During editing, the Show preview button displays examples in the template documentation using the old version. Try this workaround: instead of using the Show preview button, use the Preview page with this template box further down on the edit page, entering the name of the template you're editing as the page title to preview.
• Saving the edits does not immediately update the examples. To make the consequences of the edits appear, after saving do a null edit (that is, edit and save without making any changes). This problem with updating apparently happens even if the system is updating pages instantly to reflect changes to templates; it has to do with the order in which the system does things internally, rather than how quickly it does them.