pgsrc/Help%2FWikiPlugin

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