pedigree: added documentation (doc/plugins/pedigree.mdwn)
[ikiwiki.git] / 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.