doc/todo/conditional_text_based_on_ikiwiki_features.mdwn

   1 I'd like to see some way to conditionally include wiki text based on
   2 whether the wiki enables or disables certain features.  For example,
   3 [[ikiwiki/formatting]], could use `\[[!if (enabled smiley) """Also, because
   4 this wiki has the smiley plugin enabled, you can insert \[[smileys]] and
   5 some other useful symbols."""]]`, and a standard template for [[plugins]]
   6 pages could check for the given plugin name to print "enabled" or
   7 "disabled".
   8
   9 Some potentially useful conditionals:
  10
  11 * `enabled pluginname`
  12 * `disabled pluginname`
  13 * `any pagespec`: true if any of the pages in the [[ikiwiki/PageSpec]] exist
  14 * `all pagespec`: true if all of the pages in the [[ikiwiki/PageSpec]] exist
  15 * `no pagespec` or `none pagespec`: true if none of the pages in the [[ikiwiki/PageSpec]] exist
  16 * `thispage pagespec`: true if pagespec includes the page getting rendered (possibly one including the page with this content on it).
  17 * `sourcepage pagespec`: true if pagespec includes the page corresponding to the file actually containing this content, rather than a page including it.
  18 * `included`: true if included on another page, via [[plugins/inline]], [[plugins/sidebar]], [[plugins/contrib/navbar]], etc.
  19
  20 You may or may not want to include boolean operations (`and`, `or`, and
  21 `not`); if you do, you could replace `disabled` with `not enabled`, and `no
  22 pagespec` or `none pagespec` with `not any pagespec` (but you may want to
  23 keep the aliases for simplicity anyway).  You also may or may not want to
  24 include an `else` clause; if so, you could label the text used if true as
  25 `then`.
  26
  27 Syntax could vary greatly here, both for the
  28 [[ikiwiki/Directive]] and for the condition itself.
  29
  30 > I think this is a good thing to consider, although conditionals tend to
  31 > make everything a lot more complicated, so I also want to KISS, and not
  32 > use too many of them.
  33 >
  34 > I'd probably implement this using the same method as pagespecs, so 'and',
  35 > 'or', '!', and paren groupings work.
  36 >
  37 > It could be thought of as simply testing to see if a pagespec matches
  38 > anything, using a slightly expanded syntax for the pagespec, which would
  39 > also allow testing for things like link(somepage),
  40 > created_before(somepage), etc.
  41 >
  42 > That also gives us your "any pagespec" for free: "page or page or page".
  43 > And for "all pagespec", you can do "page and page and page".
  44 >
  45 > For plugins testing, maybe just use "enabled(name)"?
  46 >
  47 > I'm not sure what the use cases are for thispage, sourcepage, and
  48 > included. I don't know if the included test is even doable. I'd be
  49 > inclined to not bother with these three unless there are use cases I'm
  50 > not seeing.
  51 >
  52 > As to the syntax, to fit it into standard preprocessor syntax, it would
  53 > need to look something like this:
  54 >
  55 >       \[[!if test="enabled(smiley)" """foo"""]]
  56 >
  57 > --[[Joey]]
  58
  59 >> [[ikiwiki/PageSpec]] syntax seems perfect, and your proposed syntax for the `if`
  60 >> [[ikiwiki/Directive]] looks fine to me.
  61 >>
  62 >> [[ikiwiki/PageSpec]]s don't give you `none` for free, since `!foo/*` as a boolean
  63 >> would mean "does any page not matching `foo/*` exist", not "does `foo/*`
  64 >> match nothing"; however, I don't really care much about `none`, since I
  65 >> just threw it in while brainstorming, and I don't know any compelling use
  66 >> cases for it.
  67 >>
  68 >> `enabled(pluginname)` will work perfectly, and `!enabled(pluginname)`
  69 >> makes `disabled` unnecessary.
  70 >>
  71 >> A few use cases for `included`, which I would really like to see:
  72 >>
  73 >> * On the sidebar page, you could say something like \[[!if test="!included"
  74 >>   """This page, without this help message, appears as a sidebar on all
  75 >>   pages."""]].  The help text would then only appear on the sidebar page
  76 >>   itself, not the sidebar included on all pages.
  77 >>
  78 >> * On [[blog]] entries, you could use `included` to implement a cut.
  79 >>   (Please don't take that as an argument against. :) ) For instance, you
  80 >>   could use included rather than [[plugins/toggle]] for the detailed
  81 >>   changelogs of ikiwiki, or to embed an image as a link in the feed rather
  82 >>   than an embedded image.
  83 >>
  84 >> Some use cases for `thispage`:
  85 >>
  86 >> * You could use `thispage` to include or exclude parts of the sidebar based
  87 >>   on the page you include it in.  You can already use subpages/sidebar for
  88 >>   subpages/*, but `thispage` seems more flexible, makes it trivial to have
  89 >>   common portions rather than using [[plugins/inline]] with the `raw`
  90 >>   option, and keeps the sidebar in one place.
  91 >>
  92 >> * You could use `thispage` to implement multiple different feeds for the
  93 >>   same content with slightly different presentation.  For instance, using
  94 >>   templates for image inclusion, you could offer a feed with image links
  95 >>   and a feed with embedded images. Similarly, using templates for cuts, you
  96 >>   could offer a feed with cuts and a feed with full content in every post.
  97 >>
  98 >> I don't have any particular attachment to `sourcepage`.  It only makes
  99 >> sense as part of a template, since otherwise you know the source page when
 100 >> typing in the if.
 101 >>
 102 >> --[[JoshTriplett]]
 103
 104 This is now completely [[todo/done]]! See [[plugins/conditional]].
 105
 106 --[[Joey]]
 107
 108 > You rock mightily. --[[JoshTriplett]]
 109
 110 Is there a way to test features other than plugins? For example,
 111 to add to [[ikiwiki/Markdown]] something like
 112
 113     \[[!if test="enabled(multimarkdown)" then="You can also use..."]]
 114
 115 (I tried it like that just to see if it would work, but I wasn't that lucky.)
 116 --ChapmanFlack
 117
 118 > No, not supported. I really think that trying to conditionalise text on a
 119 > page for multimarkdown is a path to madness or unreadability though.
 120 > Perhaps it would be better to have .mmdwn files that can only contain
 121 > multimarkdown? --[[Joey]]
 122
 123 >> Really, there was only one (or maybe two) pages I had in mind as appropriate
 124 >> places for conditional text based on multimarkdown&mdash;the underlay pages
 125 >> for 'markdown' and maybe also 'formatting', because those are the pages you
 126 >> look at when you're trying to find out how to mark stuff up for the wiki, so
 127 >> if MM is enabled, they need to at least mention it and have a link to the
 128 >> MM syntax guide.--ChapmanFlack