ikiwiki/doc/tips/parentlinks_style.mdwn

Here are some tips for ways to style the links
provided by the [[plugins/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.

[[!toc levels=2]]

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>