pgsrc/Help%2FWikiPlugin

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