Differences between version 4 and predecessor to the previous major change of Help/WikiPlugin.
Other diffs: Previous Revision, Previous Author
Newer page: |
version 4 |
Last edited on 22 May 2014 3:01 |
by harold |
Revert |
Older page: |
version 3 |
Last edited on 9 September 2007 0:16 |
by harold |
Revert |
@@ -1,147 +1,141 @@
-Since PhpWiki-1.3.3 support for ~WikiPlugins is included.
-
-
A plugin is some PHP code that
-
-* lives in =
phpwiki/lib/plugin/<pluginname>.php=
+A **
plugin**
is some PHP code that:
+* lives in ##
phpwiki/lib/plugin/<pluginname>.php##
* implements the ~WikiPlugin interface by extending that class.
-There are many plugins already distributed with PhpWiki. Simply look
-in the =
lib/plugin=
directory or see the PluginManager list or see all the
-[Help/*Plugin pages|
phpwiki:TitleSearch?s=Help/*Plugin].
+There are many plugins already distributed with ~
PhpWiki. Simply look
+in the ##
lib/plugin##
directory or see the [[
PluginManager]]
list or see all the
+[[
phpwiki:TitleSearch?s=Help/*Plugin|Help/*Plugin pages]
].
-To write your own, look at the Help:HelloWorldPlugin (~HelloWorld.php
+To write your own, look at the [[
Help:HelloWorldPlugin]]
(~HelloWorld.php
in that directory), which is a minimal example of a plugin.
-Publish your self-written plugin at a new PhpWiki page with
-~PluginName + *Plugin* appended
-and add a link to [CategoryContributedPlugin | PhpWiki:CategoryContributedPlugin].
-A Help:
WikiPlugin allows one to easily add new types of dynamic
-content (as well as other functionality) to wiki pages within PhpWiki.
+A ~
WikiPlugin allows one to easily add new types of dynamic
+content (as well as other functionality) to wiki pages within ~
PhpWiki.
In this very wiki all actions which are not entirely lowercased
are implemented using plugins, and some lowercased convenience
actions also.
(rename, revert, setacl, diff, ...)
Note that you can NOT extend the markup syntax with a plugin, as in other wiki engines.
-(The old-style
Help:MagicPhpWikiURLs have been replaced by plugins
+(The old-style [[
Help:MagicPhpWikiURLs|MagicPhpWikiURLs]]
have been replaced by plugins
Currently, one invokes a plugin by putting something like:
-<verbatim>
-<?plugin
AllPages limit=20 cols=3 ?
>
-</verbatim>
+{{{
+<<
AllPages limit=20 cols=3>
>
+}}}
into a regular wiki-page. That particular example produces a list
-of the first 20 existing pages in 3 columns, via the PhpWiki
:PageList
+of the first 20 existing pages in 3 columns, via the [[Help
:PageList|PageList]]
-<?plugin
AllPages limit=20 cols=3 ?
>
+<<
AllPages limit=20 cols=3>
>
Plugins can take certain named arguments, most do. The values of
these arguments can be determined four different ways. In order of
precedence:
# The plugin invocation can specify the value for an argument, like so:
<?plugin BackLinks page=OtherPage ?>
# The argument can be specified via an HTTP query argument. This
doesn't happen (is not allowed) unless the argument is mentioned in
the plugin invocation:
<?plugin BackLinks page ?>
# Default values specified in the plugin invocation:
<?plugin BackLinks page||=OtherPage ?>
# The plugin must supply default values for each argument it uses.
Such default args may be overriden by URL arguments like so:
BackLinks?page=ThisPage&sortby=-mtime
(The BackLinks plugin uses the current page as the default value for
the *page* argument.)
- Most plugins using the PhpWiki
:PageList library inherit their
+ Most plugins using the [[Help
:PageList|PageList]]
library inherit their
default arguments from the ~PageList.
+===
Standard Arguments ===
-Most plugins display a list of pages, via the PhpWiki
:PageList
+Most plugins display a list of pages, via the [[Help
:PageList|PageList]]
library. ~PageList provides automatic support for those arguments.
info, exclude, author, owner, creator, sortby, limit, paging, cols, azhead,
comma, commasep, ordered
- For details see the PhpWiki
:PageList library documentation.
+ For details see the [[Help
:PageList|PageList]]
library documentation.
-*exclude* and *pages* accept a list of pages. Either as comma-seperated
list,
-supporting glob-style wildcards, or via the <tt>
<!plugin-list pluginname ~[args~] !></tt>
-invocation syntax, where pluginname might be any plugin returning a PhpWiki
:PageList.
+*exclude* and *pages* accept a list of pages. Either as comma-separated
list,
+supporting glob-style wildcards, or via the ##
<!plugin-list pluginname ~[args~] !>##
+invocation syntax, where pluginname might be any plugin returning a [[Help
:PageList|PageList]]
.
See PhpWiki:PluginList.
Since most plugins return a ~PageList, this ~PageList is also a common
input parameter for other plugins, actions or formats.
+===
Basic Plugin Types ===
-All these plugins derive from the Help:
WikiPlugin class extending the
+All these plugins derive from the ##~
WikiPlugin##
class extending the
run method,
which returns a object tree of HTML objects, and may react on any
provided arguments from the ~WikiPage (see the args below) or
optionally overridden by arguments from the url (GET or POST args),
if defined via '||='.
A basic plugin just needs the run() method, and optionally getName,
-getDescription, getVersion
, getDefaultArguments. See the
-Help:HelloWorldPlugin for a short introduction.
+getDescription, getDefaultArguments. See the
+[[
Help:HelloWorldPlugin]]
for a short introduction.
- *plugin* reacts on its arguments and the request and displays
+ *
*plugin*
* reacts on its arguments and the request and displays
- *plugin-form* is used to display a input type=text box for the
- default argument *s*.
+ *
*plugin-form*
* is used to display a input type=text box for the
+ default argument *
*s*
*.
- *plugin-list* is used as argument to provide a dynamic list of
+ *
*plugin-list*
* is used as argument to provide a dynamic list of
- <verbatim>
- <?plugin PluginName argument=value
... ?>
- </verbatim>
+ {{{
+ <?plugin PluginName [args
...]
?>
+ }}}
- <verbatim>
- <?plugin-form PluginName argument=value
... ?>
- </verbatim>
+ {{{
+ <?plugin-form PluginName [args
...]
?>
+ }}}
- <verbatim>
- <?plugin PluginName args=<!plugin-list pluginname argument=value
... !> ?>
- </verbatim>
+ {{{
+ <?plugin PluginName args=<!plugin-list pluginname [args
...]
!> ?>
+ }}}
+====
The box Method ====
Themes based on the "sidebar" theme may use the box method of any
-plugin, which displays a *title*
-and a condensed *content* in a box.
+plugin, which displays a *
*title*
*
+and a condensed *
*content*
* in a box.
+====
~WikiPluginCached ====
Plugins deriving from the class ~WikiPluginCached must also define
the methods getPluginType(),
optionally getExpire(), managesValidators(), and dependent of the
-getPluginType the methods to display the *possibly cached* result.
+getPluginType the methods to display the *
*possibly cached*
* result.
getImage(), getMap() or getHtml(),
optionally also
@@ -149,18 +143,18 @@
getAlt(), getImageType(), embedMap(), embedImg(), embedObject()
See the config.ini PLUGIN_CACHED_* settings and PhpWiki:WikiPluginCached
-The term *[ActionPage|
Help:ActionPage]* refers to a page containing a plugin
+The term *
*[[
Help:ActionPage|ActionPage]
]*
* refers to a page containing a plugin
invocation with the same or translated pluginname as the pagename.
-An *action* is together with the *pagename* argument the basic
-PhpWiki argument.
+An *
*action*
* is together with the *
*pagename*
* argument the basic
+~
PhpWiki argument.
It can both be GET or POST actions. Actions are untranslated, always
-english
, pagenames can be localized.
+English
, pagenames can be localized.
Basic (and old) actions are all lowercase, like edit, browse, remove, ...
-Newer actions in PhpWiki:CamelCase are invoked via plugins on their
+Newer actions in [[
PhpWiki:CamelCase]]
are invoked via plugins on their
specific action page.
We decoupled actions from plugins via action pages for the following
reasons:
@@ -170,9 +164,9 @@
Override or add plugin defaults.
# Split simple plugins into multiple actions, like RecentChanges/RecentEdits,
MostPopular/LeastPopular, AllPages/AllPagesCreatedByMe/AllPagesLastEditedByMe/
AllPagesOwnedByMe which differ only in one argument.
-# Simplify the syntax for actions on another actions using a PageList
+# Simplify the syntax for actions on another actions using a ~
PageList
as result of an actionpage as input parameter for another action or
format.
* Those actions which have buttons or links in the theme or are
@@ -185,20 +179,12 @@
So for a hypothetical new ~MyActionPage plugin ~MyActionPage will
invoke the plugin and ~Help:~MyActionPagePlugin should be the description page.
-See PluginManager for a detailed list. Most plugins should have their
-own description page as subpage of *Help/* with the name *Plugin*
+See [[
PluginManager]]
for a detailed list. Most plugins should have their
+own description page as subpage of *
*Help/*
* with the name *
*Plugin*
*
-<?plugin BackLinks noheader=1 ?>
-
-!!! Contributed Plugins
-
-See PhpWiki:CategoryContributedPlugin.
-
-<?plugin Backlinks page=CategoryContributedPlugin ?>
-
--
----
-PhpWikiDocumentation
+----
+[[
PhpWikiDocumentation]]
version 4
A plugin is some PHP code that:
- lives in phpwiki/lib/plugin/<pluginname>.php
- implements the WikiPlugin interface by extending that class.
There are many plugins already distributed with PhpWiki. Simply look
in the lib/plugin directory or see the PluginManager list or see all the
Help/*Plugin pages.
To write your own, look at the
Help:HelloWorldPlugin (HelloWorld.php
in that directory), which is a minimal example of a plugin.
A WikiPlugin allows one to easily add new types of dynamic
content (as well as other functionality) to wiki pages within PhpWiki.
In this very wiki all actions which are not entirely lowercased
are implemented using plugins, and some lowercased convenience
actions also.
(rename, revert, setacl, diff, ...)
Note that you can NOT extend the markup syntax with a plugin, as in other wiki engines.
(The old-style
MagicPhpWikiURLs have been replaced by plugins
entirely.)
Example
Currently, one invokes a plugin by putting something like:
<<AllPages limit=20 cols=3>>
into a regular wiki-page. That particular example produces a list
of the first 20 existing pages in 3 columns, via the
PageList
library.
All pages in this wiki (861 total):
Details
Plugins can take certain named arguments, most do. The values of
these arguments can be determined four different ways. In order of
precedence:
The plugin invocation can specify the value for an argument, like so:
<?plugin BackLinks page=OtherPage ?>
The argument can be specified via an HTTP query argument. This
doesn't happen (is not allowed) unless the argument is mentioned in
the plugin invocation:
<?plugin BackLinks page ?>
Default values specified in the plugin invocation:
<?plugin BackLinks page||=OtherPage ?>
The plugin must supply default values for each argument it uses.
Such default args may be overriden by URL arguments like so:
BackLinks?page=ThisPage&sortby=-mtime
(The BackLinks plugin uses the current page as the default value for
the page argument.)
Most plugins using the
PageList library inherit their
default arguments from the PageList.
Standard Arguments
Most plugins display a list of pages, via the
PageList
library. PageList provides automatic support for those arguments.
info, exclude, author, owner, creator, sortby, limit, paging, cols, azhead,
comma, commasep, ordered
For details see the
PageList library documentation.
exclude and pages accept a list of pages. Either as comma-separated list,
supporting glob-style wildcards, or via the <!plugin-list pluginname [args] !>
invocation syntax, where pluginname might be any plugin returning a
PageList.
See
PhpWiki:PluginList.
Since most plugins return a PageList, this PageList is also a common
input parameter for other plugins, actions or formats.
Basic Plugin Types
All these plugins derive from the WikiPlugin class extending the
run method,
which returns a object tree of HTML objects, and may react on any
provided arguments from the WikiPage (see the args below) or
optionally overridden by arguments from the url (GET or POST args),
if defined via '||='.
A basic plugin just needs the run() method, and optionally getName,
getDescription, getDefaultArguments. See the
Help:HelloWorldPlugin for a short introduction.
plugin reacts on its arguments and the request and displays
arbitrary HTML.
plugin-form is used to display a input type=text box for the
default argument s.
plugin-list is used as argument to provide a dynamic list of
pagenames.
<?plugin PluginName [args...] ?>
<?plugin-form PluginName [args...] ?>
<?plugin PluginName args=<!plugin-list pluginname [args...] !> ?>
The box Method
Themes based on the "sidebar" theme may use the box method of any
plugin, which displays a title
and a condensed content in a box.
WikiPluginCached
Plugins deriving from the class WikiPluginCached must also define
the methods getPluginType(),
optionally getExpire(), managesValidators(), and dependent of the
getPluginType the methods to display the possibly cached result.
getImage(), getMap() or getHtml(),
optionally also
getAlt(), getImageType(), embedMap(), embedImg(), embedObject()
See the config.ini PLUGIN_CACHED_* settings and
PhpWiki:WikiPluginCached
Action Pages
The term
ActionPage refers to a page containing a plugin
invocation with the same or translated pluginname as the pagename.
An action is together with the pagename argument the basic
PhpWiki argument.
It can both be GET or POST actions. Actions are untranslated, always
English, pagenames can be localized.
Basic (and old) actions are all lowercase, like edit, browse, remove, ...
Newer actions in
PhpWiki:CamelCase are invoked via plugins on their
specific action page.
We decoupled actions from plugins via action pages for the following
reasons:
- Support translated action buttons and customizable action descriptions.
- Customize standard actions by tuning the plugin invocation arguments.
Override or add plugin defaults.
- Split simple plugins into multiple actions, like RecentChanges/RecentEdits,
MostPopular/LeastPopular, AllPages/AllPagesCreatedByMe/AllPagesLastEditedByMe/
AllPagesOwnedByMe which differ only in one argument.
- Simplify the syntax for actions on another actions using a PageList
as result of an actionpage as input parameter for another action or
format.
- Those actions which have buttons or links in the theme or are
referenced in the standard pgsrc pageset require their
(possibly localized) actionpages, otherwise the actions will not work.
- If the localized actionpage is not found the english version is
used.
- If no actionpage is found, it is recommended to do action=upgrade,
which imports all missing and required action pages into the database.
So for a hypothetical new MyActionPage plugin MyActionPage will
invoke the plugin and Help:MyActionPagePlugin should be the description page.
Existing Plugins
See PluginManager for a detailed list. Most plugins should have their
own description page as subpage of Help/ with the name Plugin
appended.
PhpWikiDocumentation