doc/todo/pedigree_plugin.mdwn

   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.
   5
   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
  10 by parentlinks.
  11
  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
  15 distance to it.
  16
  17 The code and documentation (including simple and complex usage
  18 examples) are in the 'pedigree' Git branch in this repo:
  19
  20         git://repo.or.cz/ikiwiki/intrigeri.git
  21
  22 Seems there is also a [gitweb](http://repo.or.cz/w/ikiwiki/intrigeri.git).
  23
  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]]
  26
  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
  30
  31 Any opinions on the idea/design/implementation?
  32
  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:
  38
  39         <TMPL_LOOP NAME="PEDIGREE">
  40           <TMPL_IF NAME="depth_1">
  41             </TMPL_ELSE>
  42             <TMPL_IF NAME="depth_2">
  43             </TMPL_ELSE>
  44               <TMPL_VAR PAGE> /* only showing pages 2 levels deep */
  45             </TMPL_IF>
  46           </TMPL_IF>
  47         </TMPL_LOOP>
  48
  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!)
  52 >
  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]]
  55
  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
  60
  61 >>> Well, I maybe didn't get your idea properly; I may be missing
  62 >>> something obvious, but:
  63
  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.
  75
  76 >>> In my understanding, your suggestion gives us little more than can already
  77 >>> be achieved anyway with `HTML::Template`'s `loop_context_vars` (i.e.
  78 >>> `__first__`, `__last__` and `__counter__`). The only added bonus is doing
  79 >>> custom stuff for an arbitrary element in the loop, chosen by its absolute
  80 >>> depth. Please correct me if needed.
  81
  82 >>> (Intermezzo: in the meantime, to suit my personal real-world needs, I added
  83 >>> a `DISTANCE` loop-variable. Quoting the documentation, it's "thedistance,
  84 >>> expressed in path elements, from the current page to the current path
  85 >>> element; e.g. this is 1 for the current page's mother, 2 for its
  86 >>> grand-mother, etc.".)
  87
  88 >>> Anyway, your comments have made me think of other ways to simplify a bit
  89 >>> this plugin, which admittedly provides too much overlapping functionality.
  90 >>> Bellow is my reasoning.
  91
  92 >>> In one of my own real world examples, my two main use cases are :
  93
  94 >>> * the "full-blown example" provided in the documentation (i.e.
  95 >>>   displaying every parent but mother and grand'ma as a group, and giving
  96 >>>   every of these two last ones their dedicated div);
  97 >>> * skipping the two oldest parents, and inside what's left, displaying the
  98 >>>   three youngest parents (i.e. mother, grand'ma and grand'grand'ma), each
  99 >>>   one with a dedicated style;
 100
 101 >>> Both of these can be achieved by combining `PEDIGREE`, `DISTANCE`, and some
 102 >>> CSS tricks to hide some parts of the list. `IS_MOTHER` and
 103 >>> `IS_GRAND_MOTHER`, as well as `PEDIGREE_BUT_TWO_OLDEST`, would be convenient
 104 >>> shortcuts, but I do not formally need them.
 105
 106 >>> So... it seems things can be simplified greatly:
 107
 108 >>> * I initially added `RELDEPTH` for completeness, but I'm not sure anyone
 109 >>>   would use it. Let's give it up.
 110 >>> * Once `RELDEPTH` is lost (modulo Git tendencies to preserve history), the
 111 >>>   known bug is gone as well, and `PEDIGREE_BUT_ROOT` and
 112 >>>   `PEDIGREE_BUT_TWO_OLDEST` are now only convenient shortcuts functions;
 113 >>>   they could as well disappear, if you prefer to.
 114
 115 >>> It appears then that I'd be personally happy with the single `PEDIGREE` loop
 116 >>> (renamed to `PARENTLINKS`), providing only `PAGE`, `URL`, `ABSDEPTH` (maybe
 117 >>> renamed to `DEPTH`), and `DISTANCE`. This would make my templates a bit more
 118 >>> complicated to write and read, but would also keep the plugin's code to the
 119 >>> bare minimum. Let's say it is my up-to-date proposal. (Well, if the various
 120 >>> shortcuts don't really annoy you, I'd be glad to keep them ;)
 121
 122
 123 (I'll try never to rebase this branch, but writing this plugin has
 124 been a pretext for me to start learning Git, so...)
 125
 126 To finish with, it seems no plugin bundled with ikiwiki uses the current
 127 parentlinks implementation, so one could event think of moving it from the
 128 core to this plugin (which should then be enabled by default, since the
 129 default templates do use parentlinks ;).
 130
 131 > I think that moving parentlinks out to a plugin is a good idea.
 132 > However, if it's done, I think the plugin should be named parentlinks,
 133 > and should continue to use the same template variables as are used now,
 134 > to avoid needing to change custom templates. Pedigree is a quite nice
 135 > name, but renaming it to parentlinks seems to be the way to go to me.
 136 > --[[Joey]]
 137
 138 >> Agreed. -- intrigeri
 139
 140 >> Just commited a testsuite for this plugin, BTW. It's nearly twice
 141 >> big as the plugin itself, I'm wondering... -- intrigeri
 142