doc/tips/parentlinks_style.mdwn

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