1 After realizing (thanks to
2 [[Allow_TITLE_to_include_part_of_the_path_in_addition_to_the_basename]])
3 that I needed some kind of "parentlinks on steroids", I wrote a new
4 plugin, called pedigree.
6 This plugin provides a bunch of loops that one can use in his/her
7 `HTML::Template`'s to iterate over all or a subset of a page's
8 parents. Inside these loops, half a dozen variables are made
9 available, in addition to `PAGE` and `URL` that are already provided
12 Amongst many possibilities, one can e.g. simply use this plugin to
13 give every parent link a different `class=` attribute, depending
14 either on its depth in the path leading to the current page, or on its
17 The code and documentation (including simple and complex usage
18 examples) are in the 'pedigree' Git branch in this repo:
20 git://repo.or.cz/ikiwiki/intrigeri.git
22 Seems there is also a [gitweb](http://repo.or.cz/w/ikiwiki/intrigeri.git).
24 > Ok, I'll take a look. BTW, could you allow user joey on repo.or.cz
25 > push access to the main ikiwiki repo you set up there? --[[Joey]]
27 >> I did not. The main ikiwiki repo on repo.or.cz seems to have been
28 >> been setup by johannes.schindelin@gmx.de ; mine is what they call
29 >> a "fork" (but it's not, obviously). -- intrigeri
31 Any opinions on the idea/design/implementation?
33 > Seems that there should be a more generic way to do `PEDIGREE_BUT_ROOT`
34 > and `PEDIGREE_BUT_TWO_OLDEST` (also `is_second_ancestor`,
35 > `is_grand_mother` etc). One way would be to include in `PEDIGREE`
36 > a set of values like `depth_1`, `depth_2`, etc. The one corresponding
37 > to the `absdepth` would be true. This would allow a template like this:
39 <TMPL_LOOP NAME="PEDIGREE">
40 <TMPL_IF NAME="depth_1">
42 <TMPL_IF NAME="depth_2">
44 <TMPL_VAR PAGE> /* only showing pages 2 levels deep */
49 > The only missing information would be `reldepth`, but in the above
50 > example the author of that template knows that it's `absdepth - 1`
51 > (Things would be a lot nicer if `HTML::Template` had equality tests!)
53 > Since this would make it more generic and also fix your one documented
54 > bug, I can see no reason not to do it. ;-) --[[Joey]]
56 >> Thanks for your comments. I'll answer soon. (Grrr, I really
57 >> need to find a way to edit this wiki offline, every minute
58 >> online costs bucks to me, my old modem gently weeps,
59 >> and I hate webbrowsers.) -- intrigeri
61 >>> Well, I maybe didn't get your idea properly; I may be missing
62 >>> something obvious, but:
64 >>> * I don't understand how this would replace `is_grand_mother`. As a template
65 >>> writer, I don't know, given an absolute array index (and this is the only
66 >>> piece of data your solution gives me), if it will be e.g. the before-last
67 >>> (how do I say this in correct English?) element of an array whose
68 >>> (variable) size is unknown to me.
69 >>> * Knowing that `reldepth`'s value is, in a given loop, always equal to
70 >>> `absdepth - 1` is of little use to me (as a template writer): how do I use
71 >>> this piece of information programmatically in my templates, if I want all
72 >>> links with `reldepth==2` to be given the same style? I guess some bits of
73 >>> Javascript might do the trick, but if it's getting so complicated, I'll
74 >>> just style my parentlinks another way.
76 >>>> Perhaps I misunderstood what `is_grand_mother` is supposed to do. The
77 >>>> docs were not very clear to me. If it's supposed to be 2 down from
78 >>>> the page, (and not from the root), this could be achieved by reversing
79 >>>> the `depth_n` variables. So the page gets `depth_1` set, its parent gets
80 >>>> `depth_2` set, etc. If you want to be able to include/exclude
81 >>>> from both ends, you could also have a `height_n` that is 1 for the
82 >>>> root, and counts upwards. --[[Joey]]
84 >>> In my understanding, your suggestion gives us little more than can already
85 >>> be achieved anyway with `HTML::Template`'s `loop_context_vars` (i.e.
86 >>> `__first__`, `__last__` and `__counter__`). The only added bonus is doing
87 >>> custom stuff for an arbitrary element in the loop, chosen by its absolute
88 >>> depth. Please correct me if needed.
90 >>> (Intermezzo: in the meantime, to suit my personal real-world needs, I added
91 >>> a `DISTANCE` loop-variable. Quoting the documentation, it's "thedistance,
92 >>> expressed in path elements, from the current page to the current path
93 >>> element; e.g. this is 1 for the current page's mother, 2 for its
94 >>> grand-mother, etc.".)
96 >>> Anyway, your comments have made me think of other ways to simplify a bit
97 >>> this plugin, which admittedly provides too much overlapping functionality.
98 >>> Bellow is my reasoning.
100 >>> In one of my own real world examples, my two main use cases are :
102 >>> * the "full-blown example" provided in the documentation (i.e.
103 >>> displaying every parent but mother and grand'ma as a group, and giving
104 >>> every of these two last ones their dedicated div);
105 >>> * skipping the two oldest parents, and inside what's left, displaying the
106 >>> three youngest parents (i.e. mother, grand'ma and grand'grand'ma), each
107 >>> one with a dedicated style;
109 >>> Both of these can be achieved by combining `PEDIGREE`, `DISTANCE`, and some
110 >>> CSS tricks to hide some parts of the list. `IS_MOTHER` and
111 >>> `IS_GRAND_MOTHER`, as well as `PEDIGREE_BUT_TWO_OLDEST`, would be convenient
112 >>> shortcuts, but I do not formally need them.
114 >>> So... it seems things can be simplified greatly:
116 >>> * I initially added `RELDEPTH` for completeness, but I'm not sure anyone
117 >>> would use it. Let's give it up.
118 >>> * Once `RELDEPTH` is lost (modulo Git tendencies to preserve history), the
119 >>> known bug is gone as well, and `PEDIGREE_BUT_ROOT` and
120 >>> `PEDIGREE_BUT_TWO_OLDEST` are now only convenient shortcuts functions;
121 >>> they could as well disappear, if you prefer to.
123 >>> It appears then that I'd be personally happy with the single `PEDIGREE` loop
124 >>> (renamed to `PARENTLINKS`), providing only `PAGE`, `URL`, `ABSDEPTH` (maybe
125 >>> renamed to `DEPTH`), and `DISTANCE`. This would make my templates a bit more
126 >>> complicated to write and read, but would also keep the plugin's code to the
127 >>> bare minimum. Let's say it is my up-to-date proposal. (Well, if the various
128 >>> shortcuts don't really annoy you, I'd be glad to keep them ;)
130 >>>> This sounds fairly similar to what I just described above. (I called
131 >>>> DISTANCE "height".) I don't know about the CSS tricks; seems like if
132 >>>> `DEPTH_n` and `DISTANCE_n` are provided, you can test for them inside
133 >>>> the loop using HTML::Template's lame testing, and isolate any page or
134 >>>> range of pages. --[[Joey]]
136 >>>>> Ok, I definitely like this idea, as an effective and generic
137 >>>>> page-range selection tool; this seems the way to go to me.
139 >>>>> But if you discard the `DEPTH` and `HEIGHT`
140 >>>>> counters, we lack a way to **style**, for example, every parent link
141 >>>>> depending on its depth or height; one can do this for arbitrary
142 >>>>> parents (chosen by their height or depth), but *not* for *any* parent,
143 >>>>> since there is no way to express, with HTML::Template, something like
144 >>>>> "display the name of the only `DEPTH_n` variable that is currently
145 >>>>> true". So I am in favor of keeping the `DEPTH` and `HEIGHT` counters,
146 >>>>> to allow constructs like:
148 <TMPL_LOOP NAME="PARENTLINKS">
149 <a href="<TMPL_VAR NAME="URL">" class="parentdistance<TMPL_VAR NAME="DISTANCE">">
150 <TMPL_VAR NAME="PAGE">
154 >>>>> This seems to me a nice functionality bonus, and should not
155 >>>>> imply too bloated code. I'm thus going to rewrite the plugin
156 >>>>> with only `PEDIGREE`, `DEPTH`, `HEIGHT`, `DEPTH_n` and
157 >>>>> `HEIGHT_n`. -- intrigeri
159 >>>>>> Done, and pushed in my pedigree branch. Update: I've also done and
160 >>>>>> pushed two commits that rename the plugin and replace
161 >>>>>> the core parentlinks with this one. --[[intrigeri]]
163 (I'll try never to rebase this branch, but writing this plugin has
164 been a pretext for me to start learning Git, so...)
166 To finish with, it seems no plugin bundled with ikiwiki uses the current
167 parentlinks implementation, so one could event think of moving it from the
168 core to this plugin (which should then be enabled by default, since the
169 default templates do use parentlinks ;).
171 > I think that moving parentlinks out to a plugin is a good idea.
172 > However, if it's done, I think the plugin should be named parentlinks,
173 > and should continue to use the same template variables as are used now,
174 > to avoid needing to change custom templates. Pedigree is a quite nice
175 > name, but renaming it to parentlinks seems to be the way to go to me.
178 >> Agreed. -- intrigeri
180 >> Just commited a testsuite for this plugin, BTW. It's nearly twice
181 >> big as the plugin itself, I'm wondering... -- intrigeri
183 Merged, nice work. (Overkill having a test suite. ;-) --[[Joey]]
185 > Thanks. If the testsuite reveals itself to be harder to maintain than
186 > the plugin, my ego won't be offended to see it removed. It's been
187 > nice to find a way, step by step, to work with you on this small
188 > plugin thing. I'm starting to feel a bit at home in ikiwiki
189 > sourcetree, which is great since I may have to start working on some
190 > more ambitious ikiwiki stuff, such as the ~multilingual wiki
191 > (master language + translations) support. Expect news from me on
192 > this front in the next weeks. --[[intrigeri]]