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