Writing Registry Plugins

If you just need to publish static documents, see Publishing Mostly Static Public Content instead.

Registry functionality can be extended with the use of Plugins. Building a Registry Plugin requires knowledge of PHP, CakePHP, and COmanage.

Building a Registry Plugin

Background

Understand the Cake Framework. You should minimally have worked through the tutorials and examples.
Understand Cake Plugins. Registry Plugins are just Cake Plugins, with some extra conventions.
Understand the Registry Data Model.

Instantiated vs Non-Instantiated

There are two basic categories of Plugins supported by COmanage Registry.

Instantiated plugins must be configured before they can be used. For example, the LDAP Provisioner must be given connection information that is specific to each CO. Creating that configuration is instantiating the plugin.
Non-Instantiated plugins do not have CO-specific configuration. For example, normalizing whitespace is not CO specific.

This categorization is based on how Registry handles the plugin. An instantiated plugin follows a typical add/edit flow in order to use the plugin, with entry points described in the Additional Requirements By Plugin Type section, below.

It is possible for a non-instantiated plugin to maintain its own configuration, however Registry provides no direct support for configuring non-instantiated plugins.

It is possible that non-instantiated plugins will be converted to instantiated plugins in future releases as Registry capabilities evolve. Such a conversion may require changes to the plugin interfaces.

Plugin Directory

Set up a new Plugin in the directory local/Plugin/MyPlugin. You might find it handy to use Cake's bake command.

$ cd app
$ ./Console/cake bake plugin MyPlugin
Welcome to CakePHP v2.7.1 Console
---------------------------------------------------------------
App : app
Path: /home/user/src/comanage/git/registry/app/
---------------------------------------------------------------
1. /home/user/src/comanage/git/registry/local/Plugin/
2. /home/user/src/comanage/git/registry/app/Plugin/
3. /home/user/src/comanage/git/registry/plugins/
Choose a plugin path from the paths above.  
[1] > 1

Prior to v1.0.0, Plugins must be placed in app/Plugin/MyPlugin.

Plugin Model

Create a Model whose name matches the name of the Plugin. In this example, the Model is created at app/Plugin/MyPlugin/Model/MyPlugin.php.

Define $cmPluginType to indicate the type of the Plugin, from the following options:

$cmPluginType	Description	Available Since	Instantiated?
`enroller`	Enrollment Flow Plugin	v0.9.4	No
`identifiervalidator`	Identifier Validation Plugin	v1.1.0	Optional
`ldapschema`	LDAP Schema Plugin	v1.1.0	Yes, via LDAP schema configuration
`normalizer`	Normalization Plugin	v0.9.2	No
`orgidsource`	Organizational Identity Sources Plugin	v1.1.0	Yes
`provisioner`	Provisioning Plugin	v0.8	Yes
`other`	Any other type of Plugin	v0.8	No

As of v1.1.0, $cmPluginType may also be an array.

Here's an example Model:

class LdapProvisioner extends AppModel {
  // Required by COmanage Plugins
  public $cmPluginType = "provisioner";
}

Database Schema

Plugins have full access to the Registry database. You can create your own additional tables by creating a schema file and placing it in Plugin/MyPlugin/Config/Schema/schema.xml. The file is specified in ADOdb AXMLS format.

Tables should follow the Cake standard conventions, including id, created, and modified.

Once the file is created, the database schema will automatically be updated by the normal mechanism:

$ cd app
$ ./Console/cake database

Database Prefixing

For the most part, the database prefix as specified in the database configuration file will just work. The exception is that foreign keys must have the prefix explicitly hardcoded (CO-174). For now, using the prefix cm_ is recommended.

Foreign Key Dependencies

If you define tables for your plugin, you will almost certainly want foreign keys into the core database schema. For example, your tables may have co_person_id or co_id to refer to CO People or COs, respectively.

In order for deletes to cascade successfully when the parent object is deleted, you must specify any dependencies your plugin has. (Failure to do so will result in foreign key violation errors when the parent object is deleted.) To do so, define an array $cmPluginHasMany in Model/MyPlugin.php, which consists of an array where the keys are the model the foreign key points to and the values are the name of the model they point from.

For example:

// Document foreign keys
public $cmPluginHasMany = array(
  "CoPerson" => array("CoChangelogProvisionerExport")
);

CoPerson hasMany CoChangelogProvisionerExports. Put another way, co_changelog_provisioner_exports has a column co_person_id that is a foreign key to co_people.

Language Texts

Do not hardcode display texts, but instead create lookup files that translate keys into language specific texts. For now, Registry uses a custom mechanism for I18N/L10N (CO-351). Use _txt(key) or _txt(key, array(param1, param2)) in your code to generate language-specific text, and then define those keys in the file Plugin/MyPlugin/Lib/lang.php:

// When localizing, the number in format specifications (eg: %1$s) indicates the argument
// position as passed to _txt.  This can be used to process the arguments in
// a different order than they were passed.

$cm_my_plugin_texts['en_US'] = array(
  // Titles, per-controller
  'ct.co_my_plugin_model.1'  => 'My Plugin Model',
  'ct.co_my_plugin_model.pl' => 'My Plugin Models',

  // Plugin texts
  'pl.myplugin.someparam'    => 'Some Parameter',
  'pl.myplugin.another'      => 'Another Parameter'
);

Enumerations

Plugins may define enumerations in Plugin/MyPlugin/Lib/enum.php:

class MyPluginFruitEnum
{
  const Apple = 'A';
  const Orange = 'O';
}

Use of Standard Views

You may use Registry's "standard" views to easily render your pages in the Registry look. Simply create links from Plugin/MyPlugin/View/Model to ../../../../View/Standard. See core Registry views for examples. Note that you will need to define the language texts ct.co_X_model.1 and ct.co_X_model.pl to use the standard views, replacing X with the name of your model.

Menu Links

Plugins can add items to Registry's menus. To do so, define in Model/MyPlugin.php a function cmPluginMenus() that returns an array. The key in this array is the menu location to append to (see table below), and the value is another array, which defines one or more labels and the corresponding controllers and actions to generate links to. The Plugin infrastructure will automatically append CO IDs and CO Person IDs as appropriate.

Whether or not a Plugin menu is rendered is determined by the default permission as listed below.

Menu Location Key	Menu Location*	Default Permission	Available Since
cmp	Platform Menu	CMP Administrator	v0.8
cos	Collaborations Menu	Member of Any CO	v0.8
coconfig	CO Configuration Menu	CO Administrator	v0.8
copeople	CO People Menu	Member of CO	v0.8
cogroups*	CO Groups Menu	Member of CO	v1.0.0
coperson	My Identities Menu	Member of CO	v0.8
coservices	CO Services Menu	Member of CO	v1.1.0

An example:

/**
  * Expose menu items.
  *
  * @ since COmanage Registry v0.9.2
  * @ return Array with menu location type as key and array of labels, controllers, actions as values.
  */
public function cmPluginMenus() {
  return array(
    "coperson" => array(_txt('pl.dirviewer.viewmenu') =>
                      array('controller' => "dir_viewers",
                            'action'     => "view"))
  );
}

REST API

Exposing Plugin functionality via the REST API is not currently supported. (CO-521)

Additional Requirements By Plugin Type

Plugin Types not listed here have no additional requirements.

Space shortcuts

Page tree