Commit e202e3df authored by catch's avatar catch
Browse files

Issue #1327484 by xenophyle: Clean up API docs for book.

parent 8c47bfff
......@@ -3,12 +3,17 @@
/**
* @file
* Default theme implementation for rendering book outlines within a block.
* This template is used only when the block is configured to "show block on
* all pages" which presents Multiple independent books on all pages.
*
* This template is used only when the block is configured to "show block on all
* pages", which presents multiple independent books on all pages.
*
* Available variables:
* - $book_menus: Array of book outlines keyed to the parent book ID. Call
* render() on each to print it as an unordered list.
*
* @see template_preprocess_book_all_books_block()
*
* @ingroup themeable
*/
?>
<?php foreach ($book_menus as $book_id => $menu): ?>
......
......@@ -14,6 +14,8 @@
* book-node-export-html.tpl.php.
*
* @see template_preprocess_book_export_html()
*
* @ingroup themeable
*/
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
......
<?php
/**
* @file
* Default theme implementation to navigate books. Presented under nodes that
* are a part of book outlines.
* Default theme implementation to navigate books.
*
* Presented under nodes that are a part of book outlines.
*
* Available variables:
* - $tree: The immediate children of the current node rendered as an
* unordered list.
* - $current_depth: Depth of the current node within the book outline.
* Provided for context.
* - $tree: The immediate children of the current node rendered as an unordered
* list.
* - $current_depth: Depth of the current node within the book outline. Provided
* for context.
* - $prev_url: URL to the previous node.
* - $prev_title: Title of the previous node.
* - $parent_url: URL to the parent node.
......@@ -18,14 +19,16 @@
* - $next_title: Title of the next node.
* - $has_links: Flags TRUE whenever the previous, parent or next data has a
* value.
* - $book_id: The book ID of the current outline being viewed. Same as the
* node ID containing the entire outline. Provided for context.
* - $book_url: The book/node URL of the current outline being viewed.
* Provided as an option. Not used by default.
* - $book_id: The book ID of the current outline being viewed. Same as the node
* ID containing the entire outline. Provided for context.
* - $book_url: The book/node URL of the current outline being viewed. Provided
* as an option. Not used by default.
* - $book_title: The book/node title of the current outline being viewed.
* Provided as an option. Not used by default.
*
* @see template_preprocess_book_navigation()
*
* @ingroup themeable
*/
?>
<?php if ($tree || $has_links): ?>
......
......@@ -2,8 +2,7 @@
/**
* @file
* Default theme implementation for rendering a single node in a printer
* friendly outline.
* Default theme implementation for a single node in a printer-friendly outline.
*
* @see book-node-export-html.tpl.php
* Where it is collected and printed out.
......@@ -15,6 +14,8 @@
* - $children: All the child nodes recursively rendered through this file.
*
* @see template_preprocess_book_node_export_html()
*
* @ingroup themeable
*/
?>
<div id="node-<?php print $node->nid; ?>" class="section-<?php print $depth; ?>">
......
......@@ -6,7 +6,11 @@
*/
/**
* Returns an administrative overview of all books.
* Page callback: Returns an administrative overview of all books.
*
* Path: admin/content/book
*
* @see book_menu()
*/
function book_admin_overview() {
$rows = array();
......@@ -22,10 +26,12 @@ function book_admin_overview() {
}
/**
* Builds and returns the book settings form.
* Form constructor for the book settings form.
*
* @see book_admin_settings_validate()
* Path: admin/content/book/settings
*
* @see book_menu()
* @see book_admin_settings_validate()
* @ingroup forms
*/
function book_admin_settings() {
......@@ -52,9 +58,7 @@ function book_admin_settings() {
}
/**
* Validate the book settings form.
*
* @see book_admin_settings()
* Form validation handler for book_admin_settings().
*/
function book_admin_settings_validate($form, &$form_state) {
$child_type = $form_state['values']['book_child_type'];
......@@ -64,11 +68,17 @@ function book_admin_settings_validate($form, &$form_state) {
}
/**
* Build the form to administrate the hierarchy of a single book.
* Form constructor for administering a single book's hierarchy.
*
* @see book_admin_edit_submit()
* Path: admin/content/book/%node
*
* @ingroup forms.
* @param $node
* The node of the top-level page in the book.
*
* @see book_menu()
* @see book_admin_edit_validate()
* @see book_admin_edit_submit()
* @ingroup forms
*/
function book_admin_edit($form, $form_state, $node) {
drupal_set_title($node->title);
......@@ -83,9 +93,11 @@ function book_admin_edit($form, $form_state, $node) {
}
/**
* Check that the book has not been changed while using the form.
* Form validation handler for book_admin_edit().
*
* @see book_admin_edit()
* Checks that the book has not been changed while using the form.
*
* @see book_admin_edit_submit()
*/
function book_admin_edit_validate($form, &$form_state) {
if ($form_state['values']['tree_hash'] != $form_state['values']['tree_current_hash']) {
......@@ -94,12 +106,12 @@ function book_admin_edit_validate($form, &$form_state) {
}
/**
* Handle submission of the book administrative page form.
* Form submission handler for book_admin_edit().
*
* This function takes care to save parent menu items before their children.
* Saving menu items in the incorrect order can break the menu tree.
*
* @see book_admin_edit()
* @see book_admin_edit_validate()
* @see menu_overview_form_submit()
*/
function book_admin_edit_submit($form, &$form_state) {
......@@ -139,7 +151,12 @@ function book_admin_edit_submit($form, &$form_state) {
}
/**
* Build the table portion of the form for the book administration page.
* Builds the table portion of the form for the book administration page.
*
* @param $node
* The node of the top-level page in the book.
* @param $form
* The form that is being modified.
*
* @see book_admin_edit()
*/
......@@ -169,7 +186,15 @@ function _book_admin_table($node, &$form) {
}
/**
* Recursive helper to build the main table in the book administration page form.
* Helps build the main table in the book administration page form.
*
* @param $tree
* A subtree of the book menu hierarchy.
* @param $form
* The form that is being modified.
*
* @return
* The form that is being modified.
*
* @see book_admin_edit()
*/
......
......@@ -28,6 +28,9 @@ function book_uninstall() {
menu_cache_clear_all();
}
/**
* Creates the book content type.
*/
function _book_install_type_create() {
// Create an additional node type.
$book_node_type = array(
......
......@@ -84,7 +84,12 @@ function book_permission() {
}
/**
* Inject links into $node as needed.
* Adds relevant book links to the node's links.
*
* @param $node
* The book page node to add links to.
* @param $view_mode
* The view mode of the node.
*/
function book_node_view_link($node, $view_mode) {
$links = array();
......@@ -190,14 +195,30 @@ function book_menu() {
}
/**
* Menu item access callback - determine if the outline tab is accessible.
* Access callback: Determines if the outline tab is accessible.
*
* Path:
* - admin/content/book/%node
* - node/%node/outline
*
* @param $node
* The node whose outline tab is to be viewed.
*
* @see book_menu()
*/
function _book_outline_access($node) {
return user_access('administer book outlines') && node_access('view', $node);
}
/**
* Menu item access callback - determine if the user can remove nodes from the outline.
* Access callback: Determines if the user can remove nodes from the outline.
*
* Path: node/%node/outline/remove
*
* @param $node
* The node to remove from the outline.
*
* @see book_menu()
*/
function _book_outline_remove_access($node) {
return isset($node->book) && ($node->book['bid'] != $node->nid) && _book_outline_access($node);
......@@ -348,6 +369,9 @@ function theme_book_title_link($variables) {
*
* This list may be used for generating a list of all the books, or for building
* the options for a form select.
*
* @return
* An array of all books.
*/
function book_get_books() {
$all_books = &drupal_static(__FUNCTION__);
......@@ -416,7 +440,7 @@ function book_form_node_form_alter(&$form, &$form_state, $form_id) {
}
/**
* Submit handler to change a node's book.
* Form submission handler for node_form().
*
* This handler is run when JavaScript is disabled. It triggers the form to
* rebuild so that the "Parent item" options are changed to reflect the newly
......@@ -425,6 +449,7 @@ function book_form_node_form_alter(&$form, &$form_state, $form_id) {
* book_form_update() Ajax callback instead.
*
* @see book_form_update()
* @see book_form_node_form_alter()
*/
function book_pick_book_nojs_submit($form, &$form_state) {
$form_state['node']->book = $form_state['values']['book'];
......@@ -432,11 +457,17 @@ function book_pick_book_nojs_submit($form, &$form_state) {
}
/**
* Build the parent selection form element for the node form or outline tab.
* Builds the parent selection form element for the node form or outline tab.
*
* This function is also called when generating a new set of options during the
* Ajax callback, so an array is returned that can be used to replace an existing
* form element.
* Ajax callback, so an array is returned that can be used to replace an
* existing form element.
*
* @param $book_link
* A fully loaded menu link that is part of the book hierarchy.
*
* @return
* A parent selection form element.
*/
function _book_parent_select($book_link) {
if (variable_get('menu_override_parent_selector', FALSE)) {
......@@ -479,7 +510,10 @@ function _book_parent_select($book_link) {
}
/**
* Build the common elements of the book form for the node and outline forms.
* Builds the common elements of the book form for the node and outline forms.
*
* @param $node
* The node whose form is being viewed.
*/
function _book_add_form_elements(&$form, &$form_state, $node) {
// If the form is being processed during the Ajax callback of our book bid
......@@ -577,10 +611,17 @@ function book_form_update($form, $form_state) {
}
/**
* Common helper function to handles additions and updates to the book outline.
* Handles additions and updates to the book outline.
*
* This common helper function performs all additions and updates to the book
* outline through node addition, node editing, node deletion, or the outline
* tab.
*
* Performs all additions and updates to the book outline through node addition,
* node editing, node deletion, or the outline tab.
* @param $node
* The node that is being saved, added, deleted, or moved.
*
* @return
* TRUE if the menu link was saved; FALSE otherwise.
*/
function _book_update_outline($node) {
if (empty($node->book['bid'])) {
......@@ -643,7 +684,7 @@ function _book_update_outline($node) {
}
/**
* Update the bid for a page and its children when it is moved to a new book.
* Updates the book ID of a page and its children when it moves to a new book.
*
* @param $book_link
* A fully loaded menu link that is part of the book hierarchy.
......@@ -665,16 +706,17 @@ function book_update_bid($book_link) {
}
/**
* Get the book menu tree for a page, and return it as a linear array.
* Gets the book menu tree for a page and returns it as a linear array.
*
* @param $book_link
* A fully loaded menu link that is part of the book hierarchy.
*
* @return
* A linear array of menu links in the order that the links are shown in the
* menu, so the previous and next pages are the elements before and after the
* element corresponding to $node. The children of $node (if any) will come
* immediately after it in the array, and links will only be fetched as deep
* as one level deeper than $book_link.
* element corresponding to the current node. The children of the current node
* (if any) will come immediately after it in the array, and links will only
* be fetched as deep as one level deeper than $book_link.
*/
function book_get_flat_menu($book_link) {
$flat = &drupal_static(__FUNCTION__, array());
......@@ -690,7 +732,14 @@ function book_get_flat_menu($book_link) {
}
/**
* Recursive helper function for book_get_flat_menu().
* Recursively converts a tree of menu links to a flat array.
*
* @param $tree
* A tree of menu links in an array.
* @param $flat
* A flat array of the menu links from $tree.
*
* @see book_get_flat_menu().
*/
function _book_flatten_menu($tree, &$flat) {
foreach ($tree as $data) {
......@@ -705,6 +754,13 @@ function _book_flatten_menu($tree, &$flat) {
/**
* Fetches the menu link for the previous page of the book.
*
* @param $book_link
* A fully loaded menu link that is part of the book hierarchy.
*
* @return
* A fully loaded menu link for the page before the one represented in
* $book_link.
*/
function book_prev($book_link) {
// If the parent is zero, we are at the start of a book.
......@@ -740,6 +796,13 @@ function book_prev($book_link) {
/**
* Fetches the menu link for the next page of the book.
*
* @param $book_link
* A fully loaded menu link that is part of the book hierarchy.
*
* @return
* A fully loaded menu link for the page after the one represented in
* $book_link.
*/
function book_next($book_link) {
$flat = book_get_flat_menu($book_link);
......@@ -755,7 +818,13 @@ function book_next($book_link) {
}
/**
* Format the menu links for the child pages of the current page.
* Formats the menu links for the child pages of the current page.
*
* @param $book_link
* A fully loaded menu link that is part of the book hierarchy.
*
* @return
* HTML for the links to the child pages of the current page.
*/
function book_children($book_link) {
$flat = book_get_flat_menu($book_link);
......@@ -784,7 +853,13 @@ function book_children($book_link) {
}
/**
* Generate the corresponding menu name from a book ID.
* Generates the corresponding menu name from a book ID.
*
* @param $bid
* The book ID for which to make a menu name.
*
* @return
* The menu name.
*/
function book_menu_name($bid) {
return 'book-toc-' . $bid;
......@@ -824,7 +899,7 @@ function book_node_view($node, $view_mode) {
/**
* Implements hook_page_alter().
*
* Add the book menu to the list of menus used to build the active trail when
* Adds the book menu to the list of menus used to build the active trail when
* viewing a book page.
*/
function book_page_alter(&$page) {
......@@ -940,14 +1015,24 @@ function book_node_prepare($node) {
}
/**
* Find the depth limit for items in the parent select.
* Finds the depth limit for items in the parent select.
*
* @param $book_link
* A fully loaded menu link that is part of the book hierarchy.
*
* @return
* The depth limit for items in the parent select.
*/
function _book_parent_depth_limit($book_link) {
return MENU_MAX_DEPTH - 1 - (($book_link['mlid'] && $book_link['has_children']) ? menu_link_children_relative_depth($book_link) : 0);
}
/**
* Form altering function for the confirm form for a single node deletion.
* Implements hook_form_FORM_ID_alter().
*
* Alters the confirm form for a single node deletion.
*
* @see node_delete_confirm()
*/
function book_form_node_delete_confirm_alter(&$form, $form_state) {
$node = node_load($form['nid']['#value']);
......@@ -961,23 +1046,29 @@ function book_form_node_delete_confirm_alter(&$form, $form_state) {
}
/**
* Return an array with default values for a book link.
* Returns an array with default values for a book page's menu link.
*
* @param $nid
* The ID of the node whose menu link is being created.
*
* @return
* The default values for the menu link.
*/
function _book_link_defaults($nid) {
return array('original_bid' => 0, 'menu_name' => '', 'nid' => $nid, 'bid' => 0, 'router_path' => 'node/%', 'plid' => 0, 'mlid' => 0, 'has_children' => 0, 'weight' => 0, 'module' => 'book', 'options' => array());
}
/**
* Process variables for book-all-books-block.tpl.php.
* Processes variables for book-all-books-block.tpl.php.
*
* The $variables array contains the following arguments:
* - $book_menus
* All non-renderable elements are removed so that the template has full access
* to the structured data but can also simply iterate over all elements and
* render them (as in the default template).
*
* All non-renderable elements are removed so that the template has full
* access to the structured data but can also simply iterate over all
* elements and render them (as in the default template).
* The $variables array contains the following elements:
* - book_menus
*
* @see book-navigation.tpl.php
* @see book-all-books-block.tpl.php
*/
function template_preprocess_book_all_books_block(&$variables) {
// Remove all non-renderable elements.
......@@ -989,10 +1080,10 @@ function template_preprocess_book_all_books_block(&$variables) {
}
/**
* Process variables for book-navigation.tpl.php.
* Processes variables for book-navigation.tpl.php.
*
* The $variables array contains the following arguments:
* - $book_link
* The $variables array contains the following elements:
* - book_link
*
* @see book-navigation.tpl.php
*/
......@@ -1049,13 +1140,13 @@ function template_preprocess_book_navigation(&$variables) {
/**
* Recursively processes and formats menu items for book_toc().
*
* This helper function recursively modifies the $toc array for each item in
* $tree, ignoring items in the exclude array or at a depth greater than the
* limit. Truncates titles over thirty characters and appends an indentation
* string incremented by depth.
* This helper function recursively modifies the table of contents array for
* each item in the menu tree, ignoring items in the exclude array or at a depth
* greater than the limit. Truncates titles over thirty characters and appends
* an indentation string incremented by depth.
*
* @param $tree
* The data structure of the book's menu tree. Includes hidden links.
* The data structure of the book's menu tree. Includes hidden links.
* @param $indent
* A string appended to each menu item title. Increments by '--' per depth
* level.
......@@ -1063,8 +1154,8 @@ function template_preprocess_book_navigation(&$variables) {
* Reference to the table of contents array. This is modified in place, so the
* function does not have a return value.
* @param $exclude
* Optional array of mlid values. Any link whose mlid is in this array will be
* excluded (along with its children).
* Optional array of menu link ID values. Any link whose menu link ID is in
* this array will be excluded (along with its children).
* @param $depth_limit
* Any link deeper than this value will be excluded (along with its children).
*/
......@@ -1092,10 +1183,12 @@ function _book_toc_recurse($tree, $indent, &$toc, $exclude, $depth_limit) {
* @param $depth_limit
* Any link deeper than this value will be excluded (along with its children).
* @param $exclude
* Optional array of mlid values. Any link whose mlid is in this array
* will be excluded (along with its children).
* Optional array of menu link ID values. Any link whose menu link ID is in
* this array will be excluded (along with its children).
*
* @return
* An array of mlid, title pairs for use as options for selecting a book page.
* An array of (menu link ID, title) pairs for use as options for selecting a
* book page.
*/
function book_toc($bid, $depth_limit, $exclude = array()) {
$tree = menu_tree_all_data(book_menu_name($bid));
......@@ -1106,12 +1199,12 @@ function book_toc($bid, $depth_limit, $exclude = array()) {
}
/**
* Process variables for book-export-html.tpl.php.
* Processes variables for book-export-html.tpl.php.
*
* The $variables array contains the following arguments:
* - $title
* - $contents
* - $depth
* The $variables array contains the following elements:
* - title
* - contents
* - depth
*
* @see book-export-html.tpl.php
*/
......@@ -1126,16 +1219,16 @@ function template_preprocess_book_export_html(&$variables) {
}
/**
* Traverse the book tree to build printable or exportable output.
* Traverses the book tree to build printable or exportable output.
*
* During the traversal, the $visit_func() callback is applied to each
* node, and is called recursively for each child of the node (in weight,
* title order).
* During the traversal, the $visit_func() callback is applied to each node and
* is called recursively for each child of the node (in weight, title order).
*
* @param $tree
* A subtree of the book menu hierarchy, rooted at the current page.
* @param $visit_func
* A function callback to be called upon visiting a node in the tree.
*
* @return
* The output generated in visiting each node.
*/
......@@ -1167,14 +1260,15 @@ function book_export_traverse($tree, $visit_func) {
/**
* Generates printer-friendly HTML for a node.
*
* @see book_export_traverse()
*
* @param $node
* The node that will be output.
* @param $children
* All the rendered child nodes within the current node.
*
* @return
* The HTML generated for the given node.
*
* @see book_export_traverse()
*/
function book_node_export($node, $children = '') {
$build = node_view($node, 'print');
......@@ -1186,11 +1280,11 @@ function book_node_export($node, $children = '') {
}
/**
* Process variables for book-node-export-html.tpl.php.
* Processes variables for book-node-export-html.tpl.php.
*
* The $variables array contains the following arguments:
* - $node
* - $children
* The $variables array contains the following elements:
* - node
* - children
*
* @see book-node-export-html.tpl.php