aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Menu/MenuLinkTreeInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Menu;
   4
   5 /**
   6  * Defines an interface for loading, transforming and rendering menu link trees.
   7  *
   8  * The main purposes of this interface are:
   9  * - Load a list of menu links, given a menu name, using
  10  *   MenuLinkTreeInterface::load(). Loaded menu links are returned as a
  11  *   tree by looking at the links' tree meta-data.
  12  * - Which links are loaded can be specified in the menu link tree parameters
  13  *   that are passed to the load() method. You can build your own set of
  14  *   parameters, or you can start from typical defaults by calling the
  15  *   MenuLinkTreeInterface::getCurrentRouteMenuTreeParameters() method. See
  16  *   \Drupal\Core\Menu\MenuTreeParameters for more on menu tree parameters.
  17  * - Transform a menu link tree, by calling MenuLinkTreeInterface::transform().
  18  *   Examples include access checking, adding custom classes, extracting a
  19  *   subtree depending on the active trail, etc. Note that translation is not
  20  *   a tree transformation, because menu links themselves are responsible
  21  *   for translation. Transformations are performed by "menu link tree
  22  *   manipulators", which are functions or methods; see
  23  *   \Drupal\Core\Menu\DefaultMenuLinkTreeManipulators for examples.
  24  * - Create a render array using MenuLinkTreeInterface::build().
  25  */
  26 interface MenuLinkTreeInterface {
  27
  28   /**
  29    * Gets the link tree parameters for rendering a specific menu.
  30    *
  31    * Builds menu link tree parameters that:
  32    * - Expand all links in the active trail based on route being viewed.
  33    * - Expand the descendants of the links in the active trail whose
  34    *   'expanded' flag is enabled.
  35    *
  36    * This only sets the (relatively complex) parameters to achieve the two above
  37    * goals, but you can still further customize these parameters.
  38    *
  39    * @param string $menu_name
  40    *   The menu name, needed for retrieving the active trail and links with the
  41    *   'expanded' flag enabled.
  42    *
  43    * @return \Drupal\Core\Menu\MenuTreeParameters
  44    *   The parameters to determine which menu links to be loaded into a tree.
  45    *
  46    * @see \Drupal\Core\Menu\MenuTreeParameters
  47    */
  48   public function getCurrentRouteMenuTreeParameters($menu_name);
  49
  50   /**
  51    * Loads a menu tree with a menu link plugin instance at each element.
  52    *
  53    * @param string $menu_name
  54    *   The name of the menu.
  55    * @param \Drupal\Core\Menu\MenuTreeParameters $parameters
  56    *   The parameters to determine which menu links to be loaded into a tree.
  57    *
  58    * @return \Drupal\Core\Menu\MenuLinkTreeElement[]
  59    *   A menu link tree.
  60    */
  61   public function load($menu_name, MenuTreeParameters $parameters);
  62
  63   /**
  64    * Applies menu link tree manipulators to transform the given tree.
  65    *
  66    * @param \Drupal\Core\Menu\MenuLinkTreeElement[] $tree
  67    *   The menu tree to manipulate.
  68    * @param array $manipulators
  69    *   The menu link tree manipulators to apply. Each is an array with keys:
  70    *   - callable: a callable or a string that can be resolved to a callable
  71    *     by \Drupal\Core\Controller\ControllerResolverInterface::getControllerFromDefinition()
  72    *   - args: optional array of arguments to pass to the callable after $tree.
  73    *
  74    * @return \Drupal\Core\Menu\MenuLinkTreeElement[]
  75    *   The manipulated menu link tree.
  76    */
  77   public function transform(array $tree, array $manipulators);
  78
  79   /**
  80    * Builds a renderable array from a menu tree.
  81    *
  82    * The menu item's LI element is given one of the following classes:
  83    * - expanded: The menu item is showing its submenu.
  84    * - collapsed: The menu item has a submenu that is not shown.
  85    * - leaf: The menu item has no submenu.
  86    *
  87    * @param \Drupal\Core\Menu\MenuLinkTreeElement[] $tree
  88    *   A data structure representing the tree, as returned from
  89    *   MenuLinkTreeInterface::load().
  90    *
  91    * @return array
  92    *   A renderable array.
  93    */
  94   public function build(array $tree);
  95
  96   /**
  97    * Returns the maximum depth of tree that is supported.
  98    *
  99    * @return int
 100    *   The maximum depth.
 101    */
 102   public function maxDepth();
 103
 104   /**
 105    * Finds the height of a subtree rooted by of the given ID.
 106    *
 107    * @param string $id
 108    *   The ID of an item in the storage.
 109    *
 110    * @return int
 111    *   Returns the height of the subtree. This will be at least 1 if the ID
 112    *   exists, or 0 if the ID does not exist in the storage.
 113    */
 114   public function getSubtreeHeight($id);
 115
 116   /**
 117    * Finds expanded links in a menu given a set of possible parents.
 118    *
 119    * @param string $menu_name
 120    *   The menu name.
 121    * @param array $parents
 122    *   One or more parent IDs to match.
 123    *
 124    * @return array
 125    *   The menu link IDs that are flagged as expanded in this menu.
 126    */
 127   public function getExpanded($menu_name, array $parents);
 128
 129 }