interlink.module

<?php
// $Id$

/**
 * @file
 * Universal, semantically correct word/phrase linking a.k.a. glossary.
 */

/**
 * Term type.
 */
define('INTERLINK_TYPE_ABBREVIATION', 1);
define('INTERLINK_TYPE_SYNONYM',      2);

/**
 * Return a list of supported types for terms.
 */
function interlink_get_types() {
  return array(
    INTERLINK_TYPE_ABBREVIATION => 'abbreviations',
    INTERLINK_TYPE_SYNONYM => 'synonyms',
  );
}

/**
 * Implementation of hook_views_api().
 */
function interlink_views_api() {
  return array(
    'api' => 2,
    'path' => drupal_get_path('module', 'interlink') . '/views',
  );
}

/**
 * Implementation of hook_init().
 */
function interlink_init() {
  drupal_add_css(drupal_get_path('module', 'interlink') .'/interlink.css');
}

/**
 * Implementation of hook_form_alter().
 */
function interlink_form_alter(&$form, $form_state, $form_id) {
  if ($form_id == 'node_type_form' && isset($form['identity']['type'])) {
    // @todo Node type selection.
  }
  elseif (isset($form['type']) && isset($form['#node']) && $form['type']['#value'] .'_node_form' == $form_id) {
    $node = $form['#node'];
    if (!empty($node->nid)) {
      $terms = interlink_load_terms('node', $node->nid);
    }
    $form['interlink'] = array(
      '#type' => 'fieldset',
      '#title' => t('Interlink settings'),
      '#tree' => TRUE,
      '#collapsible' => TRUE,
      '#collapsed' => TRUE,
    );
    $form['interlink']['abbreviations'] = array(
      '#type' => 'textarea',
      '#title' => t('Abbreviations'),
      '#default_value' => isset($terms['abbreviations']) ? implode("\n", $terms['abbreviations']) : '',
    );
    $form['interlink']['synonyms'] = array(
      '#type' => 'textarea',
      '#title' => t('Synonyms'),
      '#default_value' => isset($terms['synonyms']) ? implode("\n", $terms['synonyms']) : '',
    );
    $form['#validate'][] = 'interlink_node_form_validate';

    if (module_exists('vertical_tabs')) {
      // Add javascript providing vertical tabs summaries.
      drupal_add_js(drupal_get_path('module', 'interlink') .'/interlink.node_form.js');
    }
  }
}

function interlink_node_form_validate($form, &$form_state) {
  //$synonyms = explode("\n", $form_state['values']['interlink']['synonyms']);
}

/**
 * Implementation of hook_nodeapi().
 */
function interlink_nodeapi(&$node, $op, $a3 = NULL, $a4 = NULL) {
  switch ($op) {
    case 'insert':
    case 'update':
      // Save terms.
      foreach (interlink_get_types() as $type) {
        $node->interlink[$type] = explode("\n", $node->interlink[$type]);
      }
      interlink_save_terms('node', $node->nid, $node->title, $node->interlink);
      break;

    case 'view':
      // Set build mode for nodes acting as interlink terms.
      if ($terms = interlink_load_terms('node', $node->nid)) {
        // TODO Required?
        #$node->build_mode = 'interlink';
        $node->interlink = $terms;
      }
      break;

    case 'alter':
      // Add structural markup around node body, except for teaser and views.
      if (isset($node->interlink) && !$a3 && !isset($node->view)) {
        $node->body = '<dl class="interlink-term"><dt><dfn id="interlink-node-' . $node->nid . '">' . check_plain($node->title) . '</dfn></dt><dd>' . $node->body . '</dd></dl>';
      }
  }
}

/**
 * Implementation of hook_content_build_modes().
 */
function interlink_content_build_modes() {
  return array(
    'interlink' => array(
      'title' => t('Interlink'),
      'build modes' => array(
        'interlink' => array(
          'title' => t('Glossary'),
          'views style' => TRUE,
        ),
      ),
    ),
  );
}

/**
 * Implementation of hook_filter().
 */
function interlink_filter($op, $delta = 0, $format = -1, $text = '') {
  switch ($op) {
    case 'list':
      return array(0 => t('Interlink filter'));

    case 'description':
      return t('Universal word/phrase linking a.k.a. glossary.');

    case 'process':
      return interlink_filter_process($text, $format);

    case 'no cache':
      // @todo Testing only.
      return TRUE;

    default:
      return $text;
  }
}

/**
 * Filter text.
 */
function interlink_filter_process($text, $format) {
  require_once './sites/all/libraries/simplehtmldom/simple_html_dom.php';

  // Load regular expression consisting of all linked terms.
  if ($cache = cache_get('interlink:rx')) {
    $regex = $cache->data;
  }
  else {
    // Rebuild regular expression.
    $terms = array();
    $result = db_query("SELECT term FROM {interlink_term} ORDER BY CHAR_LENGTH(term) DESC");
    while ($row = db_fetch_array($result)) {
      $terms[] = preg_replace('@ +@', '\s+', preg_quote($row['term'], '/'));
    }
    $regex = implode('|', $terms);
    cache_set('interlink:rx', $regex);
    unset($terms);
  }
  if (!$regex) {
    return $text;
  }

  $excluded_tags = array_flip(variable_get('interlink_excluded_tags', array('abbr', 'acronym', 'dfn')));

  // Generate a hash from the text to link terms only once. This is in
  // accordance with the Web Content Accessibility Guidelines (WCAG) 1.0,
  // checkpoint 4.2, which instructs us to "specify the expansion of each
  // abbreviation or acronym in a document where it first occurs" (note the
  // last bit).
  $hash = md5($text);

  // Create a DOM object from the text.
  $html = str_get_html($text);

  // Process all DOM text nodes.
  foreach ($html->find('text') as $element) {
    $in_anchor = 'FALSE';

    // Traverse up the tree to find conflicting tags.
    $parent = $element->parent;
    while ($parent->tag != 'root') {
      if (array_key_exists($parent->tag, $excluded_tags)) {
       // Skip this element.
        continue 2;
      }
      // An anchor tag among the parents requires special handling.
      if ($parent->tag == 'a') {
        $in_anchor = 'TRUE';
      }
      $parent = $parent->parent;
    }

    $element->innertext = preg_replace('/\b(' . $regex . ')/ue', "interlink_filter_replace('$hash', '\\1', $in_anchor)", $element->innertext);
  }

  return $html->save();
}

/**
 * Helper function to replace a matched phrase.
 */
function interlink_filter_replace($hash, $match, $in_anchor = FALSE) {
  static $terms = array(), $matches = array(), $first_only;

  if (!isset($first_only)) {
    $first_only = variable_get('interlink_first_only', TRUE);
  }
  // Abort if the term has already been linked in the text currently processed.
  if ($first_only && isset($matches[$hash][$match])) {
    return $match;
  }

  // Load term.
  if (!isset($terms[$match])) {
    $terms[$match] = interlink_load_term($match);
  }
  $term = $terms[$match];

  switch ($term->type) {
    case INTERLINK_TYPE_ABBREVIATION:
      // Expand abbreviation.
      $output = '<abbr title="' . check_plain($term->title) . '">' . $match . '</abbr>';
      if ($in_anchor || interlink_filter_nolink($term)) {
        // Just expand the abbreviation if it appears within an anchor tag
        // or within the source object.
        return $output;
      }
      // Otherwise link it to the term.
      $options['html'] = TRUE;
      break;
  
    case INTERLINK_TYPE_SYNONYM:
      if ($in_anchor || interlink_filter_nolink($term)) {
        // A synonym within an anchor tag cannot be linked. Likewise, it doesn't
        // make sense to link synonyms in the source object itself.
        return $match;
      }
      // Otherwise link it to the term.
      $output = $match;
      $options['attributes']['title'] = check_plain($term->title);
      break;
  }

  // Mark this match as 'seen'.
  $matches[$hash][$match] = TRUE;

  $url = $term->object_type . '/' . $term->object_id;
  $options += array(
    'fragment' => 'interlink-' . $term->object_type . '-' . $term->object_id,
    'attributes' => array(),
  );
  $options['attributes'] += array('class' => 'interlink interlink-' . $term->object_type);
  return l($output, $url, $options);
}

/**
 * Check conditions when a term must not be linked.
 */
function interlink_filter_nolink($term) {
  static $caller;

  if (!isset($caller)) {
    // Determine calling function to avoid linking objects to themselves.
    foreach (debug_backtrace() as $trace) {
      // Node view.
      if ($trace['function'] == 'node_view') {
        $caller = array(
          'type' => 'node',
          'id' => $trace['args'][0]->nid
        );
        break;
      }
    }
    if (!isset($caller)) {
      $caller = FALSE;
    }
  }

  return (!$caller || ($caller['type'] == $term->object_type && $caller['id'] == $term->object_id));
}

/**
 * Implementation of hook_preprocess_node().
 *
 * Switch template for views displaying interlinked nodes.
 */
function interlink_preprocess_node(&$vars) {
  $node = $vars['node'];
  // TODO Weak condition, make dependent on style plugin instead.
  if (isset($node->interlink) && isset($node->view)) {
    $vars['template_files'][] = 'interlink-node';
    $vars['template_files'][] = 'interlink-node-' . $node->type;
  }
}

/**
 * Implementation of hook_theme_registry_alter().
 */
function interlink_theme_registry_alter(&$registry) {
  // Add interlink's theme directory to the list of searched paths.
  $registry['node']['theme paths'][] = drupal_get_path('module', 'interlink') . '/theme';
}

/**
 * @defgroup interlink_crud Interlink CRUD functions
 * @{
 */

/**
 * Load one term.
 *
 * @param $term
 *   A term string.
 * @return
 *   A term definition record.
 */
function interlink_load_term($term) {
  return db_fetch_object(db_query("SELECT te.*, ti.title FROM {interlink_term} te LEFT JOIN {interlink_title} ti ON ti.object_type = te.object_type AND ti.object_id = te.object_id WHERE te.term = '%s'", $term));
}

/**
 * Load terms for an object.
 *
 * @param $object_type
 *   The object type to load terms for.
 * @param $object_id
 *   The object id to load terms for.
 * @return
 *   An array of terms, separated by type.
 */
function interlink_load_terms($object_type, $object_id) {
  $terms = array();
  $types = interlink_get_types();
  $result = db_query("SELECT term, type FROM {interlink_term} WHERE object_type = '%s' AND object_id = %d", $object_type, $object_id);
  while ($row = db_fetch_array($result)) {
    $terms[$types[$row['type']]][] = $row['term'];
  }
  return $terms;
}

/**
 * Save abbreviations and synonyms of an object.
 *
 * @param $object_type
 *   The object type to save terms for.
 * @param $object_id
 *   The object id to save terms for.
 * @param $object_title
 *   The unabbreviated title of the object.
 * @param $terms
 *   An array of terms.
 */
function interlink_save_terms($object_type, $object_id, $object_title, array $terms) {
  // Clean data.
  foreach (interlink_get_types() as $type) {
    if (is_array($terms[$type])) {
      foreach ($terms[$type] as $key => $value) {
        if (trim($value) == '') {
          unset($terms[$type][$key]);
          continue;
        }
        // Strip carriage return leftovers on Windows OS.
        $terms[$type][$key] = str_replace("\r", '', $value);
      }
    }
  }
  // No need to flush caches if nothing changed.
  if ($terms == interlink_load_terms($object_type, $object_id)) {
    return;
  }

  // Delete existing data.
  db_query("DELETE FROM {interlink_term} WHERE object_type = '%s' AND object_id = %d", $object_type, $object_id);
  db_query("DELETE FROM {interlink_title} WHERE object_type = '%s' AND object_id = %d", $object_type, $object_id);

  // Store terms.
  foreach (interlink_get_types() as $type_int => $type) {
    foreach ($terms[$type] as $term) {
      $record = array(
        'object_type' => $object_type,
        'object_id' => $object_id,
        'term' => $term,
        'type' => $type_int,
      );
      drupal_write_record('interlink_term', $record);
    }
  }

  // Store object title.
  $record = array(
    'object_type' => $object_type,
    'object_id' => $object_id,
    'title' => $object_title,
  );
  drupal_write_record('interlink_title', $record);

  // Flush related cashes.
  cache_clear_all('interlink:rx', 'cache');
  cache_clear_all('*', 'cache_filter', TRUE);
  cache_clear_all('*', 'cache_block', TRUE);
  cache_clear_all('*', 'cache_page', TRUE);
}

/**
 * @} End of "defgroup interlink_crud".
 */