doc/plugins/contrib/sidebar2.mdwn

   1 [[!template id=plugin name=sidebar2 author="[[Louis|spalax]]"]]
   2 [[!tag type/chrome]]
   3
   4 *Claim:* The [[sidebar|plugins/sidebar]] plugin has nothing
   5 to do with sidebars. This plugin renders some page (which happens to be named
   6 `sidebar`) and put the result in template variable `SIDEBAR`, in template
   7 `page.tmpl`. But the fact that it is a sidebar, i.e. a bar appearing on the
   8 side on the screen, is done by CSS.
   9
  10 What if I want a sidebar, and a [[navigation bar|plugins/contrib/navbar]], and
  11 a footer a bit more elaborated than the one in the template, etc.? This plugin
  12 allows this.
  13
  14 # Configuration
  15
  16 If no option is given, or if option `global_sidebars` is a boolean, this plugin
  17 is identical to the [[sidebar plugin|plugins/sidebar/]] (if not, please [report
  18 a bug](https://atelier.gresille.org/projects/gresille-ikiwiki/issues)).
  19 Otherwise, `global_sidebars` is a list of sidebars to include. The list is as
  20 follow:
  21
  22     global_sidebars => [
  23       "var1", "page1", "pagespec1",
  24       "var2", "page2", "pagespec2",
  25       ]
  26
  27 The meaning is: if available, render `page1` in pages matching `pagespec1`, and
  28 put it in variable `var1` of the page template, and so on for `var2`, `page2`,
  29 etc.
  30
  31 The default, which gives the behaviour of the sidebar plugin, is
  32 `global_sidebars => ["sidebar", "sidebar", "*"]`.
  33
  34 # Improvements over sidebar plugin
  35
  36 * You can add several "sidebars" to your wiki. For example, to have a sidebar, a submeno that appear only in pages documentations, and a footer, your `global_sidebars` would be:
  37
  38       global_sidebars => [
  39         "sidebar", "sidebar", "*",
  40         "menu", "/doc/menu", "doc/*",
  41         "footer", "/footer", "*"
  42         ]
  43
  44 * You can enable sidebars only in certain pages matching the pagespec. If, for
  45   the same template variable, several pagespec match the current page, the
  46   first page in the list is taken into account.
  47
  48   For example, the following configuration says: render `menu` as the sidebar
  49   for every page, excepted subpages of `doc`, for which the `doc_menu` page
  50   should be rendered.
  51
  52       global_sidebars => [
  53         "sidebar", "doc_menu", "doc/*",
  54         "sidebar", "menu", "*",
  55         ]
  56
  57 # Directive
  58
  59 The behaviour of the `sidebar` directive is similar to the directive of the
  60 original [[sidebar|plugins/sidebar]], excepted that a new `var` argument is
  61 available.
  62
  63 If this `var` argument is set, instead of applying to the default `sidebar`
  64 template variable, the directive applies to the value given in the argument.
  65
  66 For example, the following command forces the `footer` sidebar to appear on the
  67 current page.
  68
  69     \[[!sidebar var=footer]]
  70
  71 The following command forces the `footer` sidebar to appaer, containing the
  72 content given in argument.
  73
  74     \[[!sidebar var=footer content="TEST"]]
  75
  76 # Which pages to render?
  77
  78 Here is the decision process to decide what is rendered in a template variable
  79 handled by this plugin.
  80
  81 1. If the page contains the [[sidebar|ikiwiki/directive/sidebar]] directive, with a `content` argument, this content is rendered.
  82 2. If the page contains the [[sidebar|ikiwiki/directive/sidebar]] directive with no `content` argument, the first rule for the considered template variable is applied, disregarding the pagespec.
  83 3. If none of the above, the first rule having its pagespec patching the current page is applied.
  84 4. If none of the above, the variable is left empty.