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 levels=2]]
  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 Avoid showing title of toplevel index page
  86 ------------------------------------------
  87
  88 If you don't like having "index" appear on the top page of the wiki,
  89 but you do want to see the name of the page otherwise, you can use a
  90 special `HAS_PARENTLINKS` template variable that the plugin provides.
  91 It is true for every page *except* the toplevel index.
  92
  93 Here is an example of using it to hide the title of the toplevel index
  94 page:
  95
  96         <TMPL_LOOP NAME="PARENTLINKS">
  97         <a href="<TMPL_VAR NAME=URL>"><TMPL_VAR NAME=PAGE></a>/
  98         </TMPL_LOOP>
  99         <TMPL_IF HAS_PARENTLINKS>
 100         <TMPL_VAR TITLE>
 101         </TMPL_IF>
 102
 103 Full-blown example
 104 ------------------
 105
 106 Let's have a look at a more complicated example; combining the boolean
 107 loop variables provided by the plugin (`IS_ROOT` and friends) and
 108 `HTML::Template` flow control structures, you can have custom HTML
 109 and/or CSS generated for some special path components; e.g.:
 110
 111         <!-- all parents, skipping mother and grand'ma, inside a common div+ul -->
 112         <div id="oldestparents">
 113         <ul>
 114         <TMPL_LOOP NAME="PARENTLINKS">
 115           <TMPL_IF NAME="HEIGHT_2">
 116           <TMPL_ELSE>
 117             <TMPL_IF NAME="HEIGHT_1">
 118             <TMPL_ELSE>
 119               <li><a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a></li>
 120             </TMPL_IF>
 121           </TMPL_IF>
 122         </TMPL_LOOP>
 123         </ul>
 124         </div>
 125
 126         <!-- dedicated div's for mother and grand'ma -->
 127         <TMPL_LOOP NAME="PARENTLINKS">
 128           <TMPL_IF NAME="HEIGHT_2">
 129             <div id="grandma">
 130               <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
 131             </div>
 132           <TMPL_ELSE>
 133             <TMPL_IF NAME="HEIGHT_1">
 134               <div id="mother">
 135                 <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
 136               </div>
 137             </TMPL_IF>
 138           </TMPL_IF>
 139         </TMPL_LOOP>
 140
 141         <!-- eventually, the current page title -->
 142         <TMPL_VAR NAME="TITLE">
 143         </div>