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