3 namespace Drupal\Core\Menu;
6 * Defines an interface for loading, transforming and rendering menu link trees.
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().
26 interface MenuLinkTreeInterface {
29 * Gets the link tree parameters for rendering a specific menu.
31 * Builds menu link tree parameters that:
32 * - Expand all links in the active trail based on route being viewed.
33 * - Expand the descendents of the links in the active trail whose
34 * 'expanded' flag is enabled.
36 * This only sets the (relatively complex) parameters to achieve the two above
37 * goals, but you can still further customize these parameters.
39 * @param string $menu_name
40 * The menu name, needed for retrieving the active trail and links with the
41 * 'expanded' flag enabled.
43 * @return \Drupal\Core\Menu\MenuTreeParameters
44 * The parameters to determine which menu links to be loaded into a tree.
46 * @see \Drupal\Core\Menu\MenuTreeParameters
48 public function getCurrentRouteMenuTreeParameters($menu_name);
51 * Loads a menu tree with a menu link plugin instance at each element.
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.
58 * @return \Drupal\Core\Menu\MenuLinkTreeElement[]
61 public function load($menu_name, MenuTreeParameters $parameters);
64 * Applies menu link tree manipulators to transform the given tree.
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.
74 * @return \Drupal\Core\Menu\MenuLinkTreeElement[]
75 * The manipulated menu link tree.
77 public function transform(array $tree, array $manipulators);
80 * Builds a renderable array from a menu tree.
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.
87 * @param \Drupal\Core\Menu\MenuLinkTreeElement[] $tree
88 * A data structure representing the tree, as returned from
89 * MenuLinkTreeInterface::load().
94 public function build(array $tree);
97 * Returns the maximum depth of tree that is supported.
102 public function maxDepth();
105 * Finds the height of a subtree rooted by of the given ID.
108 * The ID of an item in the storage.
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.
114 public function getSubtreeHeight($id);
117 * Finds expanded links in a menu given a set of possible parents.
119 * @param string $menu_name
121 * @param array $parents
122 * One or more parent IDs to match.
125 * The menu link IDs that are flagged as expanded in this menu.
127 public function getExpanded($menu_name, array $parents);