Custom plugins

This page was written for Entity Reference 7.x-1.0.

The Entity Reference module supports two different types of plugins for modifying entityreference fields: selection plugins and behavior plugins.

Selection plugins

A selection plugin is responsible for determining the list of referenceable entities for an entityreference widget. It is used for all kinds of widgets, such as checkboxes, drop downs, and autocomplete.

Every entityreference field requires one selection plugin, and the plugins shipped with the module are "Simple" and "Views". Selection plugins are configured at the field level, meaning all instances of a field use the same selection plugin with the same settings.

Behavior plugins

A behavior plugin can react to field-related events such as load, insert, update, and delete. This is useful because core hooks such as hook_field_update() can only be implemented by the modules that define fields.

Every behavior plugin has a behavior type, which is either field or instance. A field type behavior is toggled on/off and configured for all instances of a field. An instance type behavior can be toggled on/off and configured independently for each instance of a field.

Implementing a plugin

Note: A complete example can be found in the "examples" directory inside the entityreference module directory.

1. Implement hook_ctools_plugin_directory()

   Entity Reference uses CTools for managing plugins, and this hook tells CTools where to find them. The $plugin parameter will be either "selection" or "behavior".

   /**
    * Implements hook_ctools_plugin_directory().
    */
   function mymodule_ctools_plugin_directory($module, $plugin) {
     if ($module == 'entityreference') {
       return 'plugins/entityreference_' . $plugin;
     }
   }
   

2. Create the plugin definition file

   Save the file as mymodule/plugins/entityreference_behavior/example_behavior_plugin.inc. The name of this file ends up being the identifier for the plugin.

   $plugin = array(
     'title' => t('Example instance behavior'),
     'class' => 'MyModuleExampleBehaviorPlugin',
     'behavior type' => 'instance',
   );
   

3. Create the plugin class

   Save the file as mymodule/plugins/entityreference_behavior/MyModuleExampleBehaviorPlugin.class.php. Note that CTools prefers .class.php instead of .inc extensions.

   Although not required, it is a good idea to add a files[] directive to mymodule.info
   files[] = plugins/entityreference_behavior/MyModuleExampleBehaviorPlugin.class.php

   
   /**
    * The "example_behavior_plugin" Entity Reference plugin.
    */
   class MyModuleExampleBehaviorPlugin extends EntityReference_BehaviorHandler_Abstract {
     ...
   }
   
   

4. Clear your caches, then visit the settings page for any entityreference field. Your behavior should show up under an "Additional behaviors" fieldset.

Examples

The "plugins" directory contains all the selection and behavior plugins shipped with entityreference. There is also an "examples" directory bundled with the module that demonstrates how to implement a plugin.

The Entity Reference prepopulate module is a great example of a behavior plugin.