doc/plugins/pedigree.mdwn

   1 [[!template id=plugin name=pedigree author="intrigeri"]]
   2 [[!tag type/useful]]
   3
   4 This plugin provides a bunch of loops that one can use in his/her
   5 `HTML::Template`'s to iterate over all or a subset of a page's
   6 parents. One can think of pedigree as "`PARENTLINKS` on steroids".
   7
   8 [[!toc ]]
   9
  10 Content
  11 =======
  12
  13 Loop variables
  14 --------------
  15
  16 Inside any loop provided by the pedigree plugin, every path element
  17 has not only the `URL` and `PAGE` variables, as with `PARENTLINKS`,
  18 but also the following ones:
  19
  20 * `ABSDEPTH` (positive integer): depth of the path leading to the
  21   current path element, counting from the wiki's root, which has
  22   `ABSDEPTH=0`
  23 * `DISTANCE` (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 * `IS_ROOT` (boolean): true if, and only if, this path element is the
  27   wiki's root
  28 * `IS_SECOND_ANCESTOR` (boolean): true if, and only if, this path
  29   element is the first one after the wiki's root, on the path leading
  30   to the current page
  31 * `IS_GRAND_MOTHER` (boolean): true if, and only if, this path element
  32   is the current page's grand-mother
  33 * `IS_MOTHER` (boolean): true if, and only if, this path element
  34   is the current page's mother
  35
  36 Loops
  37 -----
  38
  39 ### `PEDIGREE`
  40
  41 Returns the same parents list as `PARENTLINKS` would, along with
  42 additional loop variables as explained above.
  43
  44 ### `PEDIGREE_BUT_ROOT`
  45
  46 Returns the same parents list as `PEDIGREE` would, **but** the wiki
  47 root (i.e. homepage).
  48
  49 In addition to pedigree's common loop variables, `PEDIGREE_BUT_ROOT`
  50 provides `RELDEPTH` (positive integer), whose value, for a given
  51 parent, is its relative depth, i.e. the depth of the path leading to
  52 it, counting from the first element returned by this loop.
  53
  54 ### `PEDIGREE_BUT_TWO_OLDEST`
  55
  56 Returns the same parents list as `PEDIGREE` would, **but** the wiki
  57 root (i.e. homepage) and the next path component.
  58
  59 In addition to pedigree's common loop variables,
  60 `PEDIGREE_BUT_TWO_OLDEST` provides `RELDEPTH`: depth of the path
  61 leading to the current parent, relative to the first element returned
  62 by this loop.
  63
  64 Usage
  65 =====
  66
  67 Styling parents depending on their depth
  68 ----------------------------------------
  69
  70 Say you want the parent links to be styled depending on their depth in
  71 the path leading to the current page; just add the following lines in
  72 `page.tmpl`:
  73
  74         <TMPL_LOOP NAME="PEDIGREE">
  75         <a href="<TMPL_VAR NAME="URL">" class="parentdepth<TMPL_VAR NAME="ABSDEPTH">">
  76           <TMPL_VAR NAME="PAGE">
  77         </a> /
  78         </TMPL_LOOP>
  79
  80 Then write the appropriate CSS bits for `a.parentdepth1`, etc.
  81
  82 Skip some parents, style the others depending on their distance
  83 ---------------------------------------------------------------
  84
  85 Say you want to display the parents links, skipping the wiki homepage,
  86 styled depending on their distance from the current page; just add the
  87 following lines in `page.tmpl`:
  88
  89         <TMPL_LOOP NAME="PEDIGREE_BUT_ROOT">
  90         <a href="<TMPL_VAR NAME="URL">" class="parentdistance<TMPL_VAR NAME="DISTANCE">">
  91           <TMPL_VAR NAME="PAGE">
  92         </a> /
  93         </TMPL_LOOP>
  94
  95 Then write the appropriate CSS bits for `a.parentdistance1`, etc.
  96
  97 Full-blown example
  98 ------------------
  99
 100 Let's have a look at a more complicated example; combining the boolean
 101 loop variables provided by this plugin (`IS_ROOT` and friends) and
 102 `HTML::Template` flow control structures, you can have custom HTML
 103 and/or CSS generated for some special path components; e.g.:
 104
 105         <!-- all parents, skipping mother and grand'ma, inside a common div+ul -->
 106         <div id="oldestparents">
 107         <ul>
 108         <TMPL_LOOP NAME="PEDIGREE">
 109           <TMPL_IF NAME="IS_GRAND_MOTHER">
 110           <TMPL_ELSE>
 111             <TMPL_IF NAME="IS_MOTHER">
 112             <TMPL_ELSE>
 113               <li><a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a></li>
 114             </TMPL_IF>
 115           </TMPL_IF>
 116         </TMPL_LOOP>
 117         </ul>
 118         </div>
 119
 120         <!-- dedicated div's for mother and grand'ma -->
 121         <TMPL_LOOP NAME="PEDIGREE">
 122           <TMPL_IF NAME="IS_GRAND_MOTHER">
 123             <div id="grandma">
 124               <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
 125             </div>
 126           <TMPL_ELSE>
 127             <TMPL_IF NAME="IS_MOTHER">
 128               <div id="mother">
 129                 <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
 130               </div>
 131             </TMPL_IF>
 132           </TMPL_IF>
 133         </TMPL_LOOP>
 134
 135         <!-- eventually, the current page title -->
 136         <TMPL_VAR NAME="TITLE">
 137         </div>
 138
 139 Known bugs
 140 ==========
 141
 142 If `PEDIGREE_BUT_ROOT` and `PEDIGREE_BUT_TWO_OLDEST` are used in the
 143 same `HTML::Template`, `RELDEPTH` has wrong values inside the
 144 `PEDIGREE_BUT_ROOT` loop. This can be fixed if anyone needs this to
 145 be working.