Chris@0
|
1 <?php
|
Chris@0
|
2
|
Chris@0
|
3 namespace Drupal\Core\Menu;
|
Chris@0
|
4
|
Chris@0
|
5 use Drupal\Component\Plugin\PluginManagerInterface;
|
Chris@0
|
6
|
Chris@0
|
7 /**
|
Chris@0
|
8 * Defines an interface for managing menu links and storing their definitions.
|
Chris@0
|
9 *
|
Chris@0
|
10 * Menu link managers support both automatic plugin definition discovery and
|
Chris@0
|
11 * manually maintaining plugin definitions.
|
Chris@0
|
12 *
|
Chris@0
|
13 * MenuLinkManagerInterface::updateDefinition() can be used to update a single
|
Chris@0
|
14 * menu link's definition and pass this onto the menu storage without requiring
|
Chris@0
|
15 * a full MenuLinkManagerInterface::rebuild().
|
Chris@0
|
16 *
|
Chris@0
|
17 * Implementations that do not use automatic discovery should call
|
Chris@0
|
18 * MenuLinkManagerInterface::addDefinition() or
|
Chris@0
|
19 * MenuLinkManagerInterface::removeDefinition() when they add or remove links,
|
Chris@0
|
20 * and MenuLinkManagerInterface::updateDefinition() to update links they have
|
Chris@0
|
21 * already defined.
|
Chris@0
|
22 */
|
Chris@0
|
23 interface MenuLinkManagerInterface extends PluginManagerInterface {
|
Chris@0
|
24
|
Chris@0
|
25 /**
|
Chris@0
|
26 * Triggers discovery, save, and cleanup of discovered links.
|
Chris@0
|
27 */
|
Chris@0
|
28 public function rebuild();
|
Chris@0
|
29
|
Chris@0
|
30 /**
|
Chris@0
|
31 * Deletes all links having a certain menu name.
|
Chris@0
|
32 *
|
Chris@0
|
33 * If a link is not deletable but is resettable, the link will be reset to have
|
Chris@0
|
34 * its original menu name, under the assumption that the original menu is not
|
Chris@0
|
35 * the one we are deleting it from. Note that when resetting, if the original
|
Chris@0
|
36 * menu name is the same as the menu name passed to this method, the link will
|
Chris@0
|
37 * not be moved or deleted.
|
Chris@0
|
38 *
|
Chris@0
|
39 * @param string $menu_name
|
Chris@0
|
40 * The name of the menu whose links will be deleted or reset.
|
Chris@0
|
41 */
|
Chris@0
|
42 public function deleteLinksInMenu($menu_name);
|
Chris@0
|
43
|
Chris@0
|
44 /**
|
Chris@0
|
45 * Removes a single link definition from the menu tree storage.
|
Chris@0
|
46 *
|
Chris@0
|
47 * This is used for plugins not found through discovery to remove definitions.
|
Chris@0
|
48 *
|
Chris@0
|
49 * @param string $id
|
Chris@0
|
50 * The menu link plugin ID.
|
Chris@0
|
51 * @param bool $persist
|
Chris@0
|
52 * If TRUE, this method will attempt to persist the deletion from any
|
Chris@0
|
53 * external storage by invoking MenuLinkInterface::deleteLink() on the
|
Chris@0
|
54 * plugin that is being deleted.
|
Chris@0
|
55 *
|
Chris@0
|
56 * @throws \Drupal\Component\Plugin\Exception\PluginException
|
Chris@0
|
57 * Thrown if the $id is not a valid, existing, plugin ID or if the link
|
Chris@0
|
58 * cannot be deleted.
|
Chris@0
|
59 */
|
Chris@0
|
60 public function removeDefinition($id, $persist = TRUE);
|
Chris@0
|
61
|
Chris@0
|
62 /**
|
Chris@0
|
63 * Loads multiple plugin instances based on route.
|
Chris@0
|
64 *
|
Chris@0
|
65 * @param string $route_name
|
Chris@0
|
66 * The route name.
|
Chris@0
|
67 * @param array $route_parameters
|
Chris@0
|
68 * (optional) The route parameters. Defaults to an empty array.
|
Chris@0
|
69 * @param string $menu_name
|
Chris@0
|
70 * (optional) Restricts the found links to just those in the named menu.
|
Chris@0
|
71 *
|
Chris@0
|
72 * @return \Drupal\Core\Menu\MenuLinkInterface[]
|
Chris@0
|
73 * An array of instances keyed by plugin ID.
|
Chris@0
|
74 */
|
Chris@0
|
75 public function loadLinksByRoute($route_name, array $route_parameters = [], $menu_name = NULL);
|
Chris@0
|
76
|
Chris@0
|
77 /**
|
Chris@0
|
78 * Adds a new menu link definition to the menu tree storage.
|
Chris@0
|
79 *
|
Chris@0
|
80 * Use this function when you know there is no entry in the tree. This is
|
Chris@0
|
81 * used for plugins not found through discovery to add new definitions.
|
Chris@0
|
82 *
|
Chris@0
|
83 * @param string $id
|
Chris@0
|
84 * The plugin ID for the new menu link definition that is being added.
|
Chris@0
|
85 * @param array $definition
|
Chris@0
|
86 * The values of the link definition.
|
Chris@0
|
87 *
|
Chris@0
|
88 * @return \Drupal\Core\Menu\MenuLinkInterface
|
Chris@0
|
89 * A plugin instance created using the newly added definition.
|
Chris@0
|
90 *
|
Chris@0
|
91 * @throws \Drupal\Component\Plugin\Exception\PluginException
|
Chris@0
|
92 * Thrown when the $id is not valid or is an already existing plugin ID.
|
Chris@0
|
93 */
|
Chris@0
|
94 public function addDefinition($id, array $definition);
|
Chris@0
|
95
|
Chris@0
|
96 /**
|
Chris@0
|
97 * Updates the values for a menu link definition in the menu tree storage.
|
Chris@0
|
98 *
|
Chris@0
|
99 * This will update the definition for a discovered menu link without the
|
Chris@0
|
100 * need for a full rebuild. It is also used for plugins not found through
|
Chris@0
|
101 * discovery to update definitions.
|
Chris@0
|
102 *
|
Chris@0
|
103 * @param string $id
|
Chris@0
|
104 * The menu link plugin ID.
|
Chris@0
|
105 * @param array $new_definition_values
|
Chris@0
|
106 * The new values for the link definition. This will usually be just a
|
Chris@0
|
107 * subset of the plugin definition.
|
Chris@0
|
108 * @param bool $persist
|
Chris@0
|
109 * TRUE to also have the link instance itself persist the changed values to
|
Chris@0
|
110 * any additional storage by invoking MenuLinkInterface::updateDefinition()
|
Chris@0
|
111 * on the plugin that is being updated.
|
Chris@0
|
112 *
|
Chris@0
|
113 * @return \Drupal\Core\Menu\MenuLinkInterface
|
Chris@0
|
114 * A plugin instance created using the updated definition.
|
Chris@0
|
115 *
|
Chris@0
|
116 * @throws \Drupal\Component\Plugin\Exception\PluginException
|
Chris@0
|
117 * Thrown if the $id is not a valid, existing, plugin ID.
|
Chris@0
|
118 */
|
Chris@0
|
119 public function updateDefinition($id, array $new_definition_values, $persist = TRUE);
|
Chris@0
|
120
|
Chris@0
|
121 /**
|
Chris@0
|
122 * Resets the values for a menu link based on the values found by discovery.
|
Chris@0
|
123 *
|
Chris@0
|
124 * @param string $id
|
Chris@0
|
125 * The menu link plugin ID.
|
Chris@0
|
126 *
|
Chris@0
|
127 * @return \Drupal\Core\Menu\MenuLinkInterface
|
Chris@0
|
128 * The menu link instance after being reset.
|
Chris@0
|
129 *
|
Chris@0
|
130 * @throws \Drupal\Component\Plugin\Exception\PluginException
|
Chris@0
|
131 * Thrown if the $id is not a valid, existing, plugin ID or if the link
|
Chris@0
|
132 * cannot be reset.
|
Chris@0
|
133 */
|
Chris@0
|
134 public function resetLink($id);
|
Chris@0
|
135
|
Chris@0
|
136 /**
|
Chris@0
|
137 * Counts the total number of menu links.
|
Chris@0
|
138 *
|
Chris@0
|
139 * @param string $menu_name
|
Chris@0
|
140 * (optional) The menu name to count by. Defaults to all menus.
|
Chris@0
|
141 *
|
Chris@0
|
142 * @return int
|
Chris@0
|
143 * The number of menu links in the named menu, or in all menus if the
|
Chris@0
|
144 * menu name is NULL.
|
Chris@0
|
145 */
|
Chris@0
|
146 public function countMenuLinks($menu_name = NULL);
|
Chris@0
|
147
|
Chris@0
|
148 /**
|
Chris@0
|
149 * Loads all parent link IDs of a given menu link.
|
Chris@0
|
150 *
|
Chris@0
|
151 * This method is very similar to getActiveTrailIds() but allows the link to
|
Chris@0
|
152 * be specified rather than being discovered based on the menu name and
|
Chris@0
|
153 * request. This method is mostly useful for testing.
|
Chris@0
|
154 *
|
Chris@0
|
155 * @param string $id
|
Chris@0
|
156 * The menu link plugin ID.
|
Chris@0
|
157 *
|
Chris@0
|
158 * @return array
|
Chris@0
|
159 * An ordered array of IDs representing the path to the root of the tree.
|
Chris@0
|
160 * The first element of the array will be equal to $id, unless $id is not
|
Chris@0
|
161 * valid, in which case the return value will be NULL.
|
Chris@0
|
162 */
|
Chris@0
|
163 public function getParentIds($id);
|
Chris@0
|
164
|
Chris@0
|
165 /**
|
Chris@0
|
166 * Loads all child link IDs of a given menu link, regardless of visibility.
|
Chris@0
|
167 *
|
Chris@0
|
168 * This method is mostly useful for testing.
|
Chris@0
|
169 *
|
Chris@0
|
170 * @param string $id
|
Chris@0
|
171 * The menu link plugin ID.
|
Chris@0
|
172 *
|
Chris@0
|
173 * @return array
|
Chris@0
|
174 * An unordered array of IDs representing the IDs of all children, or NULL
|
Chris@0
|
175 * if the ID is invalid.
|
Chris@0
|
176 */
|
Chris@0
|
177 public function getChildIds($id);
|
Chris@0
|
178
|
Chris@0
|
179 /**
|
Chris@0
|
180 * Determines if any links use a given menu name.
|
Chris@0
|
181 *
|
Chris@0
|
182 * @param string $menu_name
|
Chris@0
|
183 * The menu name.
|
Chris@0
|
184 *
|
Chris@0
|
185 * @return bool
|
Chris@0
|
186 * TRUE if any links are present in the named menu, FALSE otherwise.
|
Chris@0
|
187 */
|
Chris@0
|
188 public function menuNameInUse($menu_name);
|
Chris@0
|
189
|
Chris@0
|
190 /**
|
Chris@0
|
191 * Resets any local definition cache. Used for testing.
|
Chris@0
|
192 */
|
Chris@0
|
193 public function resetDefinitions();
|
Chris@0
|
194
|
Chris@0
|
195 }
|