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_LOOP>
  81
  82 Then write the appropriate CSS bits for `a.height1`, etc.
  83
  84 Full-blown example
  85 ------------------
  86
  87 Let's have a look at a more complicated example; combining the boolean
  88 loop variables provided by the plugin (`IS_ROOT` and friends) and
  89 `HTML::Template` flow control structures, you can have custom HTML
  90 and/or CSS generated for some special path components; e.g.:
  91
  92         <!-- all parents, skipping mother and grand'ma, inside a common div+ul -->
  93         <div id="oldestparents">
  94         <ul>
  95         <TMPL_LOOP NAME="PARENTLINKS">
  96           <TMPL_IF NAME="HEIGHT_2">
  97           <TMPL_ELSE>
  98             <TMPL_IF NAME="HEIGHT_1">
  99             <TMPL_ELSE>
 100               <li><a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a></li>
 101             </TMPL_IF>
 102           </TMPL_IF>
 103         </TMPL_LOOP>
 104         </ul>
 105         </div>
 106
 107         <!-- dedicated div's for mother and grand'ma -->
 108         <TMPL_LOOP NAME="PARENTLINKS">
 109           <TMPL_IF NAME="HEIGHT_2">
 110             <div id="grandma">
 111               <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
 112             </div>
 113           <TMPL_ELSE>
 114             <TMPL_IF NAME="HEIGHT_1">
 115               <div id="mother">
 116                 <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
 117               </div>
 118             </TMPL_IF>
 119           </TMPL_IF>
 120         </TMPL_LOOP>
 121
 122         <!-- eventually, the current page title -->
 123         <TMPL_VAR NAME="TITLE">
 124         </div>