Plugin Structure

Directory Layout

Each plugin is located in its own, unique directory under the /usr/local/centovacast/system/plugins/ directory on the Centova Cast web interface server.

Within the plugin directory, a single file named hooks.php must exist. This file defines the events for which the plugin should be invoked, as described below.

Any other files created in the plugin directory are ignored by Centova Cast.

The hooks.php File

The hooks.php file must contain a PHP class named PluginHooks_pluginname, where pluginname matches the name of the plugin's directory. For example, to create a plugin named foo, one might create a file called /usr/local/centovacast/system/plugins/foo/hooks.php containing a class named PluginHooks_foo.

The PluginHooks_pluginname class must inherit from the PluginHooks class which is defined elsewhere by Centova Cast. For example:

class PluginHooks_foo extends PluginHooks {

}

To register itself with Centova Cast, the class must implement a method named install_hooks(), described in the next section. Aside from the install_hooks() method, Centova Cast does not impose any further structural requirements on the class and the implementation details are left up to the developer.

The install_hooks Method

Within the plugin class, the install_hooks() method is used to register callbacks which will be called by Centova Cast whenever a specific action is performed within Centova Cast. This method should call the PluginHooks::register() method once for each callback to be registered.

A typical install_hooks() method looks like:

public function install_hooks() {
    PluginHooks::register('eventname','callback_function');
    /* optionally, additional PluginHooks::register() calls here */
}

In the above example, the plugin asks Centova Cast to invoke a function named callback_function() every time an event named eventname is triggered.

The complete list of available events is provided in the Event Reference section of the plugin API documentation.

Return Values

A callback should typically return PluginHooks::OK to indicate that the event was handled successfully.

Some events accept return values, however, which allow the plugin to abort the execution of the event. (For example, the pre-create-account event allows you to return an error to stop the account from being created.)

For events that accept return values, a callback may return PluginHooks::ERROR to indicate that Centova Cast should not proceed with the event. The plugin may also optionally return an error message by calling $this->set_error(). Any such error message will be displayed in the web interface (when applicable) and in the Centova Cast event log.

---