Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
<?php
/**
* @file
* Contains \Drupal\Core\Menu\MenuTreeStorageInterface.
*/
namespace Drupal\Core\Menu;
/**
* Defines an interface for storing a menu tree containing menu link IDs.
*
* The tree contains a hierarchy of menu links which have an ID as well as a
* route name or external URL.
*/
interface MenuTreeStorageInterface {
/**
* The maximum depth of tree the storage implementation supports.
*
* @return int
* The maximum depth.
*/
public function maxDepth();
/**
* Clears all definitions cached in memory.
*/
public function resetDefinitions();
/**
* Rebuilds the stored menu link definitions.
*
* Links that saved by passing definitions into this method must be included
* on all future calls, or they will be purged. This allows for automatic
* cleanup e.g. when modules are uninstalled.
*
* @param array $definitions
* The new menu link definitions.
*
*/
public function rebuild(array $definitions);
/**
* Loads a menu link plugin definition from the storage.
*
* @param string $id
* The menu link plugin ID.
*
* @return array|FALSE
* The plugin definition, or FALSE if no definition was found for the ID.
*/
public function load($id);
/**
* Loads multiple plugin definitions from the storage.
*
* @param array $ids
* An array of plugin IDs.
*
* @return array
* An array of plugin definition arrays keyed by plugin ID, which are the
* actual definitions after the loadMultiple() including all those plugins
* from $ids.
*/
public function loadMultiple(array $ids);
/**
* Loads multiple plugin definitions from the storage based on properties.
*
* @param array $properties
* The properties to filter by.
*
Alex Pott
committed
* @throws \InvalidArgumentException
* Thrown if an invalid property name is specified in $properties.
*
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
* @return array
* An array of menu link definition arrays.
*/
public function loadByProperties(array $properties);
/**
* Loads multiple plugin definitions from the storage based on route.
*
* @param string $route_name
* The route name.
* @param array $route_parameters
* (optional) The route parameters. Defaults to an empty array.
* @param string $menu_name
* (optional) Restricts the found links to just those in the named menu.
*
* @return array
* An array of menu link definitions keyed by ID and ordered by depth.
*/
public function loadByRoute($route_name, array $route_parameters = array(), $menu_name = NULL);
/**
* Saves a plugin definition to the storage.
*
* @param array $definition
* A definition for a \Drupal\Core\Menu\MenuLinkInterface plugin.
*
* @return array
* The menu names affected by the save operation. This will be one menu
* name if the link is saved to the sane menu, or two if it is saved to a
* new menu.
*
* @throws \Exception
* Thrown if the storage back-end does not exist and could not be created.
* @throws \Drupal\Component\Plugin\Exception\PluginException
* Thrown if the definition is invalid - for example, if the specified
* parent would cause the links children to be moved to greater than the
* maximum depth.
*/
public function save(array $definition);
/**
* Deletes a menu link definition from the storage.
*
* @param string $id
* The menu link plugin ID.
*/
public function delete($id);
/**
* Loads a menu link tree from the storage.
*
* This function may be used build the data for a menu tree only, for example
* to further massage the data manually before further processing happens.
* MenuLinkTree::checkAccess() needs to be invoked afterwards.
*
* The tree order is maintained using an optimized algorithm, for example by
* storing each parent in an individual field, see
* http://drupal.org/node/141866 for more details. However, any details of the
* storage should not be relied upon since it may be swapped with a different
* implementation.
*
* @param string $menu_name
* The name of the menu.
* @param \Drupal\Core\Menu\MenuTreeParameters $parameters
* The parameters to determine which menu links to be loaded into a tree.
*
* @return array
* An array with 2 elements:
* - tree: A fully built menu tree containing an array.
* @see static::treeDataRecursive()
* - route_names: An array of all route names used in the tree.
*/
public function loadTreeData($menu_name, MenuTreeParameters $parameters);
/**
Alex Pott
committed
* Loads all the enabled menu links that are below the given ID.
*
* The returned links are not ordered, and visible children will be included
Alex Pott
committed
* even if they have parent that is not enabled or ancestor so would not
* normally appear in a rendered tree.
*
* @param string $id
* The parent menu link ID.
* @param int $max_relative_depth
* The maximum relative depth of the children relative to the passed parent.
*
* @return array
Alex Pott
committed
* An array of enabled link definitions, keyed by ID.
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
*/
public function loadAllChildren($id, $max_relative_depth = NULL);
/**
* Loads all the IDs for menu links that are below the given ID.
*
* @param string $id
* The parent menu link ID.
*
* @return array
* An unordered array of plugin IDs corresponding to all children.
*/
public function getAllChildIds($id);
/**
* Loads a subtree rooted by the given ID.
*
* The returned links are structured like those from loadTreeData().
*
* @param string $id
* The menu link plugin ID.
* @param int $max_relative_depth
* (optional) The maximum depth of child menu links relative to the passed
* in. Defaults to NULL, in which case the full subtree will be returned.
*
* @return array
* An array with 2 elements:
* - subtree: A fully built menu tree element or FALSE.
* - route_names: An array of all route names used in the subtree.
*/
public function loadSubtreeData($id, $max_relative_depth = NULL);
/**
* Returns all the IDs that represent the path to the root of the tree.
*
* @param string $id
* A menu link ID.
*
* @return array
* An associative array of IDs with keys equal to values that represents the
* path from the given ID to the root of the tree. If $id is an ID that
* exists, the returned array will at least include it. An empty array is
* returned if the ID does not exist in the storage. An example $id (8) with
* two parents (1, 6) looks like the following:
* @code
* array(
* 'p1' => 1,
* 'p2' => 6,
* 'p3' => 8,
* 'p4' => 0,
* 'p5' => 0,
* 'p6' => 0,
* 'p7' => 0,
* 'p8' => 0,
* 'p9' => 0
* )
* @endcode
*/
public function getRootPathIds($id);
/**
* Finds expanded links in a menu given a set of possible parents.
*
* @param string $menu_name
* The menu name.
* @param array $parents
* One or more parent IDs to match.
*
* @return array
* The menu link IDs that are flagged as expanded in this menu.
*/
public function getExpanded($menu_name, array $parents);
/**
* Finds the height of a subtree rooted by the given ID.
*
* @param string $id
* The ID of an item in the storage.
*
* @return int
* Returns the height of the subtree. This will be at least 1 if the ID
* exists, or 0 if the ID does not exist in the storage.
*/
public function getSubtreeHeight($id);
/**
* Determines whether a specific menu name is used in the tree.
*
* @param string $menu_name
* The menu name.
*
* @return bool
* Returns TRUE if the given menu name is used, otherwise FALSE.
*/
public function menuNameInUse($menu_name);
/**
* Returns the used menu names in the tree storage.
*
* @return array
* The menu names.
*/
public function getMenuNames();
/**
* Counts the total number of menu links in one menu or all menus.
*
* @param string $menu_name
* (optional) The menu name to count by. Defaults to all menus.
*
* @return int
* The number of menu links in the named menu, or in all menus if the menu
* name is NULL.
*/
public function countMenuLinks($menu_name = NULL);
}