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