pgsrc/Help%2FWikiPlugin

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