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