book.module

<?php

/**
 * @file
 * Allows users to collaboratively author a book.
 */

/**
 * Implementation of hook_node_info().
 */
function book_node_info() {
  return array(
    'book' => array(
      'name' => t('Book page'),
      'module' => 'book',
      'description' => t("A book is a collaborative writing effort: users can collaborate writing the pages of the book, positioning the pages in the right order, and reviewing or modifying pages previously written. So when you have some information to share or when you read a page of the book and you didn't like it, or if you think a certain page could have been written better, you can do something about it."),
    ),
  );
}

/**
 * Implementation of hook_perm().
 */
function book_perm() {
  return array(
    'outline posts in books',
    'create book pages',
    'create new books',
    'edit book pages',
    'edit own book pages',
    'see printer-friendly version',
  );
}

/**
 * Implementation of hook_access().
 */
function book_access($op, $node) {
  global $user;
  if ($op == 'create') {

    // Only registered users can create book pages. Given the nature
    // of the book module this is considered to be a good/safe idea.
    return user_access('create book pages');
  }
  if ($op == 'update') {

    // Only registered users can update book pages. Given the nature
    // of the book module this is considered to be a good/safe idea.
    // One can only update a book page if there are no suggested updates
    // of that page waiting for approval. That is, only updates that
    // don't overwrite the current or pending information are allowed.
    if (user_access('edit book pages') || $node->uid == $user->uid && user_access('edit own book pages')) {
      return TRUE;
    }
    else {

      // do nothing. node-access() will determine further access
    }
  }
}

/**
 * Implementation of hook_link().
 */
function book_link($type, $node = NULL, $teaser = FALSE) {
  $links = array();
  if ($type == 'node' && isset($node->parent)) {
    if (!$teaser) {
      if (book_access('create', $node) && $node->status == 1) {
        $links['book_add_child'] = array(
          'title' => t('Add child page'),
          'href' => "node/add/book/parent/{$node->nid}",
        );
      }
      if (user_access('see printer-friendly version')) {
        $links['book_printer'] = array(
          'title' => t('Printer-friendly version'),
          'href' => 'book/export/html/' . $node->nid,
          'attributes' => array(
            'title' => t('Show a printer-friendly version of this book page and its sub-pages.'),
          ),
        );
      }
    }
  }
  return $links;
}

/**
 * Implementation of hook_menu().
 */
function book_menu($may_cache) {
  $items = array();
  if ($may_cache) {
    $items[] = array(
      'path' => 'admin/content/book',
      'title' => t('Books'),
      'description' => t("Manage site's books and orphaned book pages."),
      'callback' => 'book_admin',
      'access' => user_access('administer nodes'),
    );
    $items[] = array(
      'path' => 'admin/content/book/list',
      'title' => t('List'),
      'type' => MENU_DEFAULT_LOCAL_TASK,
    );
    $items[] = array(
      'path' => 'admin/content/book/orphan',
      'title' => t('Orphan pages'),
      'callback' => 'drupal_get_form',
      'callback arguments' => array(
        'book_admin_orphan',
      ),
      'type' => MENU_LOCAL_TASK,
      'weight' => 8,
    );
    $items[] = array(
      'path' => 'book',
      'title' => t('Books'),
      'callback' => 'book_render',
      'access' => user_access('access content'),
      'type' => MENU_SUGGESTED_ITEM,
    );
    $items[] = array(
      'path' => 'book/export',
      'callback' => 'book_export',
      'access' => user_access('access content'),
      'type' => MENU_CALLBACK,
    );
  }
  else {

    // Add the CSS for this module
    // We put this in !$may_cache so it's only added once per request
    drupal_add_css(drupal_get_path('module', 'book') . '/book.css');

    // To avoid SQL overhead, check whether we are on a node page and whether the
    // user is allowed to outline posts in books.
    if (arg(0) == 'node' && is_numeric(arg(1)) && user_access('outline posts in books')) {

      // Only add the outline-tab for non-book pages:
      $result = db_query(db_rewrite_sql("SELECT n.nid FROM {node} n WHERE n.nid = %d AND n.type != 'book'"), arg(1));
      if (db_num_rows($result) > 0) {
        $items[] = array(
          'path' => 'node/' . arg(1) . '/outline',
          'title' => t('Outline'),
          'callback' => 'drupal_get_form',
          'callback arguments' => array(
            'book_outline',
            arg(1),
          ),
          'access' => user_access('outline posts in books'),
          'type' => MENU_LOCAL_TASK,
          'weight' => 2,
        );
      }
    }
  }
  return $items;
}

/**
 * Implementation of hook_block().
 *
 * Displays the book table of contents in a block when the current page is a
 * single-node view of a book node.
 */
function book_block($op = 'list', $delta = 0) {
  $block = array();
  if ($op == 'list') {
    $block[0]['info'] = t('Book navigation');
    return $block;
  }
  else {
    if ($op == 'view') {

      // Only display this block when the user is browsing a book:
      if (arg(0) == 'node' && is_numeric(arg(1))) {
        $result = db_query(db_rewrite_sql('SELECT n.nid, n.title, b.parent FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE n.nid = %d'), arg(1));
        if (db_num_rows($result) > 0) {
          $node = db_fetch_object($result);
          $path = book_location($node);
          $path[] = $node;
          $expand = array();
          foreach ($path as $key => $node) {
            $expand[] = $node->nid;
          }
          $block['subject'] = check_plain($path[0]->title);
          $block['content'] = book_tree($expand[0], 5, $expand);
        }
      }
      return $block;
    }
  }
}

/**
 * Implementation of hook_insert().
 */
function book_insert($node) {
  db_query("INSERT INTO {book} (nid, vid, parent, weight) VALUES (%d, %d, %d, %d)", $node->nid, $node->vid, $node->parent, $node->weight);
}

/**
 * Implementation of hook_submit().
 */
function book_submit(&$node) {
  global $user;

  // Set default values for non-administrators.
  if (!user_access('administer nodes')) {
    $node->revision = 1;
    $node->uid = $user->uid;
  }
}

/**
 * Implementation of hook_form().
 */
function book_form(&$node) {
  $type = node_get_types('type', $node);
  if ($node->nid && !$node->parent && !user_access('create new books')) {
    $form['parent'] = array(
      '#type' => 'value',
      '#value' => $node->parent,
    );
  }
  else {
    $form['parent'] = array(
      '#type' => 'select',
      '#title' => t('Parent'),
      '#default_value' => $node->parent ? $node->parent : arg(4),
      '#options' => book_toc($node->nid),
      '#weight' => -4,
      '#description' => user_access('create new books') ? t('The parent section in which to place this page. Note that each page whose parent is &lt;top-level&gt; is an independent, top-level book.') : t('The parent that this page belongs in.'),
    );
  }
  $form['title'] = array(
    '#type' => 'textfield',
    '#title' => check_plain($type->title_label),
    '#required' => TRUE,
    '#default_value' => $node->title,
    '#weight' => -5,
  );
  $form['body_filter']['body'] = array(
    '#type' => 'textarea',
    '#title' => check_plain($type->body_label),
    '#default_value' => $node->body,
    '#rows' => 20,
    '#required' => TRUE,
  );
  $form['body_filter']['format'] = filter_form($node->format);
  if (user_access('administer nodes')) {
    $form['weight'] = array(
      '#type' => 'weight',
      '#title' => t('Weight'),
      '#default_value' => $node->weight,
      '#delta' => 15,
      '#weight' => 5,
      '#description' => t('Pages at a given level are ordered first by weight and then by title.'),
    );
  }
  else {

    // If a regular user updates a book page, we preserve the node weight; otherwise
    // we use 0 as the default for new pages
    $form['weight'] = array(
      '#type' => 'value',
      '#value' => isset($node->weight) ? $node->weight : 0,
    );
  }
  return $form;
}

/**
 * Implementation of function book_outline()
 * Handles all book outline operations.
 */
function book_outline($nid) {
  $node = node_load($nid);
  $form['parent'] = array(
    '#type' => 'select',
    '#title' => t('Parent'),
    '#default_value' => $node->parent,
    '#options' => book_toc($node->nid),
    '#description' => t('The parent page in the book.'),
  );
  $form['weight'] = array(
    '#type' => 'weight',
    '#title' => t('Weight'),
    '#default_value' => $node->weight,
    '#delta' => 15,
    '#description' => t('Pages at a given level are ordered first by weight and then by title.'),
  );
  $form['log'] = array(
    '#type' => 'textarea',
    '#title' => t('Log message'),
    '#description' => t('An explanation to help other authors understand your motivations to put this post into the book.'),
  );
  $form['nid'] = array(
    '#type' => 'value',
    '#value' => $nid,
  );
  if (isset($node->parent)) {
    $form['update'] = array(
      '#type' => 'submit',
      '#value' => t('Update book outline'),
    );
    $form['remove'] = array(
      '#type' => 'submit',
      '#value' => t('Remove from book outline'),
    );
  }
  else {
    $form['add'] = array(
      '#type' => 'submit',
      '#value' => t('Add to book outline'),
    );
  }
  drupal_set_title(check_plain($node->title));
  return $form;
}

/**
 * Handles book outline form submissions.
 */
function book_outline_submit($form_id, $form_values) {
  $op = $form_values['op'];
  $node = node_load($form_values['nid']);
  switch ($op) {
    case t('Add to book outline'):
      db_query('INSERT INTO {book} (nid, vid, parent, weight) VALUES (%d, %d, %d, %d)', $node->nid, $node->vid, $form_values['parent'], $form_values['weight']);
      db_query("UPDATE {node_revisions} SET log = '%s' WHERE vid = %d", $form_values['log'], $node->vid);
      drupal_set_message(t('The post has been added to the book.'));
      break;
    case t('Update book outline'):
      db_query('UPDATE {book} SET parent = %d, weight = %d WHERE vid = %d', $form_values['parent'], $form_values['weight'], $node->vid);
      db_query("UPDATE {node_revisions} SET log = '%s' WHERE vid = %d", $form_values['log'], $node->vid);
      drupal_set_message(t('The book outline has been updated.'));
      break;
    case t('Remove from book outline'):
      db_query('DELETE FROM {book} WHERE nid = %d', $node->nid);
      drupal_set_message(t('The post has been removed from the book.'));
      break;
  }
  return "node/{$node->nid}";
}

/**
 * Given a node, this function returns an array of 'book node' objects
 * representing the path in the book tree from the root to the
 * parent of the given node.
 *
 * @param $node
 *   A book node object for which to compute the path.
 *
 * @return
 *   An array of book node objects representing the path nodes root to
 *   parent of the given node. Returns an empty array if the node does
 *   not exist or is not part of a book hierarchy.
 */
function book_location($node, $nodes = array()) {
  $parent = db_fetch_object(db_query(db_rewrite_sql('SELECT n.nid, n.title, b.parent, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE n.nid = %d'), $node->parent));
  if (isset($parent->title)) {
    $nodes = book_location($parent, $nodes);
    $nodes[] = $parent;
  }
  return $nodes;
}

/**
 * Given a node, this function returns an array of 'book node' objects
 * representing the path in the book tree from the given node down to
 * the last sibling of it.
 *
 * @param $node
 *   A book node object where the path starts.
 *
 * @return
 *   An array of book node objects representing the path nodes from the
 *   given node. Returns an empty array if the node does not exist or
 *   is not part of a book hierarchy or there are no siblings.
 */
function book_location_down($node, $nodes = array()) {
  $last_direct_child = db_fetch_object(db_query(db_rewrite_sql('SELECT n.nid, n.title, b.parent, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE n.status = 1 AND b.parent = %d ORDER BY b.weight DESC, n.title DESC'), $node->nid));
  if ($last_direct_child) {
    $nodes[] = $last_direct_child;
    $nodes = book_location_down($last_direct_child, $nodes);
  }
  return $nodes;
}

/**
 * Fetches the node object of the previous page of the book.
 */
function book_prev($node) {

  // If the parent is zero, we are at the start of a book so there is no previous.
  if ($node->parent == 0) {
    return NULL;
  }

  // Previous on the same level:
  $direct_above = db_fetch_object(db_query(db_rewrite_sql("SELECT n.nid, n.title, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE b.parent = %d AND n.status = 1 AND (b.weight < %d OR (b.weight = %d AND n.title < '%s')) ORDER BY b.weight DESC, n.title DESC"), $node->parent, $node->weight, $node->weight, $node->title));
  if ($direct_above) {

    // Get last leaf of $above.
    $path = book_location_down($direct_above);
    return $path ? count($path) > 0 ? array_pop($path) : NULL : $direct_above;
  }
  else {

    // Direct parent:
    $prev = db_fetch_object(db_query(db_rewrite_sql('SELECT n.nid, n.title FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE n.nid = %d AND n.status = 1'), $node->parent));
    return $prev;
  }
}

/**
 * Fetches the node object of the next page of the book.
 */
function book_next($node) {

  // get first direct child
  $child = db_fetch_object(db_query(db_rewrite_sql('SELECT n.nid, n.title, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE b.parent = %d AND n.status = 1 ORDER BY b.weight ASC, n.title ASC'), $node->nid));
  if ($child) {
    return $child;
  }

  // No direct child: get next for this level or any parent in this book.
  $path = book_location($node);

  // Path to top-level node including this one.
  $path[] = $node;
  while (($leaf = array_pop($path)) && count($path)) {
    $next = db_fetch_object(db_query(db_rewrite_sql("SELECT n.nid, n.title, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE b.parent = %d AND n.status = 1 AND (b.weight > %d OR (b.weight = %d AND n.title > '%s')) ORDER BY b.weight ASC, n.title ASC"), $leaf->parent, $leaf->weight, $leaf->weight, $leaf->title));
    if ($next) {
      return $next;
    }
  }
}

/**
 * Returns the content of a given node. If $teaser if TRUE, returns
 * the teaser rather than full content. Displays the most recently
 * approved revision of a node (if any) unless we have to display this
 * page in the context of the moderation queue.
 */
function book_content($node, $teaser = FALSE) {

  // Return the page body.
  return node_prepare($node, $teaser);
}

/**
 * Implementation of hook_nodeapi().
 *
 * Appends book navigation to all nodes in the book.
 */
function book_nodeapi(&$node, $op, $teaser, $page) {
  switch ($op) {
    case 'load':
      return db_fetch_array(db_query('SELECT parent, weight FROM {book} WHERE vid = %d', $node->vid));
      break;
    case 'view':
      if (!$teaser) {
        if (isset($node->parent)) {
          $path = book_location($node);

          // Construct the breadcrumb:
          $node->breadcrumb = array();

          // Overwrite the trail with a book trail.
          foreach ($path as $level) {
            $node->breadcrumb[] = array(
              'path' => 'node/' . $level->nid,
              'title' => $level->title,
            );
          }
          $node->breadcrumb[] = array(
            'path' => 'node/' . $node->nid,
          );
          $node->content['book_navigation'] = array(
            '#value' => theme('book_navigation', $node),
            '#weight' => 100,
          );
          if ($page) {
            menu_set_location($node->breadcrumb);
          }
        }
      }
      break;
    case 'update':
      if (isset($node->parent)) {
        if ($node->revision) {
          db_query("INSERT INTO {book} (nid, vid, parent, weight) VALUES (%d, %d, %d, %d)", $node->nid, $node->vid, $node->parent, $node->weight);
        }
        else {
          db_query("UPDATE {book} SET parent = %d, weight = %d WHERE vid = %d", $node->parent, $node->weight, $node->vid);
        }
      }
      break;
    case 'delete revision':
      db_query('DELETE FROM {book} WHERE vid = %d', $node->vid);
      break;
    case 'delete':
      db_query('DELETE FROM {book} WHERE nid = %d', $node->nid);
      break;
  }
}

/**
 * Prepares the links to children (TOC) and forward/backward
 * navigation for a node presented as a book page.
 *
 * @ingroup themeable
 */
function theme_book_navigation($node) {
  $output = '';
  $links = '';
  if ($node->nid) {
    $tree = book_tree($node->nid);
    if ($prev = book_prev($node)) {
      drupal_add_link(array(
        'rel' => 'prev',
        'href' => url('node/' . $prev->nid),
      ));
      $links .= l(t('‹ ') . $prev->title, 'node/' . $prev->nid, array(
        'class' => 'page-previous',
        'title' => t('Go to previous page'),
      ));
    }
    if ($node->parent) {
      drupal_add_link(array(
        'rel' => 'up',
        'href' => url('node/' . $node->parent),
      ));
      $links .= l(t('up'), 'node/' . $node->parent, array(
        'class' => 'page-up',
        'title' => t('Go to parent page'),
      ));
    }
    if ($next = book_next($node)) {
      drupal_add_link(array(
        'rel' => 'next',
        'href' => url('node/' . $next->nid),
      ));
      $links .= l($next->title . t(' ›'), 'node/' . $next->nid, array(
        'class' => 'page-next',
        'title' => t('Go to next page'),
      ));
    }
    if (isset($tree) || isset($links)) {
      $output = '<div class="book-navigation">';
      if (isset($tree)) {
        $output .= $tree;
      }
      if (isset($links)) {
        $output .= '<div class="page-links clear-block">' . $links . '</div>';
      }
      $output .= '</div>';
    }
  }
  return $output;
}

/**
 * This is a helper function for book_toc().
 */
function book_toc_recurse($nid, $indent, $toc, $children, $exclude) {
  if ($children[$nid]) {
    foreach ($children[$nid] as $foo => $node) {
      if (!$exclude || $exclude != $node->nid) {
        $toc[$node->nid] = $indent . ' ' . $node->title;
        $toc = book_toc_recurse($node->nid, $indent . '--', $toc, $children, $exclude);
      }
    }
  }
  return $toc;
}

/**
 * Returns an array of titles and nid entries of book pages in table of contents order.
 */
function book_toc($exclude = 0) {
  $result = db_query(db_rewrite_sql('SELECT n.nid, n.title, b.parent, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE n.status = 1 ORDER BY b.weight, n.title'));
  $children = array();
  while ($node = db_fetch_object($result)) {
    if (!$children[$node->parent]) {
      $children[$node->parent] = array();
    }
    $children[$node->parent][] = $node;
  }
  $toc = array();

  // If the user has permission to create new books, add the top-level book page to the menu;
  if (user_access('create new books')) {
    $toc[0] = '<' . t('top-level') . '>';
  }
  $toc = book_toc_recurse(0, '', $toc, $children, $exclude);
  return $toc;
}

/**
 * This is a helper function for book_tree()
 */
function book_tree_recurse($nid, $depth, $children, $unfold = array()) {
  $output = '';
  if ($depth > 0) {
    if (isset($children[$nid])) {
      foreach ($children[$nid] as $foo => $node) {
        if (in_array($node->nid, $unfold)) {
          if ($tree = book_tree_recurse($node->nid, $depth - 1, $children, $unfold)) {
            $output .= '<li class="expanded">';
            $output .= l($node->title, 'node/' . $node->nid);
            $output .= '<ul class="menu">' . $tree . '</ul>';
            $output .= '</li>';
          }
          else {
            $output .= '<li class="leaf">' . l($node->title, 'node/' . $node->nid) . '</li>';
          }
        }
        else {
          if ($tree = book_tree_recurse($node->nid, 1, $children)) {
            $output .= '<li class="collapsed">' . l($node->title, 'node/' . $node->nid) . '</li>';
          }
          else {
            $output .= '<li class="leaf">' . l($node->title, 'node/' . $node->nid) . '</li>';
          }
        }
      }
    }
  }
  return $output;
}

/**
 * Returns an HTML nested list (wrapped in a menu-class div) representing the book nodes
 * as a tree.
 */
function book_tree($parent = 0, $depth = 3, $unfold = array()) {
  $result = db_query(db_rewrite_sql('SELECT n.nid, n.title, b.parent, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE n.status = 1 ORDER BY b.weight, n.title'));
  while ($node = db_fetch_object($result)) {
    $list = isset($children[$node->parent]) ? $children[$node->parent] : array();
    $list[] = $node;
    $children[$node->parent] = $list;
  }
  if ($tree = book_tree_recurse($parent, $depth, $children, $unfold)) {
    return '<ul class="menu">' . $tree . '</ul>';
  }
}

/**
 * Menu callback; prints a listing of all books.
 */
function book_render() {
  $result = db_query(db_rewrite_sql('SELECT n.nid, n.title, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE b.parent = 0 AND n.status = 1 ORDER BY b.weight, n.title'));
  $books = array();
  while ($node = db_fetch_object($result)) {
    $books[] = l($node->title, 'node/' . $node->nid);
  }
  return theme('item_list', $books);
}

/**
 * Menu callback; Generates various representation of a book page with
 * all descendants and prints the requested representation to output.
 *
 * The function delegates the generation of output to helper functions.
 * The function name is derived by prepending 'book_export_' to the
 * given output type. So, e.g., a type of 'html' results in a call to
 * the function book_export_html().
 *
 * @param type
 *   - a string encoding the type of output requested.
 *       The following types are currently supported in book module
 *          html: HTML (printer friendly output)
 *       Other types are supported in contributed modules.
 * @param nid
 *   - an integer representing the node id (nid) of the node to export
 *
 */
function book_export($type = 'html', $nid = 0) {
  $type = drupal_strtolower($type);
  $node_result = db_query(db_rewrite_sql('SELECT n.nid, n.title, b.parent FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE n.nid = %d'), $nid);
  if (db_num_rows($node_result) > 0) {
    $node = db_fetch_object($node_result);
  }
  $depth = count(book_location($node)) + 1;
  $export_function = 'book_export_' . $type;
  if (function_exists($export_function)) {
    print call_user_func($export_function, $nid, $depth);
  }
  else {
    drupal_set_message(t('Unknown export format.'));
    drupal_not_found();
  }
}

/**
 * This function is called by book_export() to generate HTML for export.
 *
 * The given node is /embedded to its absolute depth in a top level
 * section/. For example, a child node with depth 2 in the hierarchy
 * is contained in (otherwise empty) &lt;div&gt; elements
 * corresponding to depth 0 and depth 1. This is intended to support
 * WYSIWYG output - e.g., level 3 sections always look like level 3
 * sections, no matter their depth relative to the node selected to be
 * exported as printer-friendly HTML.
 *
 * @param nid
 *   - an integer representing the node id (nid) of the node to export
 * @param depth
 *   - an integer giving the depth in the book hierarchy of the node
 *     which is to be exported
 *
 * @return
 *   - string containing HTML representing the node and its children in
 *     the book hierarchy
*/
function book_export_html($nid, $depth) {
  if (user_access('see printer-friendly version')) {
    $node = node_load($nid);
    for ($i = 1; $i < $depth; $i++) {
      $content .= "<div class=\"section-{$i}\">\n";
    }
    $content .= book_recurse($nid, $depth, 'book_node_visitor_html_pre', 'book_node_visitor_html_post');
    for ($i = 1; $i < $depth; $i++) {
      $content .= "</div>\n";
    }
    return theme('book_export_html', check_plain($node->title), $content);
  }
  else {
    drupal_access_denied();
  }
}

/**
 * How the book's HTML export should be themed
 *
 * @ingroup themeable
 */
function theme_book_export_html($title, $content) {
  global $base_url;
  $html = "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">\n";
  $html .= '<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">';
  $html .= "\n<head>\n";
  $html .= '<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />';
  $html .= "\n<title>" . $title . "</title>\n";
  $html .= '<base href="' . $base_url . '/" />' . "\n";
  $html .= "<style type=\"text/css\">\n@import url(misc/print.css);\n</style>\n";
  $html .= "</head>\n<body>\n" . $content . "\n</body>\n</html>\n";
  return $html;
}

/**
 * Traverses the book tree. Applies the $visit_pre() callback to each
 * node, is called recursively for each child of the node (in weight,
 * title order). Finally appends the output of the $visit_post()
 * callback to the output before returning the generated output.
 *
 * @todo This is duplicitous with node_build_content().
 *
 * @param nid
 *  - the node id (nid) of the root node of the book hierarchy.
 * @param depth
 *  - the depth of the given node in the book hierarchy.
 * @param visit_pre
 *  - a function callback to be called upon visiting a node in the tree
 * @param visit_post
 *  - a function callback to be called after visiting a node in the tree,
 *    but before recursively visiting children.
 * @return
 *  - the output generated in visiting each node
 */
function book_recurse($nid = 0, $depth = 1, $visit_pre, $visit_post) {
  $result = db_query(db_rewrite_sql('SELECT n.nid, n.title, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE n.status = 1 AND n.nid = %d ORDER BY b.weight, n.title'), $nid);
  while ($page = db_fetch_object($result)) {

    // Load the node:
    $node = node_load($page->nid);
    if ($node) {
      if (function_exists($visit_pre)) {
        $output .= call_user_func($visit_pre, $node, $depth, $nid);
      }
      else {
        $output .= book_node_visitor_html_pre($node, $depth, $nid);
      }
      $children = db_query(db_rewrite_sql('SELECT n.nid, n.title, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE n.status = 1 AND b.parent = %d ORDER BY b.weight, n.title'), $node->nid);
      while ($childpage = db_fetch_object($children)) {
        $childnode = node_load($childpage->nid);
        if ($childnode->nid != $node->nid) {
          $output .= book_recurse($childnode->nid, $depth + 1, $visit_pre, $visit_post);
        }
      }
      if (function_exists($visit_post)) {
        $output .= call_user_func($visit_post, $node, $depth);
      }
      else {

        # default
        $output .= book_node_visitor_html_post($node, $depth);
      }
    }
  }
  return $output;
}

/**
 * Generates printer-friendly HTML for a node. This function
 * is a 'pre-node' visitor function for book_recurse().
 *
 * @param $node
 *   - the node to generate output for.
 * @param $depth
 *   - the depth of the given node in the hierarchy. This
 *   is used only for generating output.
 * @param $nid
 *   - the node id (nid) of the given node. This
 *   is used only for generating output.
 * @return
 *   - the HTML generated for the given node.
 */
function book_node_visitor_html_pre($node, $depth, $nid) {

  // Remove the delimiter (if any) that separates the teaser from the body.
  $node->body = str_replace('<!--break-->', '', $node->body);

  // The 'view' hook can be implemented to overwrite the default function
  // to display nodes.
  if (node_hook($node, 'view')) {
    $node = node_invoke($node, 'view', FALSE, FALSE);
  }
  else {
    $node = node_prepare($node, FALSE);
  }

  // Allow modules to make their own additions to the node.
  node_invoke_nodeapi($node, 'print');
  $output .= "<div id=\"node-" . $node->nid . "\" class=\"section-{$depth}\">\n";
  $output .= "<h1 class=\"book-heading\">" . check_plain($node->title) . "</h1>\n";
  $output .= drupal_render($node->content);
  return $output;
}

/**
 * Finishes up generation of printer-friendly HTML after visiting a
 * node. This function is a 'post-node' visitor function for
 * book_recurse().
 */
function book_node_visitor_html_post($node, $depth) {
  return "</div>\n";
}
function _book_admin_table($nodes = array()) {
  $form = array(
    '#theme' => 'book_admin_table',
    '#tree' => TRUE,
  );
  foreach ($nodes as $node) {
    $form = array_merge($form, _book_admin_table_tree($node, 0));
  }
  return $form;
}
function _book_admin_table_tree($node, $depth) {
  $form = array();
  $form[] = array(
    'nid' => array(
      '#type' => 'value',
      '#value' => $node->nid,
    ),
    'depth' => array(
      '#type' => 'value',
      '#value' => $depth,
    ),
    'title' => array(
      '#type' => 'textfield',
      '#default_value' => $node->title,
      '#maxlength' => 255,
    ),
    'weight' => array(
      '#type' => 'weight',
      '#default_value' => $node->weight,
      '#delta' => 15,
    ),
  );
  $children = db_query(db_rewrite_sql('SELECT n.nid, n.title, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE b.parent = %d ORDER BY b.weight, n.title'), $node->nid);
  while ($child = db_fetch_object($children)) {
    $form = array_merge($form, _book_admin_table_tree(node_load($child->nid), $depth + 1));
  }
  return $form;
}
function theme_book_admin_table($form) {
  $header = array(
    t('Title'),
    t('Weight'),
    array(
      'data' => t('Operations'),
      'colspan' => '3',
    ),
  );
  $rows = array();
  foreach (element_children($form) as $key) {
    $nid = $form[$key]['nid']['#value'];
    $pid = $form[0]['nid']['#value'];
    $rows[] = array(
      '<div style="padding-left: ' . 25 * $form[$key]['depth']['#value'] . 'px;">' . drupal_render($form[$key]['title']) . '</div>',
      drupal_render($form[$key]['weight']),
      l(t('view'), 'node/' . $nid),
      l(t('edit'), 'node/' . $nid . '/edit'),
      l(t('delete'), 'node/' . $nid . '/delete', NULL, 'destination=admin/content/book' . (arg(3) == 'orphan' ? '/orphan' : '') . ($pid != $nid ? '/' . $pid : '')),
    );
  }
  return theme('table', $header, $rows);
}

/**
 * Display an administrative view of the hierarchy of a book.
 */
function book_admin_edit($nid) {
  $node = node_load($nid);
  if ($node->nid) {
    drupal_set_title(check_plain($node->title));
    $form = array();
    $form['table'] = _book_admin_table(array(
      $node,
    ));
    $form['save'] = array(
      '#type' => 'submit',
      '#value' => t('Save book pages'),
    );
    return $form;
  }
  else {
    drupal_not_found();
  }
}

/**
 * Menu callback; displays a listing of all orphaned book pages.
 */
function book_admin_orphan() {
  $result = db_query(db_rewrite_sql('SELECT n.nid, n.title, n.status, b.parent FROM {node} n INNER JOIN {book} b ON n.vid = b.vid'));
  $pages = array();
  while ($page = db_fetch_object($result)) {
    $pages[$page->nid] = $page;
  }
  $orphans = array();
  if (count($pages)) {
    foreach ($pages as $page) {
      if ($page->parent && empty($pages[$page->parent])) {
        $orphans[] = node_load($page->nid);
      }
    }
  }
  if (count($orphans)) {
    $form['table'] = _book_admin_table($orphans);
    $form['save'] = array(
      '#type' => 'submit',
      '#value' => t('Save book pages'),
    );
  }
  else {
    $form['error'] = array(
      '#value' => '<p>' . t('There are no orphan pages.') . '</p>',
    );
  }
  $form['#base'] = 'book_admin_edit';
  return $form;
}
function book_admin_edit_submit($form_id, $form_values) {
  foreach ($form_values['table'] as $row) {
    $node = node_load($row['nid']);
    if ($row['title'] != $node->title || $row['weight'] != $node->weight) {
      $node->title = $row['title'];
      $node->weight = $row['weight'];
      node_save($node);
      watchdog('content', t('%type: updated %title.', array(
        '%type' => t('book'),
        '%title' => $node->title,
      )), WATCHDOG_NOTICE, l(t('view'), 'node/' . $node->nid));
    }
  }
  if (is_numeric(arg(3))) {

    // Updating pages in a single book.
    $book = node_load(arg(3));
    drupal_set_message(t('Updated book %title.', array(
      '%title' => $book->title,
    )));
  }
  else {

    // Updating the orphan pages.
    drupal_set_message(t('Updated orphan book pages.'));
  }
}

/**
 * Menu callback; displays the book administration page.
 */
function book_admin($nid = 0) {
  if ($nid) {
    return drupal_get_form('book_admin_edit', $nid);
  }
  else {
    return book_admin_overview();
  }
}

/**
 * Returns an administrative overview of all books.
 */
function book_admin_overview() {
  $result = db_query(db_rewrite_sql('SELECT n.nid, n.title, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE b.parent = 0 ORDER BY b.weight, n.title'));
  while ($book = db_fetch_object($result)) {
    $rows[] = array(
      l($book->title, "node/{$book->nid}"),
      l(t('outline'), "admin/content/book/{$book->nid}"),
    );
  }
  $headers = array(
    t('Book'),
    t('Operations'),
  );
  return theme('table', $headers, $rows);
}

/**
 * Implementation of hook_help().
 */
function book_help($section) {
  switch ($section) {
    case 'admin/help#book':
      $output = '<p>' . t('The <em>book</em> module is suited for creating structured, multi-page hypertexts such as site resource guides, manuals, and Frequently Asked Questions (FAQs). It permits a document to have chapters, sections, subsections, etc. Authors with suitable permissions can add pages to a collaborative book,  placing them into the existing document by adding them to a table of contents menu.') . '</p>';
      $output .= '<p>' . t('Book pages have navigation elements at the bottom of the page for moving through the text.  These link to the previous and next pages in the book, as well as a link labeled <em>up</em>, leading to the level above in the structure.  More comprehensive navigation may be provided by enabling the <em>book navigation block</em> on the <a href="@admin-block">block administration page</a>.', array(
        '@admin-block' => url('admin/build/block'),
      )) . '</p>';
      $output .= '<p>' . t('Users can select the <em>printer-friendly version</em> link visible at the bottom of a book page to generate a printer-friendly display of the page and all of its subsections. ') . '</p>';
      $output .= '<p>' . t("Posts of type %book are automatically added to the book hierarchy. Users with the <em>outline posts in books</em> permission can also add content of any other type to a book, placing it into the existing book structure through the interface that's available by clicking on the <em>outline</em> tab while viewing that post.", array(
        '%book' => node_get_types('name', 'book'),
      )) . '</p>';
      $output .= '<p>' . t('Administrators can view a list of all books on the <a href="@admin-node-book">book administration page</a>.  In this list there is a link to an outline page for each book, from which is it possible to change the titles of sections, or to change their weight, thus reordering sections. From this administrative interface, it is also possible to determine whether there are any orphan pages - pages that have become disconnected from the rest of the book structure.', array(
        '@admin-node-book' => url('admin/content/book'),
      )) . '</p>';
      $output .= '<p>' . t('For more information please read the configuration and customization handbook <a href="@book">Book page</a>.', array(
        '@book' => 'http://drupal.org/handbook/modules/book/',
      )) . '</p>';
      return $output;
    case 'admin/content/book':
      return '<p>' . t('The book module offers a means to organize content, authored by many users, in an online manual, outline or FAQ.') . '</p>';
    case 'admin/content/book/orphan':
      return '<p>' . t('Pages in a book are like a tree. As pages are edited, reorganized and removed, child pages might be left with no link to the rest of the book. Such pages are referred to as "orphan pages". On this page, administrators can review their books for orphans and reattach those pages as desired.') . '</p>';
  }
  if (arg(0) == 'node' && is_numeric(arg(1)) && arg(2) == 'outline') {
    return '<p>' . t('The outline feature allows you to include posts in the <a href="@book">book hierarchy</a>.', array(
      '@book' => url('book'),
    )) . '</p>';
  }
}