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