Hướng dẫn custom entity reference: Drupal & Entity reference

There are some good examples out there on how to create a custom Entity reference Behaviour plugin, but not so much for Selection handlers.

Why would you want to do this? A number of reasons. For me in Harmony Forum it was because the base Entity reference selection handler wasn't returning correct results on an autocomplete field and I've got custom access rules to consider, and due to future expansion it makes sense. An alternative to making our own would be to use Views, but this idea doesn't appeal due to the performance overhead compared to EntityField Query.

Behaviour handler examples can be found in the Entity reference module itself, Entityreference Prepopulate and Organic Groups.

Before we jump in, if the base generic Entity reference selection handler does most of what you want, and you only have a custom entity to integrate, all you need to do is name your class in a particular way and it'll be automatically used.

Let's have a look in entityreference/plugins/selection/EntityReference_SelectionHandler_Generic.class.php

class EntityReference_SelectionHandler_Generic implements EntityReference_SelectionHandler {

  /**
   * Implements EntityReferenceHandler::getInstance().
   */
  public static function getInstance($field, $instance = NULL, $entity_type = NULL, $entity = NULL) {
    $target_entity_type = $field['settings']['target_type'];

    // Check if the entity type does exist and has a base table.
    $entity_info = entity_get_info($target_entity_type);
    if (empty($entity_info['base table'])) {
      return EntityReference_SelectionHandler_Broken::getInstance($field, $instance);
    }

if (class_exists($class_name = 'EntityReference_SelectionHandler_Generic_' . $target_entity_type)) {
      return new $class_name($field, $instance, $entity_type, $entity);
    }
    else {
      return new EntityReference_SelectionHandler_Generic($field, $instance, $entity_type, $entity);
    }
  }
...

Note the if (class_exists($class_name = 'EntityReference_SelectionHandler_Generic_' . $target_entity_type)) {chunk, this is your in if you don't want your own totally custom selection handler.

Right, still want to do this? Great!

We'll work with the assumption that this will be the structure of our module when we're done:

example.info
example.module
plugins/entityreference/selection/example_selection_handler.inc
plugins/entityreference/selection/ExampleSelectionHandler.class.php

We'll be creating "ExampleSelectionHandler" which extends "EntityReference_SelectionHandler_Generic".

First things first, add "plugins/entityreference/selection/ExampleSelectionHandler.class.php" to "files[]" in the module .info so it can be autoloaded (though I don't believe it's necessary).

files[] = plugins/entityreference/selection/ExampleSelectionHandler.class.php

Next in your module (for our purposes "Example") implement hook_ctools_plugin_directory to point to where your plugins are.

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

Now we need to create an unusually basic definition file for the Selection handler "example_selection_handler.inc". All this file needs is an array with two items:

<?php

$plugin = array(
  'title' => t(‘Example Selection handler'),
  'class' => 'ExampleSelectionHandler',
);

Finally we define the class file which should be named as per the value of $plugin[‘class'] with ".class.php" appended. The best example to look at is probably the "base" or default Selection handler within Entity reference which can be found at "entityreference/plugins/selection/EntityReference_SelectionHandler_Generic.class.php".

What should go in your implementation depends on what you want to do, the only requirement of your custom Selection handler is that it has the method "getInstance". Here's an example.