15c0328386c4908e5df1fb661195a5d8a040d79d
[ikiwiki.git] / 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>