pgsrc/Help%2FWikiPlugin

   1 Date: Fri, 11 Jan 2013 11:16:51 +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
  21 A ~WikiPlugin allows one to easily add new types of dynamic
  22 content (as well as other functionality) to wiki pages within ~PhpWiki.
  23 In this very wiki all actions which are not entirely lowercased
  24 are implemented using plugins, and some lowercased convenience
  25 actions also.
  26 (rename, revert, setacl, diff, ...)
  27
  28 Note that you can NOT extend the markup syntax with a plugin, as in other wiki engines.
  29
  30 (The old-style [[Help:MagicPhpWikiURLs|MagicPhpWikiURLs]] have been replaced by plugins
  31 entirely.)
  32
  33 == Example ==
  34
  35 Currently, one invokes a plugin by putting something like:
  36
  37 {{{
  38 <<AllPages limit=20 cols=3>>
  39 }}}
  40
  41 into a regular wiki-page.  That particular example produces a list
  42 of the first 20 existing pages in 3 columns, via the [[Help:PageList|PageList]]
  43 library.
  44
  45 <<AllPages limit=20 cols=3>>
  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   {{{
  55   <?plugin BackLinks page=OtherPage ?>
  56   }}}
  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   {{{
  63   <?plugin BackLinks page ?>
  64   }}}
  65
  66 # Default values specified in the plugin invocation:
  67
  68   {{{
  69   <?plugin BackLinks page||=OtherPage ?>
  70   }}}
  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   {{{
  75     BackLinks?page=ThisPage&sortby=-mtime
  76   }}}
  77   (The BackLinks plugin uses the current page as the default value for
  78   the *page* argument.)
  79
  80   Most plugins using the [[Help:PageList|PageList]] library inherit their
  81   default arguments from the ~PageList.
  82
  83 === Standard Arguments ===
  84
  85 Most plugins display a list of pages, via the [[Help:PageList|PageList]]
  86 library. ~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 [[Help:PageList|PageList]] library documentation.
  92
  93 *exclude* and *pages* accept a list of pages. Either as comma-separated list,
  94 supporting glob-style wildcards, or via the ##<!plugin-list pluginname ~[args~] !>##
  95 invocation syntax, where pluginname might be any plugin returning a [[Help:PageList|PageList]].
  96 See PhpWiki:PluginList.
  97
  98 Since most plugins return a ~PageList, this ~PageList is also a common
  99 input parameter for other plugins, actions or formats.
 100
 101 === Basic Plugin Types ===
 102
 103 All these plugins derive from the ##~WikiPlugin## class extending the
 104 run method,
 105 which returns a object tree of HTML objects, and may react on any
 106 provided arguments from the ~WikiPage (see the args below) or
 107 optionally overridden by arguments from the url (GET or POST args),
 108 if defined via '||='.
 109
 110 A basic plugin just needs the run() method, and optionally getName,
 111 getDescription, getDefaultArguments. See the
 112 [[Help:HelloWorldPlugin]] for a short introduction.
 113
 114   **plugin** reacts on its arguments and the request and displays
 115   arbitrary HTML.
 116
 117   **plugin-form** is used to display a input type=text box for the
 118   default argument **s**.
 119
 120   **plugin-list** is used as argument to provide a dynamic list of
 121   pagenames.
 122
 123   {{{
 124     <?plugin PluginName [args...] ?>
 125   }}}
 126
 127   {{{
 128     <?plugin-form PluginName [args...] ?>
 129   }}}
 130
 131   {{{
 132     <?plugin PluginName args=<!plugin-list pluginname [args...] !> ?>
 133   }}}
 134
 135 ==== The box Method ====
 136
 137 Themes based on the "sidebar" theme may use the box method of any
 138 plugin, which displays a **title**
 139 and a condensed **content** in a box.
 140
 141 ==== ~WikiPluginCached ====
 142
 143 Plugins deriving from the class ~WikiPluginCached must also define
 144 the methods getPluginType(),
 145 optionally getExpire(), managesValidators(), and dependent of the
 146 getPluginType the methods to display the **possibly cached** result.
 147
 148   getImage(), getMap() or getHtml(),
 149
 150 optionally also
 151
 152   getAlt(), getImageType(), embedMap(), embedImg(), embedObject()
 153
 154 See the config.ini PLUGIN_CACHED_* settings and PhpWiki:WikiPluginCached
 155
 156 === Action Pages ===
 157
 158 The term **[[Help:ActionPage|ActionPage]]** refers to a page containing a plugin
 159 invocation with the same or translated pluginname as the pagename.
 160 An **action** is together with the **pagename** argument the basic
 161 ~PhpWiki argument.
 162 It can both be GET or POST actions. Actions are untranslated, always
 163 English, pagenames can be localized.
 164 Basic (and old) actions are all lowercase, like edit, browse, remove, ...
 165 Newer actions in [[PhpWiki:CamelCase]] are invoked via plugins on their
 166 specific action page.
 167
 168 We decoupled actions from plugins via action pages for the following
 169 reasons:
 170
 171 # Support translated action buttons and customizable action descriptions.
 172 # Customize standard actions by tuning the plugin invocation arguments.
 173   Override or add plugin defaults.
 174 # Split simple plugins into multiple actions, like RecentChanges/RecentEdits,
 175   MostPopular/LeastPopular, AllPages/AllPagesCreatedByMe/AllPagesLastEditedByMe/
 176   AllPagesOwnedByMe which differ only in one argument.
 177 # Simplify the syntax for actions on another actions using a ~PageList
 178   as result of an actionpage as input parameter for another action or
 179   format.
 180
 181 * Those actions which have buttons or links in the theme or are
 182   referenced in the standard pgsrc pageset require their
 183   (possibly localized) actionpages, otherwise the actions will not work.
 184 * If the localized actionpage is not found the english version is
 185   used.
 186 * If no actionpage is found, it is recommended to do action=upgrade,
 187   which imports all missing and required action pages into the database.
 188
 189 So for a hypothetical new ~MyActionPage plugin ~MyActionPage will
 190 invoke the plugin and ~Help:~MyActionPagePlugin should be the description page.
 191
 192 == Existing Plugins ==
 193
 194 See [[PluginManager]] for a detailed list. Most plugins should have their
 195 own description page as subpage of **Help/** with the name **Plugin**
 196 appended.
 197
 198 ----
 199 [[PhpWikiDocumentation]]