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.5 2007-01-04 16:43:39 rurban Exp $
4 Content-Type: application/x-phpwiki;
5 pagename=Help%2FWikiPlugin;
6 pgsrc_version="2 $Revision: 1.5 $";
10 Content-Transfer-Encoding: binary
12 Since PhpWiki-1.3.3 support for ~WikiPlugins is included.
14 A plugin is some PHP code that
16 * lives in =phpwiki/lib/plugin/<pluginname>.php=
17 * implements the ~WikiPlugin interface by extending that class.
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"].
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].
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, ...)
34 The old-style Help:MagicPhpWikiURLs have been replaced by plugins entirely.
38 Currently, one invokes a plugin by putting something like:
41 <?plugin AllPages limit=20 col=3?>
44 into a regular wiki-page. That particular example produces a list of
45 the first 20 existing pages in 3 columns, via the PhpWiki:PageListLibrary.
47 <?plugin AllPages limit=20 cols=3 ?>
51 Plugins can take certain named arguments (most do). The values of
52 these arguments can be determined four different ways. In order of
55 # The plugin invocation can specify the value for an argument, like so:
57 <?plugin BackLinks page=OtherPage ?>
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:
65 <?plugin BackLinks page ?>
68 # Default values specified in the plugin invocation:
71 <?plugin BackLinks page||=OtherPage ?>
74 # The plugin must supply default values for each argument it uses.
75 Such default args may be overriden by URL arguments like so:
77 BackLinks?page=ThisPage&sortby=-mtime
79 (The BackLinks plugin uses the current page as the default value for
80 the ''page'' argument.)
82 Most plugins using the ~PageListLibrary inherit their default arguments
83 from the PhpWiki:PageListLibrary.
87 Most plugins display a list of pages, via the ~PageListLibrary.
88 ~PageList provides automatic support for those arguments.
90 info, exclude, author, owner, creator, sortby, limit, paging, cols, azhead,
91 comma, commasep, ordered
93 For details see the PhpWiki:PageListLibrary documentation.
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.
100 !! Basic Plugin Types
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 '||='.
108 A basic plugin just needs the run() method, and optionally getName,
109 getDescription, getVersion, getDefaultArguments. See the Help:HelloWorldPlugin for a short introduction.
111 *plugin* reacts on its arguments and the request and displays arbitrary HTML.
113 *plugin-form* is used to display a input type=text box for the default argument *s*.
115 *plugin-list* is used as argument to provide a dynamic list of pagenames.
118 <?plugin PluginName Help:s ...] ?>
122 <?plugin-form PluginName Help:s ...] ?>
126 <?plugin PluginName args=<!plugin-list pluginname Help:s ] !> ?>
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.
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.
140 getImage(), getMap() or getHtml(),
144 getAlt(), getImageType(), embedMap(), embedImg(), embedObject()
146 See the config.ini PLUGIN_CACHED_* settings and PhpWiki:WikiPluginCached
150 The term *Help:ActionPage* refers to a page containing a plugin invocation, which takes
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.
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.
157 We decoupled actions from plugins via action pages for the following reasons:
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.
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.
170 So for a hypothetical new ~MyActionPage plugin ~MyActionPage will invoke the plugin and
171 ~MyActionPagePlugin is the the description.
175 See PluginManager for a detailed list. All plugins should have their own
176 description page as subpage of *Help/* with the name *Plugin* appended.
178 <?plugin BackLinks noheader=1 ?>
180 !!! Contributed Plugins
182 See PhpWiki:CategoryContributedPlugin.
184 <?plugin Backlinks page=CategoryContributedPlugin ?>