CWIS Developer Documentation

- Home
- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
Plugin Class Reference

Base class for all plugins. More...

Inheritance diagram for Plugin:
[legend]

## Public Member Functions
| Register ()
| Set the plugin attributes. More...
| SetUpConfigOptions ()
| Set up plugin configuration options. More...
| Initialize ()
| Initialize the plugin. More...
| HookEvents ()
| Hook methods to be called when specific events occur. More...
| DeclareEvents ()
| Declare events defined by this plugin. More...
| Install ()
| Perform any work needed when the plugin is first installed (for example, creating database tables). More...
| Upgrade ($PreviousVersion)
| Perform any work needed when the plugin is upgraded to a new version (for example, adding fields to database tables). More...
| Uninstall ()
| Perform any work needed when the plugin is uninstalled. More...
| GetAttributes ()
| Retrieve plugin information. More...
| GetBaseName ()
| Get plugin base name. More...
| ConfigSetting ($SettingName, $NewValue=NULL)
| Get/set plugin configuration setting. More...
| GetSavedConfigSetting ($SettingName)
| Get plugin configuration setting, ignoring any override value. More...
| GetConfigSettingType ($SettingName)
| Get type of a plugin configuration setting. More...
| GetConfigSettingParameters ($SettingName)
| Get plugin configuration setting parameters. More...
| ConfigSettingOverride ($SettingName, $Value)
| Set override for configuration setting, that will be returned regardless of the current saved configuration setting value. More...
| IsReady ($NewValue=NULL)
| Get/set whether the plugin is ready for use. More...
| IsEnabled ($NewValue=NULL, $Persistent=TRUE)
| Get/set whether the plugin is enabled. More...
| IsInstalled ($NewValue=NULL)
| Get/set whether the plugin is installed. More...
| InstalledVersion ($NewValue=NULL)
| Get/set the last version recorded as installed. More...
| GetName ()
| Get full name of plugin. More...
| GetDependencies ()
| Get list of plugins upon which this plugin depends (if any). More...
| __construct ()
| Class constructor – FOR PLUGIN MANAGER USE ONLY. More...

## Static Public Member Functions
static | SetApplicationFramework ($AF)
| Set the application framework to be referenced within plugins. More...

## Protected Member Functions
| CreateTables ($Tables, $DB=NULL)
| Create database tables. More...
| CreateMissingTables ($Tables)
| Create missing database tables. More...
| DropTables ($Tables)
| Drop database tables. More...

## Protected Attributes
| $Author = NULL
| Name of the plugin's author. More...
| $Description = NULL
| Text description of the plugin. More...
| $Email = NULL
| Contact email for the plugin's author. More...
| $EnabledByDefault = FALSE
| Whether the plugin should be enabled by default when installed. More...
| $InitializeBefore = array()
| Plugins that should be initialized after us. More...
| $InitializeAfter = array()
| Plugins that should be initialized before us. More...
| $Instructions = NULL
| Instructions for configuring the plugin (displayed on the automatically-generated configuration page if configuration values are supplied). More...
| $Name = NULL
| Proper (human-readable) name of plugin. More...
| $Version = NULL
| Version number of plugin in the format X.X.X (for example: 1.2.12). More...
| $Url = NULL
| Web address for more information about the plugin. More...
| $Requires = array()
| Array with plugin base (class) names for the index and minimum version numbers for the values. More...
| $CfgSetup = array()
| Associative array describing the configuration values for the plugin. More...
| $CfgPage = NULL
| Name of configuration page for plugin. More...

## Static Protected Attributes
static | $AF
| Application framework. More...

## Detailed Description

Base class for all plugins.

Definition at line 13 of file Plugin.php.

## Constructor & Destructor Documentation

Plugin::__construct | ( |  | ) |
| final

Class constructor – FOR PLUGIN MANAGER USE ONLY.

Plugins should always be retrieved via PluginManager::GetPlugin(), rather than instantiated directly. Plugin child classes should perform any needed setup in Initialize(), rather than using a constructor.

Definition at line 392 of file Plugin.php.

References StdLib\CheckMyCaller(), GetAttributes(), InstalledVersion(), and Register().

## Member Function Documentation

Plugin::ConfigSetting | ( |  | $SettingName,
|  |  | $NewValue = `NULL`
| ) |  |
| final

Get/set plugin configuration setting.

The value returned may have been overridden via ConfigSettingOverride().

Parameters

  string | $SettingName | Name of configuration value.
  mixed | $NewValue | New setting value.

Returns
  Requested value, or NULL if value was not set or there was no configuration value with the specified name.

See also
  Plugin::ConfigSettingOverride()

Definition at line 157 of file Plugin.php.

References GetBaseName().

Plugin::ConfigSettingOverride | ( |  | $SettingName,
|  |  | $Value
| ) |  |
| final

Set override for configuration setting, that will be returned regardless of the current saved configuration setting value.

This does not affect the saved setting value.

Parameters

  string | $SettingName | Name of configuration value.
  mixed | $Value | New override Value.

See also
  Plugin::ConfigSetting()

Definition at line 242 of file Plugin.php.

Plugin::CreateMissingTables | ( |  | $Tables | ) |
| protected

Create missing database tables.

(Intended for use in Plugin::Upgrade() methods.) This will not error out if the table creation SQL includes tables that already exist.

Parameters

  array | $Tables | Array of table creation SQL, with table names for the index. The class prefix may be omitted from the tables names used for the index (i.e. "MyTable" instead of "MyPlugin_MyTable").

Returns
  string Error message or NULL if creation succeeded.

Definition at line 560 of file Plugin.php.

References CreateTables().

Plugin::CreateTables | ( |  | $Tables,
|  |  | $DB = `NULL`
| ) |  |
| protected

Create database tables.

(Intended for use in Plugin::Install() methods.)

Parameters

  array | $Tables | Array of table creation SQL, with table names for the index. The class prefix may be omitted from the tables names used for the index (i.e. "MyTable" instead of "MyPlugin_MyTable").
  object | $DB | Database object to use. (OPTIONAL)

Returns
  string Error message or NULL if creation succeeded.

Definition at line 531 of file Plugin.php.

Referenced by CreateMissingTables().

Here is the caller graph for this function:

Plugin::DeclareEvents | ( |  | ) |

Declare events defined by this plugin.

This is used when a plugin defines new events that it signals or responds to. Names of these events should begin with the plugin base name, followed by "_EVENT_" and the event name in all caps (for example "MyPlugin_EVENT_MY_EVENT").

Returns
  Array with event names for the index and event types for the values.

Definition at line 75 of file Plugin.php.

Plugin::DropTables | ( |  | $Tables | ) |
| protected

Drop database tables.

(Intended for use in Plugin::Uninstall() methods.)

Parameters

  array | $Tables | Array of table creation SQL, with table names for the index. The class prefix may be omitted from the tables names used for the index (i.e. "MyTable" instead of "MyPlugin_MyTable").

Returns
  string Error message or NULL if table drops succeeded.

Definition at line 576 of file Plugin.php.

Plugin::GetAttributes | ( |  | ) |
| final

Retrieve plugin information.

Returns
  Array of attribute values indexed by attribute names.

Definition at line 118 of file Plugin.php.

Referenced by __construct().

Here is the caller graph for this function:

Plugin::GetBaseName | ( |  | ) |

Get plugin base name.

Returns
  string Base name.

Definition at line 143 of file Plugin.php.

Referenced by ConfigSetting(), InstalledVersion(), IsEnabled(), and IsInstalled().

Here is the caller graph for this function:

Plugin::GetConfigSettingParameters | ( |  | $SettingName | ) |
| final

Get plugin configuration setting parameters.

Parameters

  string | $SettingName | Name of configuration value.

Returns
  array Associative array with plugin config settings, as defined by plugin, or NULL if no setting available with the specified name.

Definition at line 228 of file Plugin.php.

Plugin::GetConfigSettingType | ( |  | $SettingName | ) |
| final

Get type of a plugin configuration setting.

Parameters

  string | $SettingName | Name of configuration value.

Returns
  string Type of setting, as specified by the plugin, or NULL if no setting available by that name.

Definition at line 215 of file Plugin.php.

Plugin::GetDependencies | ( |  | ) |

Get list of plugins upon which this plugin depends (if any).

Returns
  array Versions of required plugins with base names for the index.

Definition at line 381 of file Plugin.php.

References $Requires.

Plugin::GetName | ( |  | ) |

Get full name of plugin.

Returns
  string Name.

Definition at line 371 of file Plugin.php.

References $Name.

Plugin::GetSavedConfigSetting | ( |  | $SettingName | ) |
| final

Get plugin configuration setting, ignoring any override value.

Parameters

  string | $SettingName | Name of configuration value.

Returns
  Requested value, or NULL if value was not set or there was no configuration value with the specified name.

Definition at line 203 of file Plugin.php.

Plugin::HookEvents | ( |  | ) |

Hook methods to be called when specific events occur.

For events declared by other plugins the name string should start with the plugin base (class) name followed by "::" and then the event name.

Returns
  Array of method names to hook indexed by the event constants or names to hook them to.

Definition at line 63 of file Plugin.php.

Plugin::Initialize | ( |  | ) |

Initialize the plugin.

This is called (if the plugin is enabled) after all plugins have been loaded but before any methods for this plugin (other than Register()) have been called.

Returns
  NULL if initialization was successful, otherwise a string or array of strings containing error message(s) indicating why initialization failed.

Definition at line 51 of file Plugin.php.

Plugin::Install | ( |  | ) |

Perform any work needed when the plugin is first installed (for example, creating database tables).

Returns
  NULL if installation succeeded, otherwise a string containing an error message indicating why installation failed.

Definition at line 86 of file Plugin.php.

Plugin::InstalledVersion | ( |  | $NewValue = `NULL` | ) |

Get/set the last version recorded as installed.

This should only be set by the plugin manager.

Parameters

  string | $NewValue | New installed version. (OPTIONAL)

Returns
  string Current installed version.

Definition at line 345 of file Plugin.php.

References StdLib\CheckMyCaller(), and GetBaseName().

Referenced by __construct().

Here is the caller graph for this function:

Plugin::IsEnabled | ( |  | $NewValue = `NULL`,
|  |  | $Persistent = `TRUE`
| ) |  |

Get/set whether the plugin is enabled.

(This is the persistent setting for enabling/disabling, not whether the plugin is currently working.)

Parameters

  bool | $NewValue | TRUE to enable, or FALSE to disable. (OPTIONAL)
  bool | $Persistent | TRUE to make new setting persistent, or FALSE for new setting to apply only to this page load. (OPTIONAL, defaults to TRUE)

Returns
  bool TRUE if plugin is enabled, otherwise FALSE.

Definition at line 288 of file Plugin.php.

References GetBaseName().

Plugin::IsInstalled | ( |  | $NewValue = `NULL` | ) |

Get/set whether the plugin is installed.

This should only be set by the plugin manager.

Parameters

  bool | $NewValue | TRUE to mark as installed, or FALSE to mark as not installed. (OPTIONAL)

Returns
  bool TRUE if plugin is installed, otherwise FALSE.

Definition at line 317 of file Plugin.php.

References StdLib\CheckMyCaller(), and GetBaseName().

Plugin::IsReady | ( |  | $NewValue = `NULL` | ) |

Get/set whether the plugin is ready for use.

Parameters

  bool | $NewValue | TRUE if plugin is ready for use, otherwise FALSE. (OPTIONAL)

Returns
  bool TRUE if plugin is ready for use, otherwise FALSE.

Definition at line 261 of file Plugin.php.

References StdLib\CheckMyCaller().

Plugin::Register | ( |  | ) |
| abstract

Set the plugin attributes.

At minimum this method MUST set $this->Name and $this->Version. This is called when the plugin is loaded, and is normally the only method called for disabled plugins (except for SetUpConfigOptions(), which is called for pages within the plugin configuration interface).

Referenced by __construct().

Here is the caller graph for this function:

static Plugin::SetApplicationFramework | ( |  | $AF | ) |
| static final

Set the application framework to be referenced within plugins.

(This is set by the plugin manager.)

Parameters

  object | $AF | ApplicationFramework object.

Definition at line 447 of file Plugin.php.

References $AF.

Referenced by PluginManager\__construct().

Here is the caller graph for this function:

Plugin::SetUpConfigOptions | ( |  | ) |

Set up plugin configuration options.

This is called if the plugin is enabled and/or when loading the plugin configuration interface. Config options must be set up using this method (rather than going into Register()) whenever their setup references data from outside of the plugin in any fashion. NOTE: This method is called after the Install() or Upgrade() methods are called.

Returns
  NULL if configuration setup succeeded, otherwise a string or array of strings containing error message(s) indicating why config setup failed.

Definition at line 38 of file Plugin.php.

Plugin::Uninstall | ( |  | ) |

Perform any work needed when the plugin is uninstalled.

Returns
  NULL if uninstall succeeded, otherwise a string containing an error message indicating why uninstall failed.

Definition at line 109 of file Plugin.php.

Plugin::Upgrade | ( |  | $PreviousVersion | ) |

Perform any work needed when the plugin is upgraded to a new version (for example, adding fields to database tables).

Parameters

  string | $PreviousVersion | The version number of this plugin that was previously installed.

Returns
  NULL if upgrade succeeded, otherwise a string containing an error message indicating why upgrade failed.

Definition at line 99 of file Plugin.php.

## Member Data Documentation

Plugin::$AF
| static protected

Application framework.

Definition at line 479 of file Plugin.php.

Referenced by SetApplicationFramework().

Plugin::$Author = NULL
| protected

Name of the plugin's author.

Definition at line 456 of file Plugin.php.

Plugin::$CfgPage = NULL
| protected

Name of configuration page for plugin.

Definition at line 502 of file Plugin.php.

Plugin::$CfgSetup = array()
| protected

Associative array describing the configuration values for the plugin.

The first index is the name of the configuration setting, and the second indicates the type of information about that setting. For more information please see Implementing CWIS Plugins.

Definition at line 497 of file Plugin.php.

Plugin::$Description = NULL
| protected

Text description of the plugin.

Definition at line 458 of file Plugin.php.

Plugin::$Email = NULL
| protected

Contact email for the plugin's author.

Definition at line 460 of file Plugin.php.

Plugin::$EnabledByDefault = FALSE
| protected

Whether the plugin should be enabled by default when installed.

Definition at line 462 of file Plugin.php.

Plugin::$InitializeAfter = array()
| protected

Plugins that should be initialized before us.

Definition at line 466 of file Plugin.php.

Plugin::$InitializeBefore = array()
| protected

Plugins that should be initialized after us.

Definition at line 464 of file Plugin.php.

Plugin::$Instructions = NULL
| protected

Instructions for configuring the plugin (displayed on the automatically-generated configuration page if configuration values are supplied).

Definition at line 470 of file Plugin.php.

Plugin::$Name = NULL
| protected

Proper (human-readable) name of plugin.

Definition at line 472 of file Plugin.php.

Referenced by GetName().

Plugin::$Requires = array()
| protected

Array with plugin base (class) names for the index and minimum version numbers for the values.

Special indexes of "PHP" may be used to specify a minimum required PHP version or "PHPX_xxx" to specify a required PHP extension, where "xxx" is the extension name (e.g. "PHPX_GD"). The version number value is ignored for PHP extensions.

Definition at line 488 of file Plugin.php.

Referenced by GetDependencies().

Plugin::$Url = NULL
| protected

Web address for more information about the plugin.

Definition at line 476 of file Plugin.php.

Plugin::$Version = NULL
| protected

Version number of plugin in the format X.X.X (for example: 1.2.12).

Definition at line 474 of file Plugin.php.

The documentation for this class was generated from the following file:

- lib/ScoutLib/Plugin.php