modules/relatedcontent/relatedcontent.module

<?php

/* $Id: relatedcontent.module,v 1.16.2.2 2008/01/09 21:41:48 tbarregren Exp $
 *
 * Copyright (C) 2007-2008 Thomas Barregren.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */
 
 
/**
 * @file
 * RelatedContent – a Drupal module that Allows privileged users to associate
 * a node with related nodes that can be displayed along with the node.
 *
 * Author: 
 *   Thomas Barregren at Webbredaktören <http://drupal.org/user/16678>.
 */


/******************************************************************************
 * RELATEDCONTENT API THAT CAN BE USED BY THEMES AND OTHER MODULES
 ******************************************************************************/

/**
 * Gets the id numbers (nid) of nodes that are related to $node.
 *
 * @param $node
 *   is the node object, as loaded through node_load(), for which the related
 *   content is requested.
 * @return
 *   an array of id numbers (nid) of nodes that are related to $node. The array
 *   is sorted as described in the documentation of the module.
 */
function relatedcontent_get_nodes(&$node) {
  $nodes = $node->nodes; // Keeps $node immutable.
  asort($nodes, SORT_NUMERIC);
  return array_keys($nodes);
}

/**
 * Sets the id numbers (nid) of nodes that are related to $node.
 *
 * @param $node
 *   is the node object, as loaded through node_load(), for which the related
 *   content is to be set.
 * @param $nodes
 *   is an array of id numbers (nid) of nodes that are related to $node. The
 *   array should be sorted as described in the documentation of the module.
 */
function relatedcontent_set_nodes(&$node, $nodes) {
  $ordinal = -count($nodes);
  foreach ($nodes as $nid) {
    $node_nodes[$nid] = $ordinal++;
  }
  $node->nodes = $node_nodes;
}

/**
 * Loads, transform and group the related content of a given node.
 *
 * This function takes either a node id or a node object ($node); load those
 * nodes that contains its related content; transform them by passing them
 * through a callback function ($content_function), which may take additional
 * arguments ($content_function_args); and finally group ($output_grouped).
 *
 * Example 1: After executing
 *
 *   $node = 3;
 *   $output = relatedcontent($node);
 *
 * $output['all'] is an array of all node objects, as loaded through 
 * node_load(), with related content or the node with the id (3) in $node.
 *
 * Example 2: After executing
 *
 *   $node = node_load(7);
 *   $output = relatedcontent($node, 'type', 'node_view', array(true));
 *
 * $output[$type][], where $type is the name of an content type, is an array of
 * teasers, as provided by node_view(), with related content for the node
 * with the node object in $node.
 *
 * Example 3: Following code print the full bodies of nodes with related
 * content of the node with id 205. The output is grouped by the authors. Each
 * group is preceded with a heading stating the author's name.
 *
 *   $output = relatedcontent(205, 'name', 'node_view', array(false)); 
 *   foreach ($output as $group => $contents) {
 *     $author = $group ? $group : t('Anonymous');
 *     echo "<h3>$author</h3>";
 *     echo implode('', $contents);
 *   }
 *
 * @param $node
 *   is either the id of a node (nid) or a node object as loaded by node_load().
 * @param $output_grouped
 *   is the name of the node field by which the content should be grouped, e.g.
 *   'type', 'name', 'uid' and 'status', or FALSE if the output should not be
 *   grouped.
 * @param $content_function
 *   is a callback function that transforms a node object, passed in as its
 *   first argument, to the desired representation, e.g. the teaser or body.
 *   If omitted or empty, the default transform is just returning the node
 *   object itself. If omitted or empty, grouping s not performed.
 * @param $content_function_args
 *   is an optional array with values that are passed in as argument 2, 3, and
 *   so forth, when calling the callback function $content_function.
 * @returns
 *   An array whose keys are the names by which the output should be grouped,
 *   i.e. names of content types or authors, or 'all', depending on
 *   $output_grouped, and whose values are arrays with the return values of
 *   calling $content_function for the nodes with related content.
 */
function relatedcontent($node, $output_grouped = false, $content_function = '', $content_function_args = array()) {

  // Load the node if only the node id was given.
  if (is_numeric($node)) {
    $node = node_load($node);
  }

  // Abort if RelatedContent is disabled for the node's content type.
  if (!relatedcontent_variable_enabled($node->type)) return;

  // Handle missing arguments.
  if (!$content_function) {
    $content_function = create_function('$n', 'return $n;');
  }
  if (!isset($content_function_args)) {
    $content_function_args = array();
  }

  // Get the job done.
  return _relatedcontent($node, $output_grouped, $content_function, $content_function_args);

}


/******************************************************************************
 * THEMEABLE FUNCTIONS
 ******************************************************************************/

/**
 * Themeable function for the related content.
 *
 * @ingroup themeable
 */
function theme_relatedcontent($output, $grouped = null, $teaser = null, $page = null) {

  global $theme_engine;
  
  // If the current theme engine is PHPTemplate and the current theme has a
  // RelatedContent template file, process the provided template file, and
  // return the resulting output. Otherwise, return the default theming.
  if ($theme_engine == 'phptemplate' && file_exists(path_to_theme() .'/relatedcontent.tpl.php')) {
    $variables = array('output' => $output, 'grouped' => $grouped, 'teaser' => $teaser, 'page' => $page);
    $out = _phptemplate_callback('relatedcontent', $variables);
  }
  else {
    foreach ($output as $group => $contents) {
      $out .= "<div class=\"relatedcontent-nodes $group\">";
      if ($grouped) {
        $out .= "<h3>$group</h3>";
      }
      $out .= implode('', $contents);
      $out .= '</div>';
    }
  }

  return $out;

}

/**
 * Themeable function for displaying the table with the nodes to select from.  
 *
 * @ingroup themeable
 */
function theme_relatedcontent_form($form) {

  // Prepare the table for rendering.
  $header = array(theme('table_select_header_cell'), t('Title'), t('Type'), t('Created'), t('Author'));
  if (isset($form['title']) && is_array($form['title'])) {
    foreach (element_children($form['title']) as $nid) {
      $row = array();
      $row[] = drupal_render($form['nodes'][$nid]);
      $row[] = drupal_render($form['title'][$nid]);
      $row[] = drupal_render($form['name'][$nid]);
      $row[] = drupal_render($form['created'][$nid]);
      $row[] = drupal_render($form['username'][$nid]);
      $rows[] = $row;
    }
  }
  else  {
    $rows[] = array(array('data' => t('No nodes available.'), 'colspan' => count($header)));
  }

  // Render the form.
  $output .= drupal_render($form['intro']);
  $output .= theme('table', $header, $rows);
  $output .= drupal_render($form);

  return $output;

}


/******************************************************************************
 * HOOKS
 ******************************************************************************/

/**
 * Implementation of hook_menu().
 */
function relatedcontent_menu($may_cache) {
  $items = array();
  if (!$may_cache) {
    _relatedcontent_menu_css($items);
    _relatedcontent_menu_relatedcontent($items);
  }
  return $items;
}
    
/**
 * Implementation of hook_form_alter().
 */
function relatedcontent_form_alter($form_id, &$form) {
  if ($form_id == 'node_type_form' && isset($form['identity']['type'])) {
    _relatedcontent_form_alter_node_type($form);
  }
}

/**
 * Implementation of hook_nodeapi().
 */
function relatedcontent_nodeapi(&$node, $op, $a3 = NULL, $a4 = NULL) {
  if (relatedcontent_variable_enabled($node->type)) {
    $function = "_relatedcontent_node_$op";
    if (function_exists($function)) {
      return $function($node, $a3, $a4);
    }
  }
}

/**
 * Implementation of hook_help().
 */
function relatedcontent_help($section='admin/help#relatedcontent') {
  switch ($section) {
    case 'admin/help#relatedcontent':
      return _relatedcontent_help_help();
  }
}


/******************************************************************************
 * IMPLEMENTATION OF THE MENU HOOK
 ******************************************************************************/

/**
 * Add the module's CSS-file.
 */
function _relatedcontent_menu_css(&$items) {
  $base = drupal_get_path('module', 'relatedcontent'); 
  drupal_add_css("$base/relatedcontent.css");
}

/**
 * If viewing a node of a type for which RelatedContent is enabled,
 * provide paths and tabs for adding and removing related content of the
 * node.
 */
function _relatedcontent_menu_relatedcontent(&$items) {

  // Abort if the requested page is not a node.
  if (arg(0) != 'node' || !is_numeric($nid = arg(1))) return;

  // Abort if the module is not enabled for the content type of the node.
  if (!relatedcontent_variable_enabled(_relatedcontent_db_content_type($nid))) return;

  // Load the node.
  $node = node_load($nid);
  
  // Determine whether the user has right to update the node.
  $node_access = node_access('update', $node);

  // Add the primary tab for RelatedContent.
  $items[] = array(
    'path' => "node/$nid/relatedcontent",
    'type' => MENU_LOCAL_TASK,
    'title' => t('RelatedContent'),
    'callback' => 'drupal_get_form',
    'callback arguments' => array('_relatedcontent_form_list', $node),
    'access' => $node_access,
    'weight' => 5,
  );

  // Add the secondary tab listing all nodes with related content.
  // Make it default.
  $items[] = array(
    'path' => "node/$nid/relatedcontent/list",
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'title' => t('Overview'),
    'callback' => 'drupal_get_form',
    'callback arguments' => array('_relatedcontent_form_list', $node),
    'access' => $node_access,
    'weight' => -11,
  );

  // Add the secondary tab listing all nodes provided by the view.
  $views = _relatedcontent_db_views();
  $view = relatedcontent_variable_view($node->type);
  $items[] = array(
    'path' => "node/$nid/relatedcontent/$view",
    'type' => MENU_LOCAL_TASK,
    'title' => $views[$view],
    'callback' => 'drupal_get_form',
    'callback arguments' => array('_relatedcontent_form_view', $node, $view),
    'access' => $node_access,
    'weight' => 0,
  );

}


/******************************************************************************
 * IMPLEMENTATION OF THE NODEAPI HOOK
 ******************************************************************************/

/**
 * A node is being viewed.
 */ 
function _relatedcontent_node_view(&$node, $teaser, $page) {

  // Get settings.
  $output_placing = relatedcontent_variable_output_placing($node->type);
  $output_teasers = $teaser || relatedcontent_variable_output_teasers($node->type);
  $output_grouped = relatedcontent_variable_output_grouped($node->type);

  // Abort if output isn't wanted in general, or when viewing a teaser.
  if (!$output_placing || $teaser && relatedcontent_variable_exclude_teasers($node->type)) return;

  // Get the related content. Abort if there is no content.
  if (!($output = _relatedcontent($node, $output_grouped, 'node_view', array($output_teasers)))) return;

  // Theme the related content.
  $output = theme('relatedcontent', $output, $output_grouped, $teaser, $page);

  // Add the themed output to the node's body.
  switch ($output_placing) {
    case 'beginning':
      $node->content['body']['#value'] = $output . $node->content['body']['#value'];
      break;
    case 'end':
      $node->content['body']['#value'] = $node->content['body']['#value'] . $output;
      break;
  }

}

/**
 * A node is being loaded.
 */
function _relatedcontent_node_load(&$node) {
  return array('nodes' => _relatedcontent_db_load($node->nid));
}

/**
 * A node is being deleted.    
 */
function _relatedcontent_node_delete(&$node) {
  _relatedcontent_db_delete($node->nid);
}


/******************************************************************************
 * IMPLEMENTATION OF THE HELP HOOK
 *****************************************************************************/

function _relatedcontent_help_help() {

  // Load the help text.
  $help = file_get_contents('relatedcontent.help', FILE_USE_INCLUDE_PATH);

  // Abort if we can't find the file.
  if (!$help) return;

  // Substitute variables and translate.
  $version = str_replace(array('$Re'.'vision:', ' $'), array('', ''), '$Revision: 1.16.2.2 $');
  $year = substr('$Date: 2008/01/09 21:41:48 $', 7, 4);
  $help = t($help, array('!version' => $version, '!year' => $year));

  // Add some style. (This is really dirty, but...)
  $style = <<<EOT
<style type="text/css" media="all">
/*<![CDATA[*/
code, kbd, pre { padding: 1px; font-family: "Bitstream Vera Sans Mono", Monaco, "Lucida Console", monospace; background-color: #EDF1F3; }
/*]]>*/
</style>
EOT;
  $help = $style . $help;

    return $help;

}


/******************************************************************************
 * ALTER NODE TYPE FORM
 ******************************************************************************/

/**
 * Add RelatedContent settings to the node type forms. 
 */
function _relatedcontent_form_alter_node_type(&$form) {

  // Get the node type
  $type = $form['#node_type']->type;

  // Insert RelatedContent's fieldset into the form.
  $form['relatedcontent'] = array(
    '#type' => 'fieldset',
    '#title' => t('RelatedContent settings'),
    '#description' => t(
      'Configure how RelatedContent should work on nodes of the type <em>'. $type .'</em>. For more information, see the !help.',
      array('!help' => l(t('help page'), 'admin/help/relatedcontent'))
    ),
    '#collapsible' => true, 
    '#collapsed' => !relatedcontent_variable_enabled($type),
    '#weight' => $form['submit']['#weight'],
  );
  
  // Ask if related content should be enabled on this content type.
  $form['relatedcontent']['relatedcontent_enabled'] = array(
    '#type' => 'checkbox',
    '#title' => t('Enable'),
    '#description' => t('Check to enable RelatedContent on nodes of the content type <em>'. $type .'</em>.'),
    '#default_value' => relatedcontent_variable_enabled($type),
  );

  // Ask which views, if any, to use as node list in the related content select form.
  $form['relatedcontent']['relatedcontent_view'] = array(
    '#type' => 'select',
    '#title' => t('Source of nodes'),
    '#description' => t(
      'Select the view that will provide the nodes to select from. If no view is selected, the table with nodes to select from is disabled. Any previously selected nodes will remain selected.',
      array('!view' => l('view' , 'admin/build/views'))
    ),
    '#options' => _relatedcontent_db_views(),
    '#default_value' => relatedcontent_variable_view($type),
  );

  // Ask how many nodes to list in the related content select form.
  $form['relatedcontent']['relatedcontent_length'] = array(
    '#type' => 'select',
    '#title' => t('Length of node table'),
    '#description' => t('The number of nodes to shown on each page of the table with nodes to select from.'),
    '#options' => array(10 => 10, 20 => 20, 50 => 50, 100 => 100, 0 => t('All nodes')),
    '#default_value' => relatedcontent_variable_length($type),
  );

  // Ask where the related nodes are going to be placed in the body.
  $form['relatedcontent']['relatedcontent_exclude_teasers'] = array(
    '#type' => 'radios',
    '#title' => t('Teasers'),
    '#description' => t('Choose if related content should be shown in teasers.'),
    '#options' => array(false => t('Include'), true => t('Exclude')),
    '#default_value' => relatedcontent_variable_exclude_teasers($type),
  );

  // Ask where the related nodes are going to be placed in the body.
  $form['relatedcontent']['relatedcontent_output_placing'] = array(
    '#type' => 'radios',
    '#title' => t('Placing'),
    '#description' => t('Choose where the related content should be outputted.'),
    '#options' => array(false => 'No output', 'beginning' => t('Beginning'), 'end' => t('End')),
    '#default_value' => relatedcontent_variable_output_placing($type),
  );

  // Ask the kind of grouping, if any.
  $form['relatedcontent']['relatedcontent_output_grouped'] = array(
    '#type' => 'radios',
    '#title' => t('Grouping'),
    '#description' => t('Choose how the related content should be grouped.'),
    '#options' => array(false => t('No grouping'), 'type' => t('Content type'), 'name' => t('Author')),
    '#default_value' => relatedcontent_variable_output_grouped($type),
  );

  // Ask if the the related nodes are going to be output as teasers or bodies.
  $form['relatedcontent']['relatedcontent_output_teasers'] = array(
    '#type' => 'radios',
    '#title' => t('Format'),
    '#description' => t('Choose whether the related content should be viewed as teasers or bodies of the selected nodes.'),
    '#options' => array(true => t('Teaser'), false => t('Body')),
    '#default_value' => relatedcontent_variable_output_teasers($type),
  );
  
  // Move down the submit and delete/reset buttons.
  $form['submit']['#weight'] += 1;
  if ($form['delete']) {
    $form['delete']['#weight'] = $form['submit']['#weight'];
  }
  else {
    $form['reset']['#weight'] = $form['submit']['#weight'];
  }

}


/******************************************************************************
 * RELATED CONTENT LIST FORM
 ******************************************************************************/

/**
 * Builds the related content list form.
 */
function _relatedcontent_form_list(&$node) {

  $form = array();
  
  // Build the form.
  _relatedcontent_form_list_introduction($form, $node->type);
  _relatedcontent_form_list_table($form, $node->nodes);
  _relatedcontent_form_list_buttons($form);
  _relatedcontent_form_list_directives($form);

  return $form;

}

/**
 * Helper function to _relatedcontent_form_list(). Adds a introductory text
 * to the form.
 */
function _relatedcontent_form_list_introduction(&$form, $type) {
  $form['intro'] = array(
    '#value' => t(
      "Select nodes to be removed from this <em>$type</em>. For more information, see the !help.",
      array('!help' => l(t('help page'), 'admin/help/relatedcontent'))
    ),
  );
}

/**
 * Helper function to _relatedcontent_form_list(). Adds button to the form.
 */
function  _relatedcontent_form_list_table(&$form, $selected_nodes) {
  foreach ($selected_nodes as $nid => $ordinal) {
    $node = node_load($nid);
    $form['nodes'][$node->nid] = array(
      '#type' => 'checkbox',
      '#return_value' => $ordinal,
      '#default_value' => true,
    );
    $form['title'][$node->nid] = array('#value' => l($node->title, 'node/'. $node->nid) .' '. theme('mark', node_mark($node->nid, $node->changed)));
    $form['name'][$node->nid] =  array('#value' => node_get_types('name', $node));
    $form['created'][$node->nid] = array('#value' => format_date($node->created, 'small'));
    $form['username'][$node->nid] = array('#value' => theme('username', $node));
  }
}

/**
 * Helper function to _relatedcontent_form_list(). Adds the table of nodes with
 * related content to the form.
 */
function  _relatedcontent_form_list_buttons(&$form) {
  $form['buttons']['update'] = array(
    '#type' => 'submit',
    '#value' => t('Update'),
    '#weight' => 5,
  );
}


/**
 * Helper function to _relatedcontent_form_list(). Adds form processing
 * directives.
 */
function  _relatedcontent_form_list_directives(&$form) {
  $form['#tree'] = true;
  $form['#theme'] = 'relatedcontent_form';
}

/**
 * Handles the submission of the related content list form.
 */
function _relatedcontent_form_list_submit($form_id, &$form_values) {

  // Get the nid of the current node.
  $nid = arg(1);

  // We are saving. Store the selected nodes in the node.
  $nodes = array_filter($form_values['nodes']);
  _relatedcontent_db_delete($nid);
  _relatedcontent_db_insert($nid, $nodes);  

  // Return to the regular view of the node.
  return "node/$nid/relatedcontent";

}


/******************************************************************************
 * RELATED CONTENT VIEW FORM
 ******************************************************************************/

/**
 * Builds the related content view form.
 */
function _relatedcontent_form_view(&$node, $view_id, $form_values = null) {

  $form = array();

  // Get the view that will provide the node list. Abort if the the view has
  // been removed and the content type hasn't been updated accordingly.
  if (!($view = _relatedcontent_form_get_view($view_id, $node->type))) return;
  
  // Determine some data needed in the build process.
  $page_length = relatedcontent_variable_length($node->type);
  $page_number = _relatedcontent_form_get_next_page_number($form, $form_values['page_number'], $form_values['op']);
  $db_result = views_build_view('result', $view, array(), false, $page_length, $page_number);
  $max_page_number = _relatedcontent_form_get_max_page_number($form, $form_values['max_page_number'], $page_length, $db_result['countquery'], $db_result['rewrite_args']);

  // If this is the initial call, initialize the selected node tracker with the
  // nodes of related content already stored within the node.
  if ($form_values == null) {
    _relatedcontent_track_initialize($node->nid, $node->nodes);
  }

  // Build the form.
  _relatedcontent_form_view_introduction($form, $node->type);
  _relatedcontent_form_view_table($form, $db_result['result'], $node->nid);
  _relatedcontent_form_view_buttons($form, $page_number, $max_page_number);
  _relatedcontent_form_view_hidden_values($form, $view_id, $page_length, $page_number, $max_page_number);
  _relatedcontent_form_view_directives($form);

  return $form;
  
}

/**
 * Load the view. Display an error message if it has been removed.
 */
function _relatedcontent_form_get_view($view, $type) {

  // Load the named view and return it.
  if ($view = views_get_view($view)) return $view;
  
  // No view was given, or the named view didn't exist. Log and display
  // an error message.
  $message = t(
    'RelatedContent uses <a href="!views-url">views</a> as its source of nodes. The specified view <em>@view-name</em> doesn\'t exist any more. Please, go to the <a href="!settings-url">settings of the content type "@content-type"</a> and select another view.',
    array(
      '!views-url' => url('admin/build/views'),
      '!settings-url' => url("admin/content/types/$type"),
      '@view-name' => $view_name,
      '@content-type' => $type,
    )
  );
  watchdog('relatedcontent', $message, WATCHDOG_ERROR);
  drupal_set_message($message, 'error');

}

/**
 * Advance the page. If $page_number is not set, we are on the first page.
 */
function _relatedcontent_form_get_next_page_number(&$form, $page_number, $op) {
  if (!isset($page_number)) return 0;
  switch ($op) {
    case t('Next'):
      return ++$page_number;
    case t('Previous'):
      return --$page_number;
  }
}

/**
 * Calculate the number of the very last page.
 */
function _relatedcontent_form_get_max_page_number(&$form, $max_page_number, $page_length, $count_query, $rewrite_args) {
  if (!isset($max_page_number)) {
    if ($page_length) {
      $count = db_rewrite_sql($count_query, 'node', 'nid', $rewrite_args);
      $count = db_result(db_query($count));
      $max_page_number = ceil($count / $page_length) - 1;
    }
    else {
      $max_page_number = 0;
    }
  }
  return $max_page_number;
}

/**
 * Adds a introductory text to the form.
 */
function _relatedcontent_form_view_introduction(&$form, $type) {
  $form['intro'] = array(
    '#value' => t(
      "Select nodes to be added to this <em>$type</em>. For more information, see the !help.",
      array('!help' => l(t('help page'), 'admin/help/relatedcontent'))
    ),
  );
}

/**
 * Adds the table of nodes with related content to the form.
 */
function _relatedcontent_form_view_table(&$form, $db_result, $nid) {
  $ordinal = 0;
  $selected_nodes = _relatedcontent_track_get_selected_nodes($nid);
  while ($node = db_fetch_object($db_result)) {
    $node = node_load($node->nid);
    $form['nodes'][$node->nid] = array(
      '#type' => 'checkbox',
      '#return_value' => ++$ordinal,
      '#attributes' => $selected_nodes[$node->nid] ? array('checked' => 'checked') : null, // See http://drupal.org/node/187413.
    );
    $form['title'][$node->nid] = array('#value' => l($node->title, 'node/'. $node->nid) .' '. theme('mark', node_mark($node->nid, $node->changed)));
    $form['name'][$node->nid] =  array('#value' => node_get_types('name', $node));
    $form['created'][$node->nid] = array('#value' => format_date($node->created, 'small'));
    $form['username'][$node->nid] = array('#value' => theme('username', $node));
  }
}

/**
 * Adds buttons to the form.
 */
function _relatedcontent_form_view_buttons(&$form, $page_number, $max_page_number) {

  // On all pages, except the first page, add a previous button.
  if ($page_number > 0) {
    $form['buttons']['previous'] = array(
      '#type' => 'submit',
      '#value' => t('Previous'),
      '#weight' => -5,
    );
  }

  // On all pages, except the last page, add a next button.
  if ($page_number < $max_page_number) {
    $form['buttons']['next'] = array(
      '#type' => 'submit',
      '#value' => t('Next'),
      '#weight' => 0,
    );
  }

  // On all pages, add an update button.
  $form['buttons']['update'] = array(
    '#type' => 'submit',
    '#value' => t('Update'),
    '#weight' => 5,
  );

}

/**
 * Adds hidden fields with information needed later.
 */
function _relatedcontent_form_view_hidden_values(&$form, $view_id, $page_length, $page_number, $max_page_number) {

  // Store the view's id.
  $form['view_id'] = array(
    '#type' => 'hidden',
    '#value' => $view_id,
  );
  
  // Store the number of nodes shown on a page.
  $form['page_length'] = array(
    '#type' => 'hidden',
    '#value' => $page_length,
  );
  
  // Store the number of the current page.
  $form['page_number'] = array(
    '#type' => 'hidden',
    '#value' => $page_number,
  );
  
  // Store the number of the very last page.
  $form['max_page_number'] = array(
    '#type' => 'hidden',
    '#value' => $max_page_number,
  );

}

/**
 * Adds form processing directives.
 */
function _relatedcontent_form_view_directives(&$form) {
  $form['#multistep'] = true;
  $form['#tree'] = true;
  $form['#theme'] = 'relatedcontent_form';
}

/**
 * Handles the submission of the related content form.
 */
function _relatedcontent_form_view_submit($form_id, &$form_values) {

  // Get the nid of the current node.
  $nid = arg(1);

  // Track changes done on the current form page.
  $offset = $form_values['page_number'] * $form_values['page_length'];
  _relatedcontent_track_update_selected_nodes($nid, $form_values['nodes'], $offset);
  
  // If we are not saving, return to the form again.
  if ($form_values['op'] != t('Update')) return false;

  // We are saving. Finalize the tracking; and store the tracked changes.
  $nodes = _relatedcontent_track_finalize($nid, $form_values['view_id'], $form_values['page_length'], $form_values['max_page_number']);
  _relatedcontent_db_delete($nid);
  _relatedcontent_db_insert($nid, $nodes);  

  // Return to the regular view of the node.
  return "node/$nid/relatedcontent";

}

/******************************************************************************
 * SELECTED NODES TRACKING
 ******************************************************************************/

/**
 * Initalize the selected nodes tracker.
 *
 * @see _relatedcontent_track_finalize() for details.
 */
function _relatedcontent_track_initialize($nid, $nodes) {

  // Tracks selected nodes as we move from on epage to another.
  $_SESSION['relatedcontent'][$nid]['nodes'] = $nodes;

  // Tracks the highets page number visited.
  $_SESSION['relatedcontent'][$nid]['highest_page_number'] = 0;

}

/**
 * Add $nodes to the selected nodes tracker.
 *
 * @see _relatedcontent_track_finalize() for details.
 */
function _relatedcontent_track_update_selected_nodes($nid, $nodes, $offset) {

  // Keep track of the highest page number visited.
  if ($_SESSION['relatedcontent'][$nid]['highest_page_number'] < $page_number) {
    $_SESSION['relatedcontent'][$nid]['highest_page_number'] = $page_number;
  }

  // The ordinal numbers of the passed must be added by an offset to keep
  // the sort order from one page to another.
  foreach ($nodes as $id => $ordinal) {
    if ($ordinal) {
      $nodes[$id] += $offset;
    }
  }

  // For keys in $_SESSION['relatedcontent'][$nid]['nodes'] for which there is no key
  // in $nodes, append corresponding value $_SESSION['relatedcontent'][$nid]['nodes']
  // to $node.
  $nodes += $_SESSION['relatedcontent'][$nid]['nodes'];
  
  // Remove all non-selcted nodes.
  $nodes = array_filter($nodes);

  // Store the nodes in the session.
  $_SESSION['relatedcontent'][$nid]['nodes'] = $nodes;

}

/**
 * Returns the traced selected nodes.
 *
 * @see _relatedcontent_track_finalize() for details.
 */
function _relatedcontent_track_get_selected_nodes($nid) {
  return $_SESSION['relatedcontent'][$nid]['nodes'];
}

/**
 * Finalizing the tracking, and returns the selected nodes.
 *
 * Nodes with related content get those loaded into an array where the keys are
 * the nodes' id and the values are ordinal numbers implying an order by which
 * they should be displayed. These initial ordinal numbers are negative.
 *
 * Upon first display of the table with nodes to select from, the tracker is
 * initialized with these tuples of node id and negative ordinal numbers.
 * Each time the user moves from one page of the table to another, or click on
 * the Update button, the tracker updates the ordinal number of those nodes
 * displayed on the page the user is leaving. The updated numbers are positive,
 * and chosen to reflect the sort order among the seen nodes.
 *
 * We have a contract with the user to not break the sort order of already
 * selected nodes if they are available in the view. We must therefore
 * "visit" all pages that has not yet been displayed, and update the ordinal
 * numbers of those remaining nodes which we find on these pages. In many
 * applications of RelatedContent it is likely to find the remaining nodes
 * among the first non-visited pages. This given, and the potential that
 * there might be many unvisited pages, which translates into many round-
 * trips to the database, we abort the search as soon as possible. However,
 * if there are orphan nodes (see the on-line help), we will visit all pages
 * in vain.
 */
function _relatedcontent_track_finalize($nid, $view_id, $page_length, $max_page_number) {

  // Get the tracked information.
  $nodes = $_SESSION['relatedcontent'][$nid]['nodes'];
  $page = $_SESSION['relatedcontent'][$nid]['highest_page_number'];

  // Get the node id of those nodes which haven't been seen. These are at the
  // end of the array of tracked nodes and are recognized by negative ordinal
  // numbers.
  for (end($nodes); current($nodes) < 0 ; prev($nodes)) {
    $remaining_nodes[key($nodes)] = true;
  }

  // Visit all pages that has not been displayed, and update the ordinal
  // numbers of those remaining nodes which we find on these pages.
  $view = views_get_view($view_id); // Get the view.
  $ordinal = ($page + 1) * $page_length; // The last used ordinal number.
  while (++$page <= $max_page_number) { // For each page not yet visited...
    $info = views_build_view('result', $view, array(), false, $page_length, $page); // Get the nodes on the current page.
    while ($node = db_fetch_object($info['result'])) { // For each node on the current page...
      ++$ordinal; // Next ordinal number.
      if ($remaining_nodes[$node->nid]) { // If current node is among the remaining ones...
        $nodes[$node->nid] = $ordinal; // Assign an ordinal number.
        unset($remaining_nodes[$node->nid]); // Remove it from the list of remaining nodes.
        if (count($remaining_nodes) == 0) break 2; // Abort as soon as possible.
      }
    }
  }
  
  // Clean up.
  unset($_SESSION['relatedcontent'][$nid]);

  return $nodes;
  
}

/******************************************************************************
 * IMPLEMENTATION OF THE RELATEDCONTENT API
 *****************************************************************************/

/**
 * For each node with related content and which the user is allowed to view,
 * append the related content to the end of the output buffer of the relevant 
 * group.
 */
function _relatedcontent(&$node, $output_grouped, $content_function, $args) {
  array_unshift($args, 0);
  foreach ($node->nodes as $nid => $ordinal) {
    if ($nid && ($n = node_load($nid)) && node_access ('view', $n)) {
      $args[0] = $n;
      $key = $output_grouped ? $n->$output_grouped : 'all';
      $output[$key][] = call_user_func_array($content_function, $args);
    }
  }
  return $output;
}


/******************************************************************************
 * PERSISTED VARIABLES
 *****************************************************************************/

/**
 * The persisted variable 'enabled' which is true/false whether the
 * related content is enabled or not, respectively, for the content type.
 *  Default value, if the variable does not exists, is FALSE.
 */
function relatedcontent_variable_enabled($type, $enabled = null) {
  return _relatedcontent_variable("relatedcontent_enabled_$type", $enabled, false);
}

/**
 * The persisted variable 'view' containing the name of the view to feed the
 * assembler for a node of the given type.  Default value, if the variable does
 * not exists, is ''.
 */
function relatedcontent_variable_view($type, $view = null) {
  return _relatedcontent_variable("relatedcontent_view_$type", $view, '');
}

/**
 * The persisted variable 'length' containing the number of nodes to show in
 * the assembler for a node of the given type.  Default value, if the variable
 * does not exists, is 50.
 */
function relatedcontent_variable_length($type, $page_length = null) {
  return _relatedcontent_variable("relatedcontent_length_$type", $page_length, 50);
}

/**
 * The persisted variable 'exclude_teasers' which is true/false whether the
 * related content should excluded in teasers or not respectively.  Default
 * value, if the variable does not exists, is TRUE.
 */
function relatedcontent_variable_exclude_teasers($type, $exclude_teasers = null) {
  return _relatedcontent_variable("relatedcontent_exclude_teasers_$type", $exclude_teasers, true);
}

/**
 * The persisted variable 'teasers' which is true/false whether the related
 * content should be viewed as teasers or full bodies respectively.  Default
 * value, if the variable does not exists, is TRUE.
 */
function relatedcontent_variable_output_teasers($type, $teasers = null) {
  return _relatedcontent_variable("relatedcontent_output_teasers_$type", $teasers, true);
}

/**
 * The persisted variable 'grouped' which is false or a string with the name
 * of the node attribute, e.g. 'type' and 'name', by which the related content
 * should be grouped by. Default value, if the variable does not exists, is
 * 'type'.
 */
function relatedcontent_variable_output_grouped($type, $grouped = null) {
  return _relatedcontent_variable("relatedcontent_output_grouped_$type", $grouped, 'type');
}

/**
 * The persisted variable 'after' which is false if related content should not
 * be outputted, 'beginning' or 'end' if the output should be at the beginning
 * or end respectively. Default value, if the variable does not exists, is
 * 'end'.
 */
function relatedcontent_variable_output_placing($type, $after = null) {
  return _relatedcontent_variable("relatedcontent_output_placing_$type", $after, 'end');
}

/**
 * Sets and gets the named persisted variable.
 */
function _relatedcontent_variable($name, $value = null, $default = null) {
  if (isset($value)) {
    variable_set($name, $value);
  }
  return variable_get($name, $default);
}


/******************************************************************************
 * DATABASE
 *****************************************************************************/

/**
 * Returns the content type of the node with the provided node id.
 */
function _relatedcontent_db_content_type($nid) {
  $db_result = db_query('SELECT type FROM {node} WHERE nid = %d', $nid);
  $db_result = db_fetch_object($db_result);
  return $db_result->type;
}

/**
 * Returns the available views provided by the Views module.
 */
function _relatedcontent_db_views() {
  $views = array('' => '');
  $db_result = db_query('SELECT vid, name FROM {view_view} ORDER BY name');
  while ($view = db_fetch_object($db_result)) {
    $views[$view->vid] = $view->name;
  }
  return $views;
}

/**
 * Insert nid of included nodes into database.
 */
function _relatedcontent_db_insert($nid, $nodes) {

  // Build the VALUES clause for inserting multiple rows.
  foreach ($nodes as $include_nid => $ordinal) {
    $values .= "($nid, $include_nid, $ordinal),";
  }
  $values = substr($values, 0, -1);
  
  // Insert the values, if any, into the RelatedContent table.
  if ($values) {
    db_query('INSERT INTO {relatedcontent} (nid, include_nid, ordinal_number) VALUES %s', $values);
  }

}

/**
 * Load nid of included nodes from database.
 *
 * Get the related content of $nid, and put it into a map. The keys are the id
 * of the nodes with the related content. The values are ordinal numbers. The
 * ordinal numbers are negative, going from -N, where N is the count of pairs
 * in the map, to -1. The reason is to flag that these numbers doesn't come
 * from the user selecting nodes, but from the database. The ordinal number
 * itself is irrelevant; it's only their relation to each other that matters. 
 */
function _relatedcontent_db_load($nid) {
  $nodes = array();
  $db_result = db_query('SELECT include_nid FROM {relatedcontent} WHERE nid = %d GROUP BY ordinal_number', $nid);
  $ordinal = -db_num_rows($db_result);
  while ($row = db_fetch_object($db_result)) {
    $nodes[$row->include_nid] = $ordinal++;
  }
  return $nodes;
}

/**
 * Delete nid of included nodes in database.
 */
function _relatedcontent_db_delete($nid) {
  db_query('DELETE FROM {relatedcontent} WHERE nid = %d', $nid);
}