aboutsummaryrefslogtreecommitdiff
path: root/doc/tips/parentlinks_style.mdwn
blob: 5294e545277dc30e3ce86f6d6f200abab8289660 (plain)
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
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 ]]

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_LOOP>

Then write the appropriate CSS bits for `a.height1`, etc.

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>