git.oblomov.eu Git - ikiwiki/blob - doc/todo/firm_up_plugin_interface.mdwn

   1 The plugin interface is currently that they can register hooks, and can
   2 call any other ikiwiki internal function they desire, generally through
   3 Ikiwiki::function calls. Also, some Ikiwiki::config etc variables can be
   4 used.
   5
   6 This is a very weak interface, and should be firmed up to something more
   7 like a proper perl library. I've been waiting to get some idea of what bits
   8 of ikiwiki are most useful to plugins before doing it; there are plenty of
   9 plugins to know that now.
  10
  11 IkiWiki will now  export some function calls and variables when loaded.
  12
  13 Functions used by many plugins, which I'm sure should be exported:
  14
  15 * hook
  16 * debug
  17 * error
  18 * template
  19 * htmlpage
  20 * add_depends
  21 * pagespec_match
  22 * bestlink
  23 * htmllink
  24 * readfile
  25 * writefile
  26 * pagetype
  27 * srcfile
  28 * pagename
  29 * displaytime
  30
  31 Functions used by only some plugins, undecided:
  32
  33 * lockwiki, unlockwiki (aggregate)
  34         Too internal to ever be exported.
  35 * loadindex (aggregate)
  36         Too internal to ever be exported.
  37 * titlepage (aggregate)
  38         Not until more than one thing uses it.
  39 * basename (polygen, inline, search, polygen)
  40 * dirname (linkmap, inline)
  41         For basename and dirname, they could just use standard perl library
  42         stuff. Howevever, ikiwiki's versions are slightly different and I'd
  43         need to check if the standard versions work for the uses made in
  44         these plugins. Inclined not to export.
  45 * abs2rel (linkmap, inline)
  46         This *is* the library version, just optimised to work around a bug.
  47         Don't export this.
  48 * possibly_foolish_untaint (aggregate, polygen)
  49         Probably better to implement yourself.
  50 * htmlize
  51 * linkify
  52 * preprocess
  53 * filter
  54         Used by several, but problimatic since plugins typically define
  55         functions with these names..
  56
  57 Variables used by plugins:
  58
  59 * %IkiWiki::config (various values; probably not worth locking down any
  60   more, export it)
  61 * %IkiWiki::links (many, seems clearcut to export)
  62 * %IkiWiki::renderedfiles (orphans, inline, search)
  63 * %IkiWiki::pagesources (pagecount, sidebar, template, inline)
  64 * %IkiWiki::pagecase (aggregate.. will not export yet)
  65 * %IkiWIki::backlinks (pagestats.. will not export yet)
  66
  67 I don't want this interface to be too firm; it's ok for a plugin like
  68 `ddate` to redefine an internal function like IkiWiki::displaytime if it
  69 wants to.. But plugins that still access stuff through IkiWiki:: should be
  70 aware that that stuff can change at any time and break them. Possibly without
  71 perl's type checking catching the breakage, in some cases. Plugins that
  72 only use exported symbols should not break by future ikiwiki changes.