pgsrc/Help%2FWikiPlugin

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