annotate core/lib/Drupal/Core/Menu/MenuLinkTreeInterface.php @ 19:fa3358dc1485 tip

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