BTMash

Most folk that talk to me about linking content within a Drupal site (and use a wysiwyg module) know that I am a big fan of the Linkit module with pathologic. It provides a nice way to reference content within your site, keeps a simple url, and pathologic will convert it to the nice url. However, I recently ran into a problem with the course catalog on our campus. Each discipline as a requirements section which is currently managed by hand and we reference courses which are brought over via the migrate module. But one 2 occasions, we have had mishaps where the migrate module rolled back all of our courses (in other words, deleted) and migrated in course material. And all of these courses now had new node IDs - this meant all of our links were now broken. Linkit helped in updating those course codes, but the sheer amount of them meant that this ended up being a 6+ hour task. So we needed a new approach.

For our courses, we knew a couple of things - even though the node IDs could change, the actual course codes do not. And we have terms set up with views where we are displaying the course information (and each course has the course code as an anchor link) so perhaps a better approach would be to instead link the course via the course code to the term view page. This would require learning a few new things: letting Linkit know about the plugin via CTools (thus we are really creating a CTools plugin) and creating the plugin itself.

First off, letting CTools know you have plugins is not particularly difficult. You have to implement hook_ctools_plugin_directory($owner, $plugin_type). Within this, ctools basically asking you:
Where can I find plugins that are being requested by the module $module for the $plugin_type. In this case, we are implementing a 'Linkit' plugin of type 'linkit_plugins'. So in the end my implementation looked something like this:

/**
 * Implements hook_ctools_plugin_directory().
 */
function my_linkit_courses_plugin_ctools_plugin_directory($module, $plugin) {
  if ($module == 'linkit' && !empty($plugin)) {
    return "plugins/" . $plugin;
  }
}

This will let ctools and linkit know to find linkit plugins in my plugins directory (where there will be another directory name 'linkit_plugins'.

Inside this linkit_plugins directory, we can now create directories for each of our plugins - since I only have 1, I can store it right at the linkit_plugins level. This file will have an array explaining what the new class is going to do along with where to find it. So in my case:

<?php
/**
 * @file
 * Linkit views plugin.
 */
 
$plugin = array(
  'ui_title' => t("Course Catalog Codes"),
  'ui_description' => t('Extend Linkit course code support.'),
  'entity_type' => 'node',
  'handler' => array(
      'class' => 'LinkitPluginCourseCode',
      'file' => 'linkit_plugin_course_code.class.php',
  ),
);

Now I am ready to implement a class called LinkitPluginCourseCode. In my case, courses are nodes of bundle 'course'. Since there is already a node plugin for Linkit, I will just create a class that extends the functionality offered by that plugin. Now I just need to override 1 function: autocomplete_callback. This is the function that determines what the user will choose as their link. In my case, I have copied the autocomplete_callback from the linkit module and modified the EntityFieldQuery so it will instead search through the field_course_code field when possible. Additionally, I want to display links to all the taxonomy term pages that the course is available under so the content editor has a choice in which discipline the course link redirects to (we have a limited number of disciplines so this format is acceptable). Below is the full code:

<?php
/**
 * @file
 * Define Linkit node plugin class for courses.
 */
class LinkitPluginCourseCode extends LinkitPluginNode {
 
  /**
   * The autocomplete callback function for the Linkit Entity plugin.
   */
  function autocomplete_callback() {
    $field_definition = field_info_field('field_course_code');
    if (empty($field_definition)) {
      return parent::autocomplete_callback();
    }
    $matches = array();
    // Get the EntityFieldQuery instance.
    $this->getQueryInstance();
 
    // Add the search condition to the query object.
    $this->query->fieldCondition('field_course_code', 'value', $this->serach_string, 'CONTAINS')
      ->addTag('linkit_entity_autocomplete')
      ->addTag('linkit_' . $this->plugin['entity_type'] . '_autocomplete');
 
    // Add access tag for the query.
    // There is also a runtime access check that uses entity_access().
    $this->query->addTag($this->plugin['entity_type'] . '_access');
 
    // Bundle check.
    if (isset($this->entity_key_bundle) && isset($this->conf['bundles']) ) {
      if ($bundles = array_filter($this->conf['bundles'])) {
        $this->query->propertyCondition($this->entity_key_bundle, $bundles, 'IN');
      }
    }
 
    // Execute the query.
    $result = $this->query->execute();
 
    if (!isset($result[$this->plugin['entity_type']])) {
      return array();
    }
 
    $ids = array_keys($result[$this->plugin['entity_type']]);
 
    // Load all the entities with all the ids we got.
    $entities = entity_load($this->plugin['entity_type'], $ids);
 
    foreach ($entities AS $entity) {
      // Check the access againt the definded entity access callback.
      if (!entity_access('view', $this->plugin['entity_type'], $entity)) {
        continue;
      }
 
      if ($entity->type == 'course') {
        $term_matches = $this->buildTermPath($entity);
        foreach ($term_matches as $match) {
          $matches[] = $match;
        }
      }
      else {
        $matches[] = array(
          'title' => $this->buildLabel($entity),
          'description' => $this->buildDescription($entity),
          'path' => $this->buildPath($entity),
          'group' => $this->buildGroup($entity),
          'addClass' => $this->buildRowClass($entity),
        );
      }
 
    }
    return $matches;
  }
 
  /**
   * Builds paths to the term page instead of the entity.
   */
  function buildTermPath($entity) {
    $course_code = field_get_items('node', $entity, 'field_course_code');
    $course_code = $course_code[0]['safe_value'];
    $terms = field_get_items('node', $entity, 'field_course_discipline');
    $matches = array();
    foreach ($terms as $term) {
      $discipline = taxonomy_term_load($term['tid']);
      $entity_uri = entity_uri('taxonomy_term', $discipline);
      if (module_exists('pathologic')) {
        $uri = '/' . $entity_uri['path'] . '#' . $course_code;
      }
      else {
        $uri = url($entity_uri['path'], array('alias' => TRUE, 'fragment' => $course_code));
      }
      $matches[] = array(
        'title' => $this->buildLabel($entity) . ' - ' . check_plain($discipline->name) . ' LINK',
        'description' => $this->buildDescription($entity) . ' - ' . check_plain($discipline->name) . ' LINK',
        'path' => $uri,
        'group' => $this->buildGroup($entity),
        'addClass' => $this->buildRowClass($entity),
      );
    }
    return $matches;
  }
}

With this, the content editors are now able to link to courses based on their course id AND they are able to go to a location where they know a missing node ID will not affect the final outcome. It is not a particularly large amount of code given that it is so flexible (with this kind of scenario, it is actually possible to create even more dynamic linkit options where we could make selections more configurable. Or imagine passing what you need off to views to get your resultset. Very exciting!). And it was also a really nice introduction to creating your own CTools plugins (I certainly won't feel as afraid to write my own plugin as I used to be!).