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 }
|