pgsrc/Help%2FWikiPlugin

   1 Date: Mon, 14 Nov 2006 02:20:43 -0800
   2 Mime-Version: 1.0 (Produced by PhpWiki 1.3.13)
   3 X-Rcs-Id: $Id: Help%2FWikiPlugin,v 1.3 2007-01-02 13:24:58 rurban Exp $
   4 Content-Type: application/x-phpwiki;
   5   pagename=Help%2FWikiPlugin;
   6   pgsrc_version="2 $Revision: 1.3 $";
   7   flags="";
   8   markup=2;
   9   charset=iso-8859-1
  10 Content-Transfer-Encoding: binary
  11
  12 Since PhpWiki-1.3.3 support for ~WikiPlugins is included.
  13
  14 A plugin is some PHP code that
  15
  16 * lives in =phpwiki/lib/plugin/<pluginname>.php=
  17 * implements the ~WikiPlugin interface by extending that class.
  18
  19 There are many plugins already distributed with PhpWiki. Simply look in the =lib/plugin=
  20 directory or see the PluginManager list.
  21
  22 To write your own, look at the HelloWorldPlugin (~HelloWorld.php in that directory),
  23 which is a minimal example of a plugin.
  24 Publish your self-written plugin at a new PhpWiki page with ~PluginName + *Plugin* appended
  25 and add a link to [CategoryContributedPlugin | PhpWiki:CategoryContributedPlugin].
  26
  27 A Help:WikiPlugin allows one to easily add new types of dynamic content
  28 (as well as other functionality) to wiki pages within PhpWiki.
  29 In this very wiki all actions which are not entirely lowercased
  30 are implemented using plugins, and some lowercased convenience actions also. (rename, revert, setacl, diff, ...)
  31
  32 (The old-style  Help:MagicPhpWikiURLs have been replaced by plugins entirely.)
  33
  34 !!!Example
  35
  36 Currently, one invokes a plugin by putting something like:
  37
  38 <verbatim>
  39 <?plugin AllPages limit=5?>
  40 </verbatim>
  41
  42 into a regular wiki-page.  That particular example produces a list of
  43 the first 5 existing pages (via the ~PageList library).
  44
  45 <?plugin AllPages limit=5 ?>
  46
  47 !!!Details
  48
  49 Plugins can take certain named arguments (most do).  The values of
  50 these arguments can be determined four different ways.  In order of
  51 precedence:
  52
  53 # The plugin invocation can specify the value for an argument, like so:
  54   <verbatim>
  55   <?plugin BackLinks page=OtherPage ?>
  56   </verbatim>
  57
  58 # The argument can be specified via an HTTP query argument.  This
  59   doesn't happen (is not allowed) unless the argument is mentioned in
  60   the plugin invocation:
  61
  62   <verbatim>
  63   <?plugin BackLinks page ?>
  64   </verbatim>
  65
  66 # Default values specified in the plugin invocation:
  67
  68   <verbatim>
  69   <?plugin BackLinks page||=OtherPage ?>
  70   </verbatim>
  71
  72 # The plugin must supply default values for each argument it uses.
  73   Such default args may be overriden by URL arguments like so:
  74   <verbatim>
  75     BackLinks?page=ThisPage&sortby=-mtime
  76   </verbatim>
  77   (The BackLinks plugin uses the current page as the default value for
  78   the ''page'' argument.)
  79
  80   Most plugins using the ~PageListLibrary inherit their default arguments
  81   from the PhpWiki:PageListLibrary.
  82
  83 !! Standard Arguments
  84
  85 Most plugins display a list of pages, via the ~PageListLibrary.
  86 ~PageList provides automatic support for those arguments.
  87
  88   info, exclude, author, owner, creator, sortby, limit, paging, cols, azhead,
  89   comma, commasep, ordered
  90
  91   For details see the PhpWiki:PageListLibrary documentation.
  92
  93 *exclude* and *pages* accept a list of pages. Either as comma-seperated list,
  94 supporting glob-style wildcards, or via the <tt><!plugin-list pluginname ~[args~] !></tt>
  95 invocation syntax, where pluginname might be any plugin returning a pagelist.
  96 See PhpWiki:PluginList.
  97
  98 !! Basic Plugin Types
  99
 100 All these plugins derive from the Help:WikiPlugin class extending the run method,
 101 which returns a object tree of HTML objects, and may react on any
 102 provided arguments from the ~WikiPage (see the args below) or
 103 optionally overridden by arguments from the url (GET or POST args),
 104 if defined via '||='.
 105
 106 A basic plugin just needs the run() method, and optionally getName,
 107 getDescription, getVersion, getDefaultArguments. See the Help:HelloWorldPlugin for a short introduction.
 108
 109   *plugin* reacts on its arguments and the request and displays arbitrary HTML.
 110
 111   *plugin-form* is used to display a input type=text box for the default argument *s*.
 112
 113   *plugin-list* is used as argument to provide a dynamic list of pagenames.
 114
 115   <verbatim>
 116     <?plugin PluginName  Help:s ...] ?>
 117   </verbatim>
 118
 119   <verbatim>
 120     <?plugin-form PluginName  Help:s ...] ?>
 121   </verbatim>
 122
 123   <verbatim>
 124     <?plugin PluginName args=<!plugin-list pluginname  Help:s ] !> ?>
 125   </verbatim>
 126
 127 ! The box Method
 128
 129 Themes based on the "sidebar" theme may use the box method of any plugin, which displays a *title*
 130 and a condensed *content* in a box.
 131
 132 ! ~WikiPluginCached
 133
 134 Plugins deriving from the class ~WikiPluginCached must also define the methods getPluginType(),
 135 optionally getExpire(), managesValidators(), and dependent of the getPluginType the methods
 136 to display the *possibly cached* result.
 137
 138   getImage(), getMap() or getHtml(),
 139
 140 optionally also
 141
 142   getAlt(), getImageType(), embedMap(), embedImg(), embedObject()
 143
 144 See the config.ini PLUGIN_CACHED_* settings and PhpWiki:WikiPluginCached
 145
 146 !! Action Pages
 147
 148 The term *~ActionPage* refers to a page containing a plugin invocation.
 149 An *action* is together with the *pagename* argument the a basic PhpWiki argument.
 150 It can both be GET or POST actions. Actions are untranslated, always english.
 151 Basic (and old) actions are all lowercase, like edit, browse, remove, ...
 152 Newer actions in PhpWiki:CamelCase are invoked via plugins on their specific action page.
 153
 154 We decoupled actions from plugins via action pages for the following reasons:
 155
 156 # support translated action buttons and customizable action descriptions.
 157 # customize standard actions by tuning the plugin invocation arguments. override or add plugin defaults.
 158 # split simple plugins into multiple actions, like RecentChanges/RecentEdits, MostPopular/LeastPopular,
 159   AllPages/AllPagesCreatedByMe/AllPagesLastEditedByMe/AllPagesOwnedByMe which differ only in one argument.
 160
 161 * Those actions which have buttons or links in the theme or are referenced in the standard pgsrc
 162   pageset require their (possibly localized) actionpages, otherwise the actions will not work.
 163 * If the localized actionpage is not found the english version is used.
 164 * If no actionpage is found, it is recommended to do action=upgrade, which imports all missing
 165   and required action pages into the database.
 166
 167 So for a hypothetical new ~MyActionPage plugin ~MyActionPage will invoke the plugin and
 168 ~MyActionPagePlugin is the the description.
 169
 170 !!! Existing Plugins
 171
 172 See PluginManager for a detailed list. Most plugins should have their own description page with the name
 173 *Plugin* appended.
 174
 175 <?plugin BackLinks noheader=1 ?>
 176
 177 !!! Contributed Plugins
 178
 179 See PhpWiki:CategoryContributedPlugin.
 180
 181 <?plugin Backlinks page=CategoryContributedPlugin ?>
 182
 183 -----
 184 PhpWikiDocumentation