Difference between revisions of "Plugins"

From RackTables Wiki
Jump to navigation Jump to search
m (→‎Writing a Plugin: It was done in 0.21.0, not 0.20.11.)
m (Use fixed-width style for pathnames and PHP code, lose some passive voice, use m-dashes and arrows.)
 
(3 intermediate revisions by 2 users not shown)
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.
 
Note that this guide details features that may or may not be included in a future release.
 
  
 
=== States ===
 
=== States ===
 
A plugin may be in one of three 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 — it exists in the plugins directory, but hasn't been installed yet
* Enabled - it has been installed and is active
+
* Enabled — it has been installed and is active
* Disabled - it has been installed and was subsequently disabled
+
* Disabled — it has been installed and was subsequently disabled
  
 
=== Administration ===
 
=== 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 ==
 
== 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 ===
 
=== 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 ===
 
=== Functions ===
Line 57: Line 31:
 
!Description
 
!Description
 
|-
 
|-
|plugin_PLUGINNAME_info
+
|<code>plugin_PLUGINNAME_info()</code>
 
|array
 
|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
 
|void
 
|Initialize the plugin.  Register pages, tabs, triggers, handlers, etc.
 
|Initialize the plugin.  Register pages, tabs, triggers, handlers, etc.
 
|-
 
|-
|plugin_PLUGINNAME_install
+
|<code>plugin_PLUGINNAME_install()</code>
 
|boolean
 
|boolean
 
|Make any necessary modifications (create tables, create Config settings, etc.)
 
|Make any necessary modifications (create tables, create Config settings, etc.)
 
|-
 
|-
|plugin_PLUGINNAME_uninstall
+
|<code>plugin_PLUGINNAME_uninstall()</code>
 
|boolean
 
|boolean
 
|Make any necessary modifications (drop tables, delete Config settings, etc.)
 
|Make any necessary modifications (drop tables, delete Config settings, etc.)
 
|-
 
|-
|plugin_PLUGINNAME_upgrade
+
|<code>plugin_PLUGINNAME_upgrade()</code>
 
|boolean
 
|boolean
 
|Make any necessary modifications (alter tables, modify Config settings, etc.)
 
|Make any necessary modifications (alter tables, modify Config settings, etc.)
 
|-
 
|-
|plugin_PLUGINNAME_HOOKNAME
+
|<code>plugin_PLUGINNAME_HOOKNAME()</code>
 
|varies
 
|varies
 
|Run when called by a system-level function (described below in the Hooks section)
 
|Run when called by a system-level function (described below in the Hooks section)
Line 83: Line 57:
  
 
=== Hooks ===
 
=== 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:
 
Examples:
 
* When resetting or deleting an object
 
* 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
 
* 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 ===
 
=== 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.
 
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.

Latest revision as of 12:58, 23 July 2021

Overview

Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the racktables-contribs repository for user-submitted plugins.

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.

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 plugins directory, and that each plugin contains a plugin.php file which includes certain functions. The design was inspired by 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 Markdown format.
  • ChangeLog — Document changes made to each revision.
  • LICENSE

Functions

Name Returns Description
plugin_PLUGINNAME_info() array Array keys are name, longname, version and 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

These 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:

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);
		}
	}
}