Plugins - Revision history

Infrastation: Use fixed-width style for pathnames and PHP code, lose some passive voice, use m-dashes and arrows.

2021-07-23T11:58:59Z

Use fixed-width style for pathnames and PHP code, lose some passive voice, use m-dashes and arrows.

Adoom42 at 16:46, 2 October 2017

2017-10-02T16:46:35Z

Adoom42 at 16:44, 2 October 2017

2017-10-02T16:44:21Z

Infrastation: Remove the warning.

2017-10-02T16:25:21Z

Remove the warning.

Infrastation: /* Writing a Plugin */ It was done in 0.21.0, not 0.20.11.

2017-10-02T16:24:53Z

Writing a Plugin: It was done in 0.21.0, not 0.20.11.

Infrastation: add a warning

2016-02-17T08:16:56Z

add a warning

Adoom42: Created page with "== Overview == Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktable..."

2015-12-29T00:32:24Z

Created page with "== Overview == Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktable..."

New page

== Overview ==
Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktables-contribs racktables-contribs] repository for user-submitted plugins.

Note that this guide details features that may or may not be included in a future release.

=== States ===
A plugin may be in one of three states.
* Not installed - it exists in the plugins directory, but hasn't been installed yet
* Enabled - it has been installed and is active
* Disabled - it has been installed and was subsequently disabled

=== Administration ===
To install a plugin, first copy it to the "plugins" directory. Then visit the Configuration -> Plugins page and click the Edit tab. The new plugin should be listed with a state of "Not installed". Click the Install icon.

To upgrade a plugin, first backup the appropriate "plugins" sub-directory. To be safe, it's also a good idea to backup your entire database. Afterwards, copy over the new version into the "plugins" directory. When you visit the Edit tab of the Configuration -> Plugins page, you should see a variance in the Code Version and DB Version columns. Click the Upgrade icon.

== Writing a Plugin ==
The old procedure involves placing a PHP file in the "plugins" directory of your RackTables installation. That method has limited functionality and may be deprecated at a later date.

A new plugin architecture was introduced in version 0.20.11. It includes the ability to install, uninstall, enable and disable plugins from the web interface. It is assumed that each plugin resides in its own directory within the main "plugins" directory, and that each plugin contains a "plugin.php" file which includes certain functions. The design was inspired by [http://docs.cacti.net/plugins Cacti's] plugin architecture.

=== Files ===
Each plugin is expected to contain certain files. While the only required file is "plugin.php", it is recommended that you include all mentioned files, especially if you intend to publish it for others.

* README - Provide a general description. If you expect the plugin to be accepted into the racktables-contribs repo, use the [https://help.github.com/articles/github-flavored-markdown/ Markdown] format.
* ChangeLog - Document changes made to each revision.
* LICENSE

=== Functions ===
{| class="wikitable"
!Name
!Returns
!Description
|-
|plugin_PLUGINNAME_info
|array
|Array contains 'name', 'longname', 'version' & 'home_url'
|-
|plugin_PLUGINNAME_init
|void
|Initialize the plugin. Register pages, tabs, triggers, handlers, etc.
|-
|plugin_PLUGINNAME_install
|boolean
|Make any necessary modifications (create tables, create Config settings, etc.)
|-
|plugin_PLUGINNAME_uninstall
|boolean
|Make any necessary modifications (drop tables, delete Config settings, etc.)
|-
|plugin_PLUGINNAME_upgrade
|boolean
|Make any necessary modifications (alter tables, modify Config settings, etc.)
|-
|plugin_PLUGINNAME_HOOKNAME
|varies
|Run when called by a system-level function (described below in the Hooks section)
|}

=== Hooks ===
There are used in cases where custom functions defined by a plugin should be called at specific times.

Examples:
* When resetting or deleting an object
* Resetting the Config settings (Configuration -> User interface)
* Viewing the Data Integrity report

Hooks are already supported in some functions, such as commitResetObject(). If you need it supported by another function, create a GitHub pull request and it will probably be accepted.

=== Upgrades ===
The plugin_PLUGINNAME_upgrade function is mandatory. If this is the first version, or if no upgrade steps are required, simply have the function return TRUE.

There are many cases where upgrades involve adding/modifying/deleting tables, Config settings or other pieces of information. These transitions should be handled by the upgrade function.

Example modeled after the core RackTables upgrader:

<pre>
function plugin_myplugin_upgrade ()
{
$db_info = getPlugin ('myplugin');
$v1 = $db_info['db_version'];
$code_info = plugin_plugin_info ();
$v2 = $code_info['version'];

if ($v1 == $v2)
throw new RackTablesError ('Versions are identical', RackTablesError::INTERNAL);

// find the upgrade path to be taken
$versionhistory = array
(
'1.0',
'2.0',
'3.0'
);
$skip = TRUE;
$path = NULL;
foreach ($versionhistory as $v)
{
if ($skip and $v == $v1)
{
$skip = FALSE;
$path = array();
continue;
}
if ($skip)
continue;
$path[] = $v;
if ($v == $v2)
break;
}
if ($path === NULL or ! count ($path))
throw new RackTablesError ('Unable to determine upgrade path', RackTablesError::INTERNAL);

// build the list of queries to execute
$queries = array ();
foreach ($path as $batchid)
{
switch ($batchid)
{
case '2.0':
// perform some upgrade step here
$queries[] = "UPDATE Plugin SET version = '2.0' WHERE name = 'myplugin'";
break;
case '3.0':
// perform some upgrade step here
$queries[] = "UPDATE Plugin SET version = '3.0' WHERE name = 'myplugin'";
break;
default:
throw new RackTablesError ("Preparing to upgrade to $batchid failed", RackTablesError::INTERNAL);
}
}

// execute the queries
global $dbxlink;
foreach ($queries as $q)
{
try
{
$result = $dbxlink->query ($q);
}
catch (PDOException $e)
{
$errorInfo = $dbxlink->errorInfo();
throw new RackTablesError ("Query: ${errorInfo[2]}", RackTablesError::INTERNAL);
}
}
}
</pre>

← Older revision		Revision as of 16:25, 2 October 2017
Line 1:		Line 1:
−	~~== Warning ==~~
−
−	~~----~~
−
−	~~----~~
−
−	~~----~~
−
−	~~----~~
−
−	~~----~~
−
−	~~'''This page is a part of work in progress, it documents a feature that is not yet in RackTables source code.'''~~
−
−	~~----~~
−
−	~~----~~
−
−	~~----~~
−
−	~~----~~
−
−	~~----~~
−
	== Overview ==		== Overview ==
	Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktables-contribs racktables-contribs] repository for user-submitted plugins.		Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktables-contribs racktables-contribs] repository for user-submitted plugins.

← Older revision		Revision as of 08:16, 17 February 2016
Line 1:		Line 1:
		+	== Warning ==
		+
		+	----
		+
		+	----
		+
		+	----
		+
		+	----
		+
		+	----
		+
		+	'''This page is a part of work in progress, it documents a feature that is not yet in RackTables source code.'''
		+
		+	----
		+
		+	----
		+
		+	----
		+
		+	----
		+
		+	----
		+
	== Overview ==		== Overview ==
	Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktables-contribs racktables-contribs] repository for user-submitted plugins.		Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktables-contribs racktables-contribs] repository for user-submitted plugins.

@@ Line 4: / Line 4: @@
 === States ===
 A plugin may be in one of three states.
-* Not installed - it exists in the plugins directory, but hasn't been installed yet
+* Not installed &mdash; it exists in the plugins directory, but hasn't been installed yet
-* Enabled - it has been installed and is active
+* Enabled &mdash; it has been installed and is active
-* Disabled - it has been installed and was subsequently disabled
+* Disabled &mdash; it has been installed and was subsequently disabled
 === Administration ===
-To install a plugin, first copy it to the "plugins" directory.  Then visit the Configuration -> Plugins page and click the Edit tab.  The new plugin should be listed with a state of "Not installed".  Click the Install icon.
+To install a plugin, first copy it to the <code>plugins</code> directory.  Then visit the Configuration &rarr; Plugins page and click the Edit tab.  The new plugin should be listed with a state of "Not installed".  Click the Install icon.
-To upgrade a plugin, first backup the appropriate "plugins" sub-directory.  To be safe, it's also a good idea to backup your entire database.  Afterwards, copy over the new version into the "plugins" directory.  When you visit the Edit tab of the Configuration -> Plugins page, you should see a variance in the Code Version and DB Version columns.  Click the Upgrade icon.
+To upgrade a plugin, first backup the appropriate <code>plugins</code> sub-directory.  To be safe, it's also a good idea to backup your entire database.  Afterwards, copy over the new version into the <code>plugins</code> directory.  When you visit the Edit tab of the Configuration &rarr; Plugins page, you should see a variance in the Code Version and DB Version columns.  Click the Upgrade icon.
 == Writing a Plugin ==
-The old procedure involves placing a PHP file in the "plugins" directory of your RackTables installation.  That method has limited functionality and may be deprecated at a later date.
+The old procedure involves placing a PHP file in the <code>plugins</code> directory of your RackTables installation.  That method has limited functionality and may be deprecated at a later date.
-A new plugin architecture was introduced in version 0.21.0.  It includes the ability to install, uninstall, enable and disable plugins from the web interface.  It is assumed that each plugin resides in its own directory within the main "plugins" directory, and that each plugin contains a "plugin.php" file which includes certain functions.  The design was inspired by [http://docs.cacti.net/plugins Cacti's] plugin architecture.
+RackTables release 0.21.0 had introduced a new plugin architecture, which includes the ability to install, uninstall, enable and disable plugins from the web interface.  It is assumed that each plugin resides in its own directory within the main <code>plugins</code> directory, and that each plugin contains a <code>plugin.php</code> file which includes certain functions.  The design was inspired by [http://docs.cacti.net/plugins Cacti's] plugin architecture.
 === Files ===
-Each plugin is expected to contain certain files.  While the only required file is "plugin.php", it is recommended that you include all mentioned files, especially if you intend to publish it for others.
+Each plugin is expected to contain certain files.  While the only required file is <code>plugin.php</code>, it is recommended that you include all mentioned files, especially if you intend to publish it for others.
-* README - Provide a general description.  If you expect the plugin to be accepted into the racktables-contribs repo, use the [https://help.github.com/articles/github-flavored-markdown/ Markdown] format.
+* <code>README</code> &mdash; Provide a general description.  If you expect the plugin to be accepted into the racktables-contribs repo, use the [https://help.github.com/articles/github-flavored-markdown/ Markdown] format.
-* ChangeLog - Document changes made to each revision.
+* <code>ChangeLog</code> &mdash; Document changes made to each revision.
-* LICENSE
+* <code>LICENSE</code>
 === Functions ===
@@ Line 31: / Line 31: @@
 !Description
 |-
-|plugin_PLUGINNAME_info
+|<code>plugin_PLUGINNAME_info()</code>
 |array
-|Array contains 'name', 'longname', 'version' & 'home_url'
+|Array keys are <code>name</code>, <code>longname</code>, <code>version</code> and <code>home_url</code>.
 |-
-|plugin_PLUGINNAME_init
+|<code>plugin_PLUGINNAME_init()</code>
 |void
 |Initialize the plugin.  Register pages, tabs, triggers, handlers, etc.
 |-
-|plugin_PLUGINNAME_install
+|<code>plugin_PLUGINNAME_install()</code>
 |boolean
 |Make any necessary modifications (create tables, create Config settings, etc.)
 |-
-|plugin_PLUGINNAME_uninstall
+|<code>plugin_PLUGINNAME_uninstall()</code>
 |boolean
 |Make any necessary modifications (drop tables, delete Config settings, etc.)
 |-
-|plugin_PLUGINNAME_upgrade
+|<code>plugin_PLUGINNAME_upgrade()</code>
 |boolean
 |Make any necessary modifications (alter tables, modify Config settings, etc.)
 |-
-|plugin_PLUGINNAME_HOOKNAME
+|<code>plugin_PLUGINNAME_HOOKNAME()</code>
 |varies
 |Run when called by a system-level function (described below in the Hooks section)
@@ Line 61: / Line 61: @@
 Examples:
 * When resetting or deleting an object
-* Resetting the Config settings (Configuration -> User interface)
+* Resetting the Config settings (Configuration &rarr; User interface)
 * Viewing the Data Integrity report
-Hooks are already supported in some functions, such as commitResetObject().  If you need it supported by another function, create a GitHub pull request and it will probably be accepted.
+Hooks are already supported in some functions, such as <code>commitResetObject()</code>.  If you need it supported by another function, create a GitHub pull request and it will probably be accepted.
 === Upgrades ===
-The plugin_PLUGINNAME_upgrade function is mandatory.  If this is the first version, or if no upgrade steps are required, simply have the function return TRUE.
+The <code>plugin_PLUGINNAME_upgrade()</code> function is mandatory.  If this is the first version, or if no upgrade steps are required, simply have the function return <code>TRUE</code>.
 There are many cases where upgrades involve adding/modifying/deleting tables, Config settings or other pieces of information.  These transitions should be handled by the upgrade function.

@@ Line 57: / Line 57: @@
 === Hooks ===
-There are used in cases where custom functions defined by a plugin should be called at specific times.
+These are used in cases where custom functions defined by a plugin should be called at specific times.
 Examples:

@@ Line 1: / Line 1: @@
 == Overview ==
 Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior.  See the [https://github.com/RackTables/racktables-contribs racktables-contribs] repository for user-submitted plugins.
 === States ===