pgsrc/Help%2FWikiPlugin

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