doc/plugins/pedigree.mdwn

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