Pawtucket plugins

From CollectiveAccess Documentation
Jump to: navigation, search

Capabilities

Pawtucket plugins are PHP classes you can write to extend Pawtucket with specialized functionality. If you need to add custom user interfaces – including menu items and screens – to your Pawtucket installation plugins are usually the best option.

Each plugin has its own directory in app/plugins which contains all of the code, views, graphics and configuration required for operation. At a minimum every plugin has a plugin class. This class, a sub-class of BaseApplicationPlugin, defines methods that "hook" various events that may occur during a user request. Your plugin class need only implement methods for the hooks it is interested in. Every time a user request is processed by Pawtucket and hookable events triggered, each plugin implementing a method for a given hook will called.

Information will be passed to your methods by the application plugin interface. The scope and format of this information varies by hook and is described in detail in the Hooks section. In addition, all plugins have access to the current request object, and by extension request parameters and the application configuration file, via an inherited getRequest() method.

If you need to do any of the following then application plugins are probably a good solution:

  1. Add custom navigation
  2. Add completely custom screens with their own controllers, views and even database tables
  3. Modify the behavior of the Pawtucket user interface in specific ways


Layout

Every plugin has a directory located in app/plugins The name of this directory should be the name of the plugin (for example simpleGallery). Within this directory you must create a file with the name of your plugin and the suffix 'Plugin.php' This file should contain a PHP class with your plugin's name suffixed with 'Plugin'.

Your plugin can have, if required, its own controllers, views, graphics and configuration. By convention these are located in directories within the plugin directory with the following layout (following our 'simpleGallery' example):

  • app/plugins/simpleGallery
  • app/plugins/simpleGallery/simpleGalleryPlugin.php [plugin class]
  • app/plugins/simpleGallery/conf [directory containing plugin's configuration file(s); most plugins define at least one configuration file]
  • app/plugins/simpleGallery/controllers [directory containing plugin's controllers; needed if the plugin generates a user interface]
  • app/plugins/simpleGallery/views [directory containing views for the plugin's views; needed if the plugin generates a user interface]
  • app/plugins/simpleGallery/graphics [directory containing graphic elements; usually needed if the plugin generates a user interface]

The Plugin Class

Besides implementing a method for each hook your plugins needs to use, you must also define a checkStatus() method that returns information about the plugin and whether it is available for use or not. The return value for checkStatus() is an array with four keys:

  • description : a description of the plugin
  • errors : an array of text error messages relating to the initialization of the plugin. This should be an empty array if there are no errors. If the plugin is not available the reason why should be expressed in the errors array.
  • warnings : an array of text warning messages relating to the initialization of the plugin. Should be a list of warnings about anything that will limit the functionality of the plugin. Should be an empty array if there are no warnings.
  • available : set to true if plugin is loaded and available for use, false if it cannot load for some reason.

If initialization of your plugin fails, or for some reason the plugin should not be available in the current context (eg. some requirement for running is not met) then you must return false for the available value.

Your plugin must also set the $description property, inherited from the base plugin class. This should be set to a short description of the plugin, for display to the system administrator.

If your plugin needs to load its own configuration files or do other initialization, then you will need to include a constructor in your class. The constructor is passed an absolute file path to the plugin's directory, which is needed to load plugin-specific configuration files (or anything else in the plugin directory for that matter).

Hooks

The following hooks can be used by your plugin by defining a method in your plugin class using the hook name prefixed with "hook" For example, if your plugin needs change the menu bar define a method in your class like this:

public function hookRenderMenuBar($pa_menu_bar) {

	// ... more code here ...

}

Note that some hooks require you to return a value, while others do not. Use care when writing plugins that modify standard user interface elements such as menu bars. Errors in the values your plugin returns for hooks such as RenderMenuBar can make the system unusable.

If your plugin returns an array, the contents of that array will be merged with the array that was passed to you effectively incorporating your changes. There is one significant exception: if you return an empty the plugin manager will immediately return the null value to the caller and abort processing. Other plugins that may respond to the hook will not be called. This allows your plugin to "short circuit" a call to a hook, behavior that is useful in situations where the first plugin that can do the job must exclusively get the job. Note that returning any non-array value from your plugin is ignored by the plugin manager. In those cases the plugin manager will return the parameters passed into the hook unchanged.


Navigation

Hook name Description Parameters
RenderMenuBar Triggered when Pawtucket is generating the top-level menu bar just prior to its being drawn on-screen. This hook gives your plug-in the opportunity to add its own menus or modify existing menus. Param 1: the full top-level navigation array (structure as defined in the navigation.conf file) Your plug-in hook should modify this array as needed and return it


Common Problems

If Pawtucket is silently refusing to load your plugin then consider the following frequent mistakes:

  1. Is your plugin class named properly? It needs to be the name of your plugin directory + "Plugin". (eg. for a "simpleGallery" plugin, the plugin class filename should be "simpleGalleryPlugin.php" and the class defined within that file named "simpleGalleryPlugin"
  2. Is your plugin class directly within the plugin directory? It should not be in a sub-directory
  3. Is your plugin class returning true for the available setting in getStatus()?
Namespaces

Variants
Actions
Navigation
Tools
User
Personal tools