diff options
Diffstat (limited to 'modules/book')
| -rw-r--r-- | modules/book/book-rtl.css | 4 | ||||
| -rw-r--r-- | modules/book/book.admin.inc | 15 | ||||
| -rw-r--r-- | modules/book/book.css | 4 | ||||
| -rw-r--r-- | modules/book/book.js | 1 | ||||
| -rw-r--r-- | modules/book/book.module | 47 | ||||
| -rw-r--r-- | modules/book/book.pages.inc | 12 | ||||
| -rw-r--r-- | modules/book/book.test | 121 |
7 files changed, 138 insertions, 66 deletions
diff --git a/modules/book/book-rtl.css b/modules/book/book-rtl.css index f3a84c20e..40dff0e53 100644 --- a/modules/book/book-rtl.css +++ b/modules/book/book-rtl.css @@ -1,3 +1,7 @@ +/** + * @file + * Right-to-Left styling for the Book module. + */ .book-navigation .menu { padding: 1em 3em 0 0; diff --git a/modules/book/book.admin.inc b/modules/book/book.admin.inc index 62c6e841a..cc3f08fc8 100644 --- a/modules/book/book.admin.inc +++ b/modules/book/book.admin.inc @@ -2,11 +2,16 @@ /** * @file - * Admin page callbacks for the book module. + * Administration page callbacks for the Book module. */ /** * Returns an administrative overview of all books. + * + * @return string + * A HTML-formatted string with the administrative page content. + * + * @see book_menu() */ function book_admin_overview() { $rows = array(); @@ -53,6 +58,8 @@ function book_admin_settings() { /** * Form validation handler for book_admin_settings(). + * + * @see book_admin_settings_submit() */ function book_admin_settings_validate($form, &$form_state) { $child_type = $form_state['values']['book_child_type']; @@ -149,7 +156,7 @@ function book_admin_edit_submit($form, &$form_state) { * @param $node * The node of the top-level page in the book. * @param $form - * The form that is being modified. + * The form that is being modified, passed by reference. * * @see book_admin_edit() */ @@ -184,10 +191,10 @@ function _book_admin_table($node, &$form) { * @param $tree * A subtree of the book menu hierarchy. * @param $form - * The form that is being modified. + * The form that is being modified, passed by reference. * * @return - * The form that is being modified. + * The modified form array. * * @see book_admin_edit() */ diff --git a/modules/book/book.css b/modules/book/book.css index a8d2136df..00e379ee0 100644 --- a/modules/book/book.css +++ b/modules/book/book.css @@ -1,3 +1,7 @@ + /** + * @file + * Styling for the Book module. + */ .book-navigation .menu { border-top: 1px solid #888; diff --git a/modules/book/book.js b/modules/book/book.js index 0853e8ecb..64f4aee68 100644 --- a/modules/book/book.js +++ b/modules/book/book.js @@ -3,7 +3,6 @@ * Javascript behaviors for the Book module. */ - (function ($) { Drupal.behaviors.bookFieldsetSummaries = { diff --git a/modules/book/book.module b/modules/book/book.module index 1fb0c0b11..71b89945e 100644 --- a/modules/book/book.module +++ b/modules/book/book.module @@ -221,6 +221,9 @@ function _book_outline_remove_access($node) { * * A node can be removed from a book if it is actually in a book and it either * is not a top-level page or is a top-level page with no children. + * + * @param $node + * The node to remove from the outline. */ function _book_node_is_removable($node) { return (!empty($node->book['bid']) && (($node->book['bid'] != $node->nid) || !$node->book['has_children'])); @@ -734,7 +737,7 @@ function book_get_flat_menu($book_link) { * @param $tree * A tree of menu links in an array. * @param $flat - * A flat array of the menu links from $tree. + * A flat array of the menu links from $tree, passed by reference. * * @see book_get_flat_menu(). */ @@ -1062,8 +1065,9 @@ function _book_link_defaults($nid) { * 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 + * @param $variables + * An associative array containing the following key: + * - book_menus * * @see book-all-books-block.tpl.php */ @@ -1079,8 +1083,9 @@ function template_preprocess_book_all_books_block(&$variables) { /** * Processes variables for book-navigation.tpl.php. * - * The $variables array contains the following elements: - * - book_link + * @param $variables + * An associative array containing the following key: + * - book_link * * @see book-navigation.tpl.php */ @@ -1151,8 +1156,9 @@ 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 menu link ID values. Any link whose menu link ID is in - * this array will be excluded (along with its children). + * (optional) An array of menu link ID values. Any link whose menu link ID is + * in this array will be excluded (along with its children). Defaults to an + * empty array. * @param $depth_limit * Any link deeper than this value will be excluded (along with its children). */ @@ -1198,10 +1204,11 @@ function book_toc($bid, $depth_limit, $exclude = array()) { /** * Processes variables for book-export-html.tpl.php. * - * The $variables array contains the following elements: - * - title - * - contents - * - depth + * @param $variables + * An associative array containing the following keys: + * - title + * - contents + * - depth * * @see book-export-html.tpl.php */ @@ -1261,7 +1268,8 @@ function book_export_traverse($tree, $visit_func) { * @param $node * The node that will be output. * @param $children - * All the rendered child nodes within the current node. + * (optional) All the rendered child nodes within the current node. Defaults + * to an empty string. * * @return * The HTML generated for the given node. @@ -1280,9 +1288,10 @@ function book_node_export($node, $children = '') { /** * Processes variables for book-node-export-html.tpl.php. * - * The $variables array contains the following elements: - * - node - * - children + * @param $variables + * An associative array containing the following keys: + * - node + * - children * * @see book-node-export-html.tpl.php */ @@ -1294,6 +1303,12 @@ function template_preprocess_book_node_export_html(&$variables) { /** * Determine if a given node type is in the list of types allowed for books. + * + * @param $type + * A node type. + * + * @return + * A Boolean TRUE if the node type can be included in books; otherwise, FALSE. */ function book_type_is_allowed($type) { return in_array($type, variable_get('book_allowed_types', array('book'))); @@ -1336,7 +1351,7 @@ function book_node_type_update($type) { * * @return * A menu link, with the link translated for rendering and data added from the - * {book} table. + * {book} table. FALSE if there is an error. */ function book_link_load($mlid) { if ($item = db_query("SELECT * FROM {menu_links} ml INNER JOIN {book} b ON b.mlid = ml.mlid LEFT JOIN {menu_router} m ON m.path = ml.router_path WHERE ml.mlid = :mlid", array( diff --git a/modules/book/book.pages.inc b/modules/book/book.pages.inc index 63a1d15a4..e5a04c5a2 100644 --- a/modules/book/book.pages.inc +++ b/modules/book/book.pages.inc @@ -7,6 +7,11 @@ /** * Menu callback: Prints a listing of all books. + * + * @return string + * A HTML-formatted string with the listing of all books content. + * + * @see book_menu() */ function book_render() { $book_list = array(); @@ -36,6 +41,8 @@ function book_render() { * @return * A string representing the node and its children in the book hierarchy in a * format determined by the $type parameter. + * + * @see book_menu() */ function book_export($type, $nid) { // Check that the node exists and that the current user has access to it. @@ -100,6 +107,11 @@ function book_export_html($nid) { * * @param $node * The book node for which to show the outline. + * + * @return string + * A HTML-formatted string with the outline form for a single node. + * + * @see book_menu() */ function book_outline($node) { drupal_set_title($node->title); diff --git a/modules/book/book.test b/modules/book/book.test index 2708e3674..81f4524ac 100644 --- a/modules/book/book.test +++ b/modules/book/book.test @@ -5,14 +5,37 @@ * Tests for book.module. */ +/** + * Tests the functionality of the Book module. + */ class BookTestCase extends DrupalWebTestCase { + + /** + * A book node. + * + * @var object + */ protected $book; - // $book_author is a user with permission to create and edit books. + + /** + * A user with permission to create and edit books. + * + * @var object + */ protected $book_author; - // $web_user is a user with permission to view a book - // and access the printer-friendly version. + + /** + * A user with permission to view a book and access printer-friendly version. + * + * @var object + */ protected $web_user; - // $admin_user is a user with permission to create and edit books and to administer blocks. + + /** + * A user with permission to create and edit books and to administer blocks. + * + * @var object + */ protected $admin_user; public static function getInfo() { @@ -36,7 +59,7 @@ class BookTestCase extends DrupalWebTestCase { } /** - * Create a new book with a page hierarchy. + * Creates a new book with a page hierarchy. */ function createBook() { // Create new book. @@ -67,7 +90,7 @@ class BookTestCase extends DrupalWebTestCase { } /** - * Test book functionality through node interfaces. + * Tests book functionality through node interfaces. */ function testBook() { // Create new book. @@ -106,18 +129,20 @@ class BookTestCase extends DrupalWebTestCase { } /** - * Check the outline of sub-pages; previous, up, and next; and printer friendly version. + * Checks the outline of sub-pages; previous, up, and next. + * + * Also checks the printer friendly version of the outline. * * @param $node * Node to check. * @param $nodes * Nodes that should be in outline. * @param $previous - * Previous link node. + * (optional) Previous link node. Defaults to FALSE. * @param $up - * Up link node. + * (optional) Up link node. Defaults to FALSE. * @param $next - * Next link node. + * (optional) Next link node. Defaults to FALSE. * @param $breadcrumb * The nodes that should be displayed in the breadcrumb. */ @@ -129,23 +154,23 @@ class BookTestCase extends DrupalWebTestCase { // Check outline structure. if ($nodes !== NULL) { - $this->assertPattern($this->generateOutlinePattern($nodes), t('Node ' . $number . ' outline confirmed.')); + $this->assertPattern($this->generateOutlinePattern($nodes), format_string('Node %number outline confirmed.', array('%number' => $number))); } else { - $this->pass(t('Node ' . $number . ' doesn\'t have outline.')); + $this->pass(format_string('Node %number does not have outline.', array('%number' => $number))); } // Check previous, up, and next links. if ($previous) { - $this->assertRaw(l('‹ ' . $previous->title, 'node/' . $previous->nid, array('attributes' => array('class' => array('page-previous'), 'title' => t('Go to previous page')))), t('Previous page link found.')); + $this->assertRaw(l('‹ ' . $previous->title, 'node/' . $previous->nid, array('attributes' => array('class' => array('page-previous'), 'title' => t('Go to previous page')))), 'Previous page link found.'); } if ($up) { - $this->assertRaw(l('up', 'node/' . $up->nid, array('attributes' => array('class' => array('page-up'), 'title' => t('Go to parent page')))), t('Up page link found.')); + $this->assertRaw(l('up', 'node/' . $up->nid, array('attributes' => array('class' => array('page-up'), 'title' => t('Go to parent page')))), 'Up page link found.'); } if ($next) { - $this->assertRaw(l($next->title . ' ›', 'node/' . $next->nid, array('attributes' => array('class' => array('page-next'), 'title' => t('Go to next page')))), t('Next page link found.')); + $this->assertRaw(l($next->title . ' ›', 'node/' . $next->nid, array('attributes' => array('class' => array('page-next'), 'title' => t('Go to next page')))), 'Next page link found.'); } // Compute the expected breadcrumb. @@ -163,20 +188,24 @@ class BookTestCase extends DrupalWebTestCase { } // Compare expected and got breadcrumbs. - $this->assertIdentical($expected_breadcrumb, $got_breadcrumb, t('The breadcrumb is correctly displayed on the page.')); + $this->assertIdentical($expected_breadcrumb, $got_breadcrumb, 'The breadcrumb is correctly displayed on the page.'); // Check printer friendly version. $this->drupalGet('book/export/html/' . $node->nid); - $this->assertText($node->title, t('Printer friendly title found.')); - $this->assertRaw(check_markup($node->body[LANGUAGE_NONE][0]['value'], $node->body[LANGUAGE_NONE][0]['format']), t('Printer friendly body found.')); + $this->assertText($node->title, 'Printer friendly title found.'); + $this->assertRaw(check_markup($node->body[LANGUAGE_NONE][0]['value'], $node->body[LANGUAGE_NONE][0]['format']), 'Printer friendly body found.'); $number++; } /** - * Create a regular expression to check for the sub-nodes in the outline. + * Creates a regular expression to check for the sub-nodes in the outline. + * + * @param array $nodes + * An array of nodes to check in outline. * - * @param array $nodes Nodes to check in outline. + * @return + * A regular expression that locates sub-nodes of the outline. */ function generateOutlinePattern($nodes) { $outline = ''; @@ -188,10 +217,12 @@ class BookTestCase extends DrupalWebTestCase { } /** - * Create book node. + * Creates a book node. * - * @param integer $book_nid Book node id or set to 'new' to create new book. - * @param integer $parent Parent book reference id. + * @param $book_nid + * A book node ID or set to 'new' to create a new book. + * @param $parent + * (optional) Parent book reference ID. Defaults to NULL. */ function createBookNode($book_nid, $parent = NULL) { // $number does not use drupal_static as it should not be reset @@ -216,7 +247,7 @@ class BookTestCase extends DrupalWebTestCase { // Check to make sure the book node was created. $node = $this->drupalGetNodeByTitle($edit['title']); - $this->assertNotNull(($node === FALSE ? NULL : $node), t('Book node found in database.')); + $this->assertNotNull(($node === FALSE ? NULL : $node), 'Book node found in database.'); $number++; return $node; @@ -236,28 +267,28 @@ class BookTestCase extends DrupalWebTestCase { // Make sure each part of the book is there. foreach ($nodes as $node) { - $this->assertText($node->title, t('Node title found in printer friendly version.')); - $this->assertRaw(check_markup($node->body[LANGUAGE_NONE][0]['value'], $node->body[LANGUAGE_NONE][0]['format']), t('Node body found in printer friendly version.')); + $this->assertText($node->title, 'Node title found in printer friendly version.'); + $this->assertRaw(check_markup($node->body[LANGUAGE_NONE][0]['value'], $node->body[LANGUAGE_NONE][0]['format']), 'Node body found in printer friendly version.'); } // Make sure we can't export an unsupported format. $this->drupalGet('book/export/foobar/' . $this->book->nid); - $this->assertResponse('404', t('Unsupported export format returned "not found".')); + $this->assertResponse('404', 'Unsupported export format returned "not found".'); // Make sure we get a 404 on a not existing book node. $this->drupalGet('book/export/html/123'); - $this->assertResponse('404', t('Not existing book node returned "not found".')); + $this->assertResponse('404', 'Not existing book node returned "not found".'); // Make sure an anonymous user cannot view printer-friendly version. $this->drupalLogout(); // Load the book and verify there is no printer-friendly version link. $this->drupalGet('node/' . $this->book->nid); - $this->assertNoLink(t('Printer-friendly version'), t('Anonymous user is not shown link to printer-friendly version.')); + $this->assertNoLink(t('Printer-friendly version'), 'Anonymous user is not shown link to printer-friendly version.'); // Try getting the URL directly, and verify it fails. $this->drupalGet('book/export/html/' . $this->book->nid); - $this->assertResponse('403', t('Anonymous user properly forbidden.')); + $this->assertResponse('403', 'Anonymous user properly forbidden.'); // Now grant anonymous users permission to view the printer-friendly // version and verify that node access restrictions still prevent them from @@ -276,30 +307,30 @@ class BookTestCase extends DrupalWebTestCase { // Set block title to confirm that the interface is available. $block_title = $this->randomName(16); $this->drupalPost('admin/structure/block/manage/book/navigation/configure', array('title' => $block_title), t('Save block')); - $this->assertText(t('The block configuration has been saved.'), t('Block configuration set.')); + $this->assertText(t('The block configuration has been saved.'), 'Block configuration set.'); // Set the block to a region to confirm block is available. $edit = array(); $edit['blocks[book_navigation][region]'] = 'footer'; $this->drupalPost('admin/structure/block', $edit, t('Save blocks')); - $this->assertText(t('The block settings have been updated.'), t('Block successfully move to footer region.')); + $this->assertText(t('The block settings have been updated.'), 'Block successfully move to footer region.'); // Give anonymous users the permission 'node test view'. $edit = array(); $edit[DRUPAL_ANONYMOUS_RID . '[node test view]'] = TRUE; $this->drupalPost('admin/people/permissions/' . DRUPAL_ANONYMOUS_RID, $edit, t('Save permissions')); - $this->assertText(t('The changes have been saved.'), t("Permission 'node test view' successfully assigned to anonymous users.")); + $this->assertText(t('The changes have been saved.'), "Permission 'node test view' successfully assigned to anonymous users."); // Test correct display of the block. $nodes = $this->createBook(); $this->drupalGet('<front>'); - $this->assertText($block_title, t('Book navigation block is displayed.')); - $this->assertText($this->book->title, t('Link to book root (@title) is displayed.', array('@title' => $nodes[0]->title))); - $this->assertNoText($nodes[0]->title, t('No links to individual book pages are displayed.')); + $this->assertText($block_title, 'Book navigation block is displayed.'); + $this->assertText($this->book->title, format_string('Link to book root (@title) is displayed.', array('@title' => $nodes[0]->title))); + $this->assertNoText($nodes[0]->title, 'No links to individual book pages are displayed.'); } /** - * Test the book navigation block when an access module is enabled. + * Tests the book navigation block when an access module is enabled. */ function testNavigationBlockOnAccessModuleEnabled() { $this->drupalLogin($this->admin_user); @@ -312,19 +343,19 @@ class BookTestCase extends DrupalWebTestCase { // Set block display to 'Show block only on book pages'. $edit['book_block_mode'] = 'book pages'; $this->drupalPost('admin/structure/block/manage/book/navigation/configure', $edit, t('Save block')); - $this->assertText(t('The block configuration has been saved.'), t('Block configuration set.')); + $this->assertText(t('The block configuration has been saved.'), 'Block configuration set.'); // Set the block to a region to confirm block is available. $edit = array(); $edit['blocks[book_navigation][region]'] = 'footer'; $this->drupalPost('admin/structure/block', $edit, t('Save blocks')); - $this->assertText(t('The block settings have been updated.'), t('Block successfully move to footer region.')); + $this->assertText(t('The block settings have been updated.'), 'Block successfully move to footer region.'); // Give anonymous users the permission 'node test view'. $edit = array(); $edit[DRUPAL_ANONYMOUS_RID . '[node test view]'] = TRUE; $this->drupalPost('admin/people/permissions/' . DRUPAL_ANONYMOUS_RID, $edit, t('Save permissions')); - $this->assertText(t('The changes have been saved.'), t('Permission \'node test view\' successfully assigned to anonymous users.')); + $this->assertText(t('The changes have been saved.'), "Permission 'node test view' successfully assigned to anonymous users."); // Create a book. $this->createBook(); @@ -332,12 +363,12 @@ class BookTestCase extends DrupalWebTestCase { // Test correct display of the block to registered users. $this->drupalLogin($this->web_user); $this->drupalGet('node/' . $this->book->nid); - $this->assertText($block_title, t('Book navigation block is displayed to registered users.')); + $this->assertText($block_title, 'Book navigation block is displayed to registered users.'); $this->drupalLogout(); // Test correct display of the block to anonymous users. $this->drupalGet('node/' . $this->book->nid); - $this->assertText($block_title, t('Book navigation block is displayed to anonymous users.')); + $this->assertText($block_title, 'Book navigation block is displayed to anonymous users.'); } /** @@ -350,10 +381,10 @@ class BookTestCase extends DrupalWebTestCase { // Test access to delete top-level and child book nodes. $this->drupalGet('node/' . $this->book->nid . '/outline/remove'); - $this->assertResponse('403', t('Deleting top-level book node properly forbidden.')); + $this->assertResponse('403', 'Deleting top-level book node properly forbidden.'); $this->drupalPost('node/' . $nodes[4]->nid . '/outline/remove', $edit, t('Remove')); $node4 = node_load($nodes[4]->nid, NULL, TRUE); - $this->assertTrue(empty($node4->book), t('Deleting child book node properly allowed.')); + $this->assertTrue(empty($node4->book), 'Deleting child book node properly allowed.'); // Delete all child book nodes and retest top-level node deletion. foreach ($nodes as $node) { @@ -362,6 +393,6 @@ class BookTestCase extends DrupalWebTestCase { node_delete_multiple($nids); $this->drupalPost('node/' . $this->book->nid . '/outline/remove', $edit, t('Remove')); $node = node_load($this->book->nid, NULL, TRUE); - $this->assertTrue(empty($node->book), t('Deleting childless top-level book node properly allowed.')); + $this->assertTrue(empty($node->book), 'Deleting childless top-level book node properly allowed.'); } } |