doc/bugs/template_evaluation_oddities.mdwn

   1 [[ikiwiki/directive/template]]s expose odd behavior when it comes to composing
   2 links and directives:
   3
   4 * the parameters are passed through the preprocessor twice, once on
   5   per-parameter basis and once for the final result (which usually contains the
   6   preprocessed parameters).
   7
   8   one of the results it that you have to write:
   9
  10       \[[!template id="infobox" body="""
  11           Just use the \\\[[!template]] directive!
  12       """]]
  13
  14   (that'd be three backslashes in front of the opening [.)
  15
  16   <!-- if you read this and wonder why there are only three backslashes in the
  17   source code too, look at how backslash-escaping directives is implemented.
  18   -->
  19
  20   this also means that parts which are not used by the template at all still
  21   have their side effects without showing.
  22
  23   furthermore, the evaluation sequence is hard to predict. this might or might
  24   not be a problem, depending on whether someone comes up with a less contrived
  25   example (this one assumes a ``\[[!literal value]]`` directive that just
  26   returns value but protects it from the preprocessor):
  27
  28   we can use `\[[!literal """[[!invalid example]]"""]]`, but we can't use
  29   `\[[!template id=literalator value="""[[!invalid example]]"""]]` with a
  30   'literalator' template `<span class="literal">\[[!literal """<TMPL_VAR
  31   value>"""]]</span>` because then the `invalid` directive comes to action in
  32   the first (per-argument) preprocessor run
  33
  34 * links in templates are not stored at all; they appear, but the backlinks
  35   don't work unless the link is explicit in one of the arguments.
  36
  37       \[[!template id="linker" destination="foo"]]
  38
  39   with a 'linker' template like
  40
  41       Go to \[[<TMPL_VAR destination>]]!
  42
  43   would result in a link to 'destination', but would not be registered in the
  44   scan phase and thus not show a backlink from 'foo'.
  45
  46   (a ``\[[!link to=...]]`` directive, as suggested in
  47   [[todo/flexible relationships between pages]], does get evaluated properly
  48   though.)
  49
  50   this seems to be due to linkification being called before preprocess rather
  51   than as a part of it, or (if that is on purpose) by the template plugin not
  52   running linkification as an extra step (not even once).
  53
  54 (nb: there is a way to include the ``raw_`` value of a directive, but that only
  55 refers to htmlification, not directive evaluation.)
  56
  57 both those behaviors are non-intuitive and afaict undocumented. personally, i'd
  58 swap them out for passing the parameters as-is to the template, then running
  59 the linkifier and preprocessor on the final result. that would be as if all
  60 parameters were queried `raw_` -- then again, i don't see where `raw_` makes
  61 anything not work that worked originally, so obviously i'm missing something.
  62
  63
  64 i think it boils down to one question: are those behaviors necessary for
  65 compatibility reasons, and if yes, why?
  66
  67 --[[chrysn]]