Here are some tips for ways to style the links provided by the parentlinks plugin.

This plugin offers a HTML::Template loop that iterates over all or a subset of a page's parents. It also provides a few bonus possibilities, such as styling the parent links depending on their place in the path.

  1. Content
  2. Usage
    1. Basic usage
    2. Styling parents depending on their depth
    3. Skip some parents, style the others depending on their distance to the current page
    4. Avoid showing title of toplevel index page
    5. Full-blown example

Content

The plugin provides one template loop, called PARENTLINKS, that returns the list of parent pages for the current page. Every returned path element has the following variables set:

  • URL (string): url to the current path element
  • PAGE (string): title of the current path element
  • DEPTH (positive integer): depth of the path leading to the current path element, counting from the wiki's root, which has DEPTH=0
  • HEIGHT (positive integer): distance, expressed in path elements, from the current page to the current path element; e.g. this is 1 for the current page's mother, 2 for its grand-mother, etc.
  • DEPTH_n (boolean): true if, and only if, DEPTH==n
  • HEIGHT_n (boolean): true if, and only if, HEIGHT==n

Usage

The DEPTH_n and HEIGHT_n variables allow the template writer to skip arbitrary elements in the parents list: they are arbitrary page-range selectors.

The DEPTH and HEIGHT variables allow the template writer to apply general treatment, depending on one of these variables, to every parent: they are counters.

Basic usage

As in the default page.tmpl, one can simply display the list of parent pages:

<TMPL_LOOP NAME="PARENTLINKS">
<a href="<TMPL_VAR NAME=URL>"><TMPL_VAR NAME=PAGE></a>/ 
</TMPL_LOOP>
<TMPL_VAR TITLE>

Styling parents depending on their depth

Say you want the parent links to be styled depending on their depth in the path going from the wiki root to the current page; just add the following lines in page.tmpl:

<TMPL_LOOP NAME="PARENTLINKS">
<a href="<TMPL_VAR NAME="URL">" class="depth<TMPL_VAR NAME="DEPTH">">
  <TMPL_VAR NAME="PAGE">
</a> / 
</TMPL_LOOP>

Then write the appropriate CSS bits for a.depth1, etc.

Skip some parents, style the others depending on their distance to the current page

Say you want to display all the parents links but the wiki homepage, styled depending on their distance to the current page; just add the following lines in page.tmpl:

<TMPL_LOOP NAME="PARENTLINKS">
<TMPL_IF NAME="DEPTH_0">
<TMPL_ELSE>
<a href="<TMPL_VAR NAME="URL">" class="height<TMPL_VAR NAME="HEIGHT">">
  <TMPL_VAR NAME="PAGE">
</a> / 
</TMPL_IF>
</TMPL_LOOP>

Then write the appropriate CSS bits for a.height1, etc.

Avoid showing title of toplevel index page

If you don't like having "index" appear on the top page of the wiki, but you do want to see the name of the page otherwise, you can use a special HAS_PARENTLINKS template variable that the plugin provides. It is true for every page except the toplevel index.

Here is an example of using it to hide the title of the toplevel index page:

<TMPL_LOOP NAME="PARENTLINKS">
<a href="<TMPL_VAR NAME=URL>"><TMPL_VAR NAME=PAGE></a>/ 
</TMPL_LOOP>
<TMPL_IF HAS_PARENTLINKS>
<TMPL_VAR TITLE>
</TMPL_IF>

Full-blown example

Let's have a look at a more complicated example; combining the boolean loop variables provided by the plugin (IS_ROOT and friends) and HTML::Template flow control structures, you can have custom HTML and/or CSS generated for some special path components; e.g.:

<!-- all parents, skipping mother and grand'ma, inside a common div+ul -->
<div id="oldestparents">
<ul>
<TMPL_LOOP NAME="PARENTLINKS">
  <TMPL_IF NAME="HEIGHT_2">
  <TMPL_ELSE>
    <TMPL_IF NAME="HEIGHT_1">
    <TMPL_ELSE>
      <li><a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a></li>
    </TMPL_IF>
  </TMPL_IF>
</TMPL_LOOP>
</ul>
</div>

<!-- dedicated div's for mother and grand'ma -->
<TMPL_LOOP NAME="PARENTLINKS">
  <TMPL_IF NAME="HEIGHT_2">
    <div id="grandma">
      <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
    </div>
  <TMPL_ELSE>
    <TMPL_IF NAME="HEIGHT_1">
      <div id="mother">
    <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
      </div>
    </TMPL_IF>
  </TMPL_IF>
</TMPL_LOOP>

<!-- eventually, the current page title -->
<TMPL_VAR NAME="TITLE">
</div>