www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/book/src/BookManagerInterface.php

   1 <?php
   2
   3 namespace Drupal\book;
   4
   5 use Drupal\Core\Form\FormStateInterface;
   6 use Drupal\Core\Session\AccountInterface;
   7 use Drupal\node\NodeInterface;
   8
   9
  10 /**
  11  * Provides an interface defining a book manager.
  12  */
  13 interface BookManagerInterface {
  14
  15   /**
  16    * Gets the data structure representing a named menu tree.
  17    *
  18    * Since this can be the full tree including hidden items, the data returned
  19    * may be used for generating an an admin interface or a select.
  20    *
  21    * Note: based on menu_tree_all_data().
  22    *
  23    * @param int $bid
  24    *   The Book ID to find links for.
  25    * @param array|null $link
  26    *   (optional) A fully loaded menu link, or NULL. If a link is supplied, only
  27    *   the path to root will be included in the returned tree - as if this link
  28    *   represented the current page in a visible menu.
  29    * @param int|null $max_depth
  30    *   (optional) Maximum depth of links to retrieve. Typically useful if only
  31    *   one or two levels of a sub tree are needed in conjunction with a non-NULL
  32    *   $link, in which case $max_depth should be greater than $link['depth'].
  33    *
  34    * @return array
  35    *   An tree of menu links in an array, in the order they should be rendered.
  36    */
  37   public function bookTreeAllData($bid, $link = NULL, $max_depth = NULL);
  38
  39   /**
  40    * Gets the active trail IDs for the specified book at the provided path.
  41    *
  42    * @param string $bid
  43    *   The Book ID to find links for.
  44    * @param array $link
  45    *   A fully loaded menu link.
  46    *
  47    * @return array
  48    *   An array containing the active trail: a list of mlids.
  49    */
  50   public function getActiveTrailIds($bid, $link);
  51
  52   /**
  53    * Loads a single book entry.
  54    *
  55    * The entries of a book entry is documented in
  56    * \Drupal\book\BookOutlineStorageInterface::loadMultiple.
  57    *
  58    * If $translate is TRUE, it also checks access ('access' key) and
  59    * loads the title from the node itself.
  60    *
  61    * @param int $nid
  62    *   The node ID of the book.
  63    * @param bool $translate
  64    *   If TRUE, set access, title, and other elements.
  65    *
  66    * @return array
  67    *   The book data of that node.
  68    *
  69    * @see \Drupal\book\BookOutlineStorageInterface::loadMultiple
  70    */
  71   public function loadBookLink($nid, $translate = TRUE);
  72
  73   /**
  74    * Loads multiple book entries.
  75    *
  76    * The entries of a book entry is documented in
  77    * \Drupal\book\BookOutlineStorageInterface::loadMultiple.
  78    *
  79    * If $translate is TRUE, it also checks access ('access' key) and
  80    * loads the title from the node itself.
  81    *
  82    * @param int[] $nids
  83    *   An array of nids to load.
  84    * @param bool $translate
  85    *   If TRUE, set access, title, and other elements.
  86    *
  87    * @return array[]
  88    *   The book data of each node keyed by NID.
  89    *
  90    * @see \Drupal\book\BookOutlineStorageInterface::loadMultiple
  91    */
  92   public function loadBookLinks($nids, $translate = TRUE);
  93
  94   /**
  95    * Returns an array of book pages in table of contents order.
  96    *
  97    * @param int $bid
  98    *   The ID of the book whose pages are to be listed.
  99    * @param int $depth_limit
 100    *   Any link deeper than this value will be excluded (along with its
 101    *   children).
 102    * @param array $exclude
 103    *   (optional) An array of menu link ID values. Any link whose menu link ID
 104    *   is in this array will be excluded (along with its children). Defaults to
 105    *   an empty array.
 106    *
 107    * @return array
 108    *   An array of (menu link ID, title) pairs for use as options for selecting
 109    *   a book page.
 110    */
 111   public function getTableOfContents($bid, $depth_limit, array $exclude = []);
 112
 113   /**
 114    * Finds the depth limit for items in the parent select.
 115    *
 116    * @param array $book_link
 117    *   A fully loaded menu link that is part of the book hierarchy.
 118    *
 119    * @return int
 120    *   The depth limit for items in the parent select.
 121    */
 122   public function getParentDepthLimit(array $book_link);
 123
 124   /**
 125    * Collects node links from a given menu tree recursively.
 126    *
 127    * @param array $tree
 128    *   The menu tree you wish to collect node links from.
 129    * @param array $node_links
 130    *   An array in which to store the collected node links.
 131    */
 132   public function bookTreeCollectNodeLinks(&$tree, &$node_links);
 133
 134   /**
 135    * Provides book loading, access control and translation.
 136    *
 137    * Note: copied from _menu_link_translate() in menu.inc, but reduced to the
 138    * minimal code that's used.
 139    *
 140    * @param array $link
 141    *   A book link.
 142    */
 143   public function bookLinkTranslate(&$link);
 144
 145   /**
 146    * Gets the book for a page and returns it as a linear array.
 147    *
 148    * @param array $book_link
 149    *   A fully loaded book link that is part of the book hierarchy.
 150    *
 151    * @return array
 152    *   A linear array of book links in the order that the links are shown in the
 153    *   book, so the previous and next pages are the elements before and after the
 154    *   element corresponding to the current node. The children of the current node
 155    *   (if any) will come immediately after it in the array, and links will only
 156    *   be fetched as deep as one level deeper than $book_link.
 157    */
 158   public function bookTreeGetFlat(array $book_link);
 159
 160   /**
 161    * Returns an array of all books.
 162    *
 163    * This list may be used for generating a list of all the books, or for
 164    * building the options for a form select.
 165    *
 166    * @return array
 167    *   An array of all books.
 168    */
 169   public function getAllBooks();
 170
 171   /**
 172    * Handles additions and updates to the book outline.
 173    *
 174    * This common helper function performs all additions and updates to the book
 175    * outline through node addition, node editing, node deletion, or the outline
 176    * tab.
 177    *
 178    * @param \Drupal\node\NodeInterface $node
 179    *   The node that is being saved, added, deleted, or moved.
 180    *
 181    * @return bool
 182    *   TRUE if the book link was saved; FALSE otherwise.
 183    */
 184   public function updateOutline(NodeInterface $node);
 185
 186   /**
 187    * Saves a single book entry.
 188    *
 189    * @param array $link
 190    *   The link data to save.
 191    * @param bool $new
 192    *   Is this a new book.
 193    *
 194    * @return array
 195    *   The book data of that node.
 196    */
 197   public function saveBookLink(array $link, $new);
 198
 199   /**
 200    * Returns an array with default values for a book page's menu link.
 201    *
 202    * @param string|int $nid
 203    *   The ID of the node whose menu link is being created.
 204    *
 205    * @return array
 206    *   The default values for the menu link.
 207    */
 208   public function getLinkDefaults($nid);
 209
 210   public function getBookParents(array $item, array $parent = []);
 211
 212   /**
 213    * Builds the common elements of the book form for the node and outline forms.
 214    *
 215    * @param array $form
 216    *   An associative array containing the structure of the form.
 217    * @param \Drupal\Core\Form\FormStateInterface $form_state
 218    *   The current state of the form.
 219    * @param \Drupal\node\NodeInterface $node
 220    *   The node whose form is being viewed.
 221    * @param \Drupal\Core\Session\AccountInterface $account
 222    *   The account viewing the form.
 223    * @param bool $collapsed
 224    *   If TRUE, the fieldset starts out collapsed.
 225    *
 226    * @return array
 227    *   The form structure, with the book elements added.
 228    */
 229   public function addFormElements(array $form, FormStateInterface $form_state, NodeInterface $node, AccountInterface $account, $collapsed = TRUE);
 230
 231   /**
 232    * Deletes node's entry from book table.
 233    *
 234    * @param int $nid
 235    *   The nid to delete.
 236    */
 237   public function deleteFromBook($nid);
 238
 239   /**
 240    * Returns a rendered menu tree.
 241    *
 242    * The menu item's LI element is given one of the following classes:
 243    * - expanded: The menu item is showing its submenu.
 244    * - collapsed: The menu item has a submenu which is not shown.
 245    *
 246    * @param array $tree
 247    *   A data structure representing the tree as returned from buildBookOutlineData.
 248    *
 249    * @return array
 250    *   A structured array to be rendered by drupal_render().
 251    *
 252    * @see \Drupal\Core\Menu\MenuLinkTree::build
 253    */
 254   public function bookTreeOutput(array $tree);
 255
 256   /**
 257    * Checks access and performs dynamic operations for each link in the tree.
 258    *
 259    * @param array $tree
 260    *   The book tree you wish to operate on.
 261    * @param array $node_links
 262    *   A collection of node link references generated from $tree by
 263    *   menu_tree_collect_node_links().
 264    */
 265   public function bookTreeCheckAccess(&$tree, $node_links = []);
 266
 267   /**
 268    * Gets the data representing a subtree of the book hierarchy.
 269    *
 270    * The root of the subtree will be the link passed as a parameter, so the
 271    * returned tree will contain this item and all its descendants in the menu
 272    * tree.
 273    *
 274    * @param array $link
 275    *   A fully loaded book link.
 276    *
 277    * @return
 278    *   A subtree of book links in an array, in the order they should be rendered.
 279    */
 280   public function bookSubtreeData($link);
 281
 282   /**
 283    * Determines if a node can be removed from the book.
 284    *
 285    * A node can be removed from a book if it is actually in a book and it either
 286    * is not a top-level page or is a top-level page with no children.
 287    *
 288    * @param \Drupal\node\NodeInterface $node
 289    *   The node to remove from the outline.
 290    *
 291    * @return bool
 292    *   TRUE if a node can be removed from the book, FALSE otherwise.
 293    */
 294   public function checkNodeIsRemovable(NodeInterface $node);
 295
 296 }