doc/tips/parentlinks_style.mdwn

   1 Here are some tips for ways to style the links
   2 provided by the [[plugins/parentlinks]] plugin.
   3
   4 This plugin offers a `HTML::Template` loop that iterates over all or
   5 a subset of a page's parents. It also provides a few bonus
   6 possibilities, such as styling the parent links depending on their
   7 place in the path.
   8
   9 [[!toc ]]
  10
  11 Content
  12 =======
  13
  14 The plugin provides one template loop, called `PARENTLINKS`, that
  15 returns the list of parent pages for the current page. Every returned
  16 path element has the following variables set:
  17
  18 * `URL` (string): url to the current path element
  19 * `PAGE` (string): title of the current path element
  20 * `DEPTH` (positive integer): depth of the path leading to the
  21   current path element, counting from the wiki's root, which has
  22   `DEPTH=0`
  23 * `HEIGHT` (positive integer): distance, expressed in path elements,
  24   from the current page to the current path element; e.g. this is
  25   1 for the current page's mother, 2 for its grand-mother, etc.
  26 * `DEPTH_n` (boolean): true if, and only if, `DEPTH==n`
  27 * `HEIGHT_n` (boolean): true if, and only if, `HEIGHT==n`
  28
  29 Usage
  30 =====
  31
  32 The `DEPTH_n` and `HEIGHT_n` variables allow the template writer to
  33 skip arbitrary elements in the parents list: they are arbitrary
  34 page-range selectors.
  35
  36 The `DEPTH` and `HEIGHT` variables allow the template writer to apply
  37 general treatment, depending on one of these variables, to *every*
  38 parent: they are counters.
  39
  40 Basic usage
  41 -----------
  42
  43 As in the default `page.tmpl`, one can simply display the list of
  44 parent pages:
  45
  46         <TMPL_LOOP NAME="PARENTLINKS">
  47         <a href="<TMPL_VAR NAME=URL>"><TMPL_VAR NAME=PAGE></a>/
  48         </TMPL_LOOP>
  49         <TMPL_VAR TITLE>
  50
  51
  52 Styling parents depending on their depth
  53 ----------------------------------------
  54
  55 Say you want the parent links to be styled depending on their depth in
  56 the path going from the wiki root to the current page; just add the
  57 following lines in `page.tmpl`:
  58
  59         <TMPL_LOOP NAME="PARENTLINKS">
  60         <a href="<TMPL_VAR NAME="URL">" class="depth<TMPL_VAR NAME="DEPTH">">
  61           <TMPL_VAR NAME="PAGE">
  62         </a> /
  63         </TMPL_LOOP>
  64
  65 Then write the appropriate CSS bits for `a.depth1`, etc.
  66
  67 Skip some parents, style the others depending on their distance to the current page
  68 -----------------------------------------------------------------------------------
  69
  70 Say you want to display all the parents links but the wiki homepage,
  71 styled depending on their distance to the current page; just add the
  72 following lines in `page.tmpl`:
  73
  74         <TMPL_LOOP NAME="PARENTLINKS">
  75         <TMPL_IF NAME="DEPTH_0">
  76         <TMPL_ELSE>
  77         <a href="<TMPL_VAR NAME="URL">" class="height<TMPL_VAR NAME="HEIGHT">">
  78           <TMPL_VAR NAME="PAGE">
  79         </a> /
  80         </TMPL_IF>
  81         </TMPL_LOOP>
  82
  83 Then write the appropriate CSS bits for `a.height1`, etc.
  84
  85 Full-blown example
  86 ------------------
  87
  88 Let's have a look at a more complicated example; combining the boolean
  89 loop variables provided by the plugin (`IS_ROOT` and friends) and
  90 `HTML::Template` flow control structures, you can have custom HTML
  91 and/or CSS generated for some special path components; e.g.:
  92
  93         <!-- all parents, skipping mother and grand'ma, inside a common div+ul -->
  94         <div id="oldestparents">
  95         <ul>
  96         <TMPL_LOOP NAME="PARENTLINKS">
  97           <TMPL_IF NAME="HEIGHT_2">
  98           <TMPL_ELSE>
  99             <TMPL_IF NAME="HEIGHT_1">
 100             <TMPL_ELSE>
 101               <li><a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a></li>
 102             </TMPL_IF>
 103           </TMPL_IF>
 104         </TMPL_LOOP>
 105         </ul>
 106         </div>
 107
 108         <!-- dedicated div's for mother and grand'ma -->
 109         <TMPL_LOOP NAME="PARENTLINKS">
 110           <TMPL_IF NAME="HEIGHT_2">
 111             <div id="grandma">
 112               <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
 113             </div>
 114           <TMPL_ELSE>
 115             <TMPL_IF NAME="HEIGHT_1">
 116               <div id="mother">
 117                 <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
 118               </div>
 119             </TMPL_IF>
 120           </TMPL_IF>
 121         </TMPL_LOOP>
 122
 123         <!-- eventually, the current page title -->
 124         <TMPL_VAR NAME="TITLE">
 125         </div>