From: <nuc...@us...> - 2008-09-30 19:41:23
|
Revision: 5614 http://mantisbt.svn.sourceforge.net/mantisbt/?rev=5614&view=rev Author: nuclear_eclipse Date: 2008-09-30 19:40:58 +0000 (Tue, 30 Sep 2008) Log Message: ----------- More plugin documentation. Modified Paths: -------------- trunk/mantisbt/docbook/developers/en/file-entities.ent trunk/mantisbt/docbook/developers/en/plugins-building.sgml trunk/mantisbt/docbook/developers/en/plugins.sgml Added Paths: ----------- trunk/mantisbt/docbook/developers/en/plugins-building-source.sgml Modified: trunk/mantisbt/docbook/developers/en/file-entities.ent =================================================================== --- trunk/mantisbt/docbook/developers/en/file-entities.ent 2008-09-30 18:25:18 UTC (rev 5613) +++ trunk/mantisbt/docbook/developers/en/file-entities.ent 2008-09-30 19:40:58 UTC (rev 5614) @@ -2,6 +2,7 @@ <!ENTITY events SYSTEM "events.sgml"> <!ENTITY plugins SYSTEM "plugins.sgml"> <!ENTITY plugins-building SYSTEM "plugins-building.sgml"> +<!ENTITY plugins-building-source SYSTEM "plugins-building-source.sgml"> <!ENTITY eventref SYSTEM "event-reference.sgml"> <!ENTITY eventref-output SYSTEM "event-reference-output.sgml"> <!ENTITY eventref-bug SYSTEM "event-reference-bug.sgml"> Added: trunk/mantisbt/docbook/developers/en/plugins-building-source.sgml =================================================================== --- trunk/mantisbt/docbook/developers/en/plugins-building-source.sgml (rev 0) +++ trunk/mantisbt/docbook/developers/en/plugins-building-source.sgml 2008-09-30 19:40:58 UTC (rev 5614) @@ -0,0 +1,17 @@ + <sect1 id="dev.plugins.building.source"> + <title>Example Plugin Source Listing</title> + + <para> + The code in this section, for the Example plugin, is available for use, + modification, and redistribution without any restrictions and without any + warranty or implied warranties. You may use this code however you want. + </para> + + <sect2 id="dev.plugins.building.source.Example.php"> + <title>Example/Example.php</title> + + <programlisting> + </programlisting> + </sect2> + </sect1> + Property changes on: trunk/mantisbt/docbook/developers/en/plugins-building-source.sgml ___________________________________________________________________ Added: svn:mime-type + text/sgml Added: svn:eol-style + native Modified: trunk/mantisbt/docbook/developers/en/plugins-building.sgml =================================================================== --- trunk/mantisbt/docbook/developers/en/plugins-building.sgml 2008-09-30 18:25:18 UTC (rev 5613) +++ trunk/mantisbt/docbook/developers/en/plugins-building.sgml 2008-09-30 19:40:58 UTC (rev 5614) @@ -9,6 +9,13 @@ knowledge of database schemas and how they are used with Mantis. </para> + <para> + This walkthrough will be working towards building a single end result: the + "Example" plugin as listed in the <link linkend="dev.plugins.building.source"> + next section</link>. You may refer to the final source code along the way, + although every part of it will be built up in steps throughout this section. + </para> + <sect2 id="dev.plugins.building.basics"> <title>The Basics</title> @@ -28,7 +35,71 @@ It may not contain any spacing or special characters beyond the ASCII upper- and lowercase alphabet, numerals, and underscore. This is used to identify the plugin everywhere except for what the end-user sees. + For our "Example" plugin, the basename we will use should be obvious + enough: "Example". </para> + + <para> + Every plugin must be contained in a single directory named to match the + plugin's basename, as well as contain at least a single PHP file, also + named to match the basename, as such: + </para> + + <programlisting> +Example/ + Example.php + </programlisting> + + <para> + This top-level PHP file must then contain a concrete class deriving from + the <classname>MantisPlugin</classname> class, which must be named in the + form of <classname>%Basename%Plugin</classname>, which for our purpose + becomes <classname>ExamplePlugin</classname>. + </para> + + <para> + Because of how <classname>MantisPlugin</classname> declares the + <code>register()</code> method as <code>abstract</code>, our plugin must + implement that method before PHP will find it semantically valid. This + method is meant for one simple purpose, and should never be used for any + other task: setting the plugin's information properties, including the + plugin's name, description, version, and more. + </para> + + <para> + Once your plugin defines its class, implements the <code>register()</code> + method, and sets at least the name and version properties, it is then + considered a "complete" plugin, and can be loaded and installed within + Mantis' plugin manager. At this stage, our Example plugin, with all the + possible plugin properties set at registration, looks like this: + </para> + + <programlisting><filename>Example/Example.php</filename> + +<?php +class ExamplePlugin extends MantisPlugin { + function register() { + $this->name = 'Example'; # Proper name of plugin + $this->description = ''; # Short description of the plugin + $this->page = ''; # Default plugin page + + $this->version = '1.0'; # Plugin version string + $this->requires = array( # Plugin dependencies, array of basename => version pairs + 'MantisCore' => '1.2', # Should always depend on an appropriate version of Mantis + ); + + $this->author = ''; # Author/team name + $this->contact = ''; # Author/team e-mail address + $this->url = ''; # Support webpage + } +} + </programlisting> + + <para> + This alone will allow the Example plugin to be installed with Mantis, and + is the foundation of any plugin. More of the plugin development process + will be continued in the next section. + </para> </sect3> </sect2> @@ -45,5 +116,6 @@ <para> </para> </sect2> + </sect1> Modified: trunk/mantisbt/docbook/developers/en/plugins.sgml =================================================================== --- trunk/mantisbt/docbook/developers/en/plugins.sgml 2008-09-30 18:25:18 UTC (rev 5613) +++ trunk/mantisbt/docbook/developers/en/plugins.sgml 2008-09-30 19:40:58 UTC (rev 5614) @@ -13,14 +13,16 @@ </para> <para> - Plugins are defined as implementations, or subclasses, of the MantisPlugin - class as defined in <filename>core/classes/MantisPlugin.php</filename>. Each - plugin may define information about itself, as well as a list of conflicts - and dependencies upon other plugins. There are many methods defined in the - MantisPlugin class that may be used as convenient places to define extra - behaviors, such as configuration options, event declarations, event hooks, - errors, and database schemas. Outside a plugin's core class, there is a - standard method of handling language strings, content pages, and files. + Plugins are defined as implementations, or subclasses, of the + <classname>MantisPlugin</classname> class as defined in + <filename>core/classes/MantisPlugin.php</filename>. Each plugin may define + information about itself, as well as a list of conflicts and dependencies + upon other plugins. There are many methods defined in the + <classname>MantisPlugin</classname> class that may be used as convenient + places to define extra behaviors, such as configuration options, event + declarations, event hooks, errors, and database schemas. Outside a plugin's + core class, there is a standard method of handling language strings, content + pages, and files. </para> <para> @@ -35,12 +37,13 @@ The plugin system includes a special set of API functions that provide convenience wrappers around the more useful Mantis API calls, including configuration, language strings, and link generation. This API allows - plugins to use core API's in 'sandboxed' fashions to aid interoperation + plugins to use core API's in "sandboxed" fashions to aid interoperation with other plugins, and simplification of common functionality. </para> </sect1> &plugins-building; + &plugins-building-source; <sect1 id="dev.plugins.api"> <title>API Usage</title> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |