1. 8.2.x core/includes/menu.inc
  2. 8.0.x core/includes/menu.inc
  3. 8.1.x core/includes/menu.inc
  4. 8.3.x core/includes/menu.inc
  5. 4.6.x includes/menu.inc
  6. 4.7.x includes/menu.inc
  7. 5.x includes/menu.inc
  8. 6.x includes/menu.inc
  9. 7.x includes/menu.inc

API for the Drupal menu system.

File

includes/menu.inc
View source
  1. <?php
  2. /**
  3. * @file
  4. * API for the Drupal menu system.
  5. */
  6. /**
  7. * @defgroup menu Menu system
  8. * @{
  9. * Define the navigation menus, and route page requests to code based on URLs.
  10. *
  11. * The Drupal menu system drives both the navigation system from a user
  12. * perspective and the callback system that Drupal uses to respond to URLs
  13. * passed from the browser. For this reason, a good understanding of the
  14. * menu system is fundamental to the creation of complex modules. As a note,
  15. * this is related to, but separate from menu.module, which allows menus
  16. * (which in this context are hierarchical lists of links) to be customized from
  17. * the Drupal administrative interface.
  18. *
  19. * Drupal's menu system follows a simple hierarchy defined by paths.
  20. * Implementations of hook_menu() define menu items and assign them to
  21. * paths (which should be unique). The menu system aggregates these items
  22. * and determines the menu hierarchy from the paths. For example, if the
  23. * paths defined were a, a/b, e, a/b/c/d, f/g, and a/b/h, the menu system
  24. * would form the structure:
  25. * - a
  26. * - a/b
  27. * - a/b/c/d
  28. * - a/b/h
  29. * - e
  30. * - f/g
  31. * Note that the number of elements in the path does not necessarily
  32. * determine the depth of the menu item in the tree.
  33. *
  34. * When responding to a page request, the menu system looks to see if the
  35. * path requested by the browser is registered as a menu item with a
  36. * callback. If not, the system searches up the menu tree for the most
  37. * complete match with a callback it can find. If the path a/b/i is
  38. * requested in the tree above, the callback for a/b would be used.
  39. *
  40. * The found callback function is called with any arguments specified
  41. * in the "page arguments" attribute of its menu item. The
  42. * attribute must be an array. After these arguments, any remaining
  43. * components of the path are appended as further arguments. In this
  44. * way, the callback for a/b above could respond to a request for
  45. * a/b/i differently than a request for a/b/j.
  46. *
  47. * For an illustration of this process, see page_example.module.
  48. *
  49. * Access to the callback functions is also protected by the menu system.
  50. * The "access callback" with an optional "access arguments" of each menu
  51. * item is called before the page callback proceeds. If this returns TRUE,
  52. * then access is granted; if FALSE, then access is denied. Default local task
  53. * menu items (see next paragraph) may omit this attribute to use the value
  54. * provided by the parent item.
  55. *
  56. * In the default Drupal interface, you will notice many links rendered as
  57. * tabs. These are known in the menu system as "local tasks", and they are
  58. * rendered as tabs by default, though other presentations are possible.
  59. * Local tasks function just as other menu items in most respects. It is
  60. * convention that the names of these tasks should be short verbs if
  61. * possible. In addition, a "default" local task should be provided for
  62. * each set. When visiting a local task's parent menu item, the default
  63. * local task will be rendered as if it is selected; this provides for a
  64. * normal tab user experience. This default task is special in that it
  65. * links not to its provided path, but to its parent item's path instead.
  66. * The default task's path is only used to place it appropriately in the
  67. * menu hierarchy.
  68. *
  69. * Everything described so far is stored in the menu_router table. The
  70. * menu_links table holds the visible menu links. By default these are
  71. * derived from the same hook_menu definitions, however you are free to
  72. * add more with menu_link_save().
  73. */
  74. /**
  75. * @defgroup menu_flags Menu flags
  76. * @{
  77. * Flags for use in the "type" attribute of menu items.
  78. */
  79. /**
  80. * Internal menu flag -- menu item is the root of the menu tree.
  81. */
  82. define('MENU_IS_ROOT', 0x0001);
  83. /**
  84. * Internal menu flag -- menu item is visible in the menu tree.
  85. */
  86. define('MENU_VISIBLE_IN_TREE', 0x0002);
  87. /**
  88. * Internal menu flag -- menu item is visible in the breadcrumb.
  89. */
  90. define('MENU_VISIBLE_IN_BREADCRUMB', 0x0004);
  91. /**
  92. * Internal menu flag -- menu item links back to its parent.
  93. */
  94. define('MENU_LINKS_TO_PARENT', 0x0008);
  95. /**
  96. * Internal menu flag -- menu item can be modified by administrator.
  97. */
  98. define('MENU_MODIFIED_BY_ADMIN', 0x0020);
  99. /**
  100. * Internal menu flag -- menu item was created by administrator.
  101. */
  102. define('MENU_CREATED_BY_ADMIN', 0x0040);
  103. /**
  104. * Internal menu flag -- menu item is a local task.
  105. */
  106. define('MENU_IS_LOCAL_TASK', 0x0080);
  107. /**
  108. * Internal menu flag -- menu item is a local action.
  109. */
  110. define('MENU_IS_LOCAL_ACTION', 0x0100);
  111. /**
  112. * @} End of "Menu flags".
  113. */
  114. /**
  115. * @defgroup menu_item_types Menu item types
  116. * @{
  117. * Definitions for various menu item types.
  118. *
  119. * Menu item definitions provide one of these constants, which are shortcuts for
  120. * combinations of @link menu_flags Menu flags @endlink.
  121. */
  122. /**
  123. * Menu type -- A "normal" menu item that's shown in menu and breadcrumbs.
  124. *
  125. * Normal menu items show up in the menu tree and can be moved/hidden by
  126. * the administrator. Use this for most menu items. It is the default value if
  127. * no menu item type is specified.
  128. */
  129. define('MENU_NORMAL_ITEM', MENU_VISIBLE_IN_TREE | MENU_VISIBLE_IN_BREADCRUMB);
  130. /**
  131. * Menu type -- A hidden, internal callback, typically used for API calls.
  132. *
  133. * Callbacks simply register a path so that the correct function is fired
  134. * when the URL is accessed. They do not appear in menus or breadcrumbs.
  135. */
  136. define('MENU_CALLBACK', 0x0000);
  137. /**
  138. * Menu type -- A normal menu item, hidden until enabled by an administrator.
  139. *
  140. * Modules may "suggest" menu items that the administrator may enable. They act
  141. * just as callbacks do until enabled, at which time they act like normal items.
  142. * Note for the value: 0x0010 was a flag which is no longer used, but this way
  143. * the values of MENU_CALLBACK and MENU_SUGGESTED_ITEM are separate.
  144. */
  145. define('MENU_SUGGESTED_ITEM', MENU_VISIBLE_IN_BREADCRUMB | 0x0010);
  146. /**
  147. * Menu type -- A task specific to the parent item, usually rendered as a tab.
  148. *
  149. * Local tasks are menu items that describe actions to be performed on their
  150. * parent item. An example is the path "node/52/edit", which performs the
  151. * "edit" task on "node/52".
  152. */
  153. define('MENU_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_VISIBLE_IN_BREADCRUMB);
  154. /**
  155. * Menu type -- The "default" local task, which is initially active.
  156. *
  157. * Every set of local tasks should provide one "default" task, that links to the
  158. * same path as its parent when clicked.
  159. */
  160. define('MENU_DEFAULT_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_LINKS_TO_PARENT | MENU_VISIBLE_IN_BREADCRUMB);
  161. /**
  162. * Menu type -- An action specific to the parent, usually rendered as a link.
  163. *
  164. * Local actions are menu items that describe actions on the parent item such
  165. * as adding a new user, taxonomy term, etc.
  166. */
  167. define('MENU_LOCAL_ACTION', MENU_IS_LOCAL_TASK | MENU_IS_LOCAL_ACTION | MENU_VISIBLE_IN_BREADCRUMB);
  168. /**
  169. * @} End of "Menu item types".
  170. */
  171. /**
  172. * @defgroup menu_context_types Menu context types
  173. * @{
  174. * Flags for use in the "context" attribute of menu router items.
  175. */
  176. /**
  177. * Internal menu flag: Invisible local task.
  178. *
  179. * This flag may be used for local tasks like "Delete", so custom modules and
  180. * themes can alter the default context and expose the task by altering menu.
  181. */
  182. define('MENU_CONTEXT_NONE', 0x0000);
  183. /**
  184. * Internal menu flag: Local task should be displayed in page context.
  185. */
  186. define('MENU_CONTEXT_PAGE', 0x0001);
  187. /**
  188. * Internal menu flag: Local task should be displayed inline.
  189. */
  190. define('MENU_CONTEXT_INLINE', 0x0002);
  191. /**
  192. * @} End of "Menu context types".
  193. */
  194. /**
  195. * @defgroup menu_status_codes Menu status codes
  196. * @{
  197. * Status codes for menu callbacks.
  198. */
  199. /**
  200. * Internal menu status code -- Menu item was found.
  201. */
  202. define('MENU_FOUND', 1);
  203. /**
  204. * Menu status code -- Not found.
  205. *
  206. * This can be used as the return value from a page callback, although it is
  207. * preferable to use a load function to accomplish this; see the hook_menu()
  208. * documentation for details.
  209. */
  210. define('MENU_NOT_FOUND', 2);
  211. /**
  212. * Menu status code -- Access denied.
  213. *
  214. * This can be used as the return value from a page callback, although it is
  215. * preferable to use an access callback to accomplish this; see the hook_menu()
  216. * documentation for details.
  217. */
  218. define('MENU_ACCESS_DENIED', 3);
  219. /**
  220. * Internal menu status code -- Menu item inaccessible because site is offline.
  221. */
  222. define('MENU_SITE_OFFLINE', 4);
  223. /**
  224. * Internal menu status code -- Everything is working fine.
  225. */
  226. define('MENU_SITE_ONLINE', 5);
  227. /**
  228. * @} End of "Menu status codes".
  229. */
  230. /**
  231. * @defgroup menu_tree_parameters Menu tree parameters
  232. * @{
  233. * Parameters for a menu tree.
  234. */
  235. /**
  236. * The maximum number of path elements for a menu callback
  237. */
  238. define('MENU_MAX_PARTS', 9);
  239. /**
  240. * The maximum depth of a menu links tree - matches the number of p columns.
  241. */
  242. define('MENU_MAX_DEPTH', 9);
  243. /**
  244. * @} End of "Menu tree parameters".
  245. */
  246. /**
  247. * Reserved key to identify the most specific menu link for a given path.
  248. *
  249. * The value of this constant is a hash of the constant name. We use the hash
  250. * so that the reserved key is over 32 characters in length and will not
  251. * collide with allowed menu names:
  252. * @code
  253. * sha1('MENU_PREFERRED_LINK') = 1cf698d64d1aa4b83907cf6ed55db3a7f8e92c91
  254. * @endcode
  255. *
  256. * @see menu_link_get_preferred()
  257. */
  258. define('MENU_PREFERRED_LINK', '1cf698d64d1aa4b83907cf6ed55db3a7f8e92c91');
  259. /**
  260. * Returns the ancestors (and relevant placeholders) for any given path.
  261. *
  262. * For example, the ancestors of node/12345/edit are:
  263. * - node/12345/edit
  264. * - node/12345/%
  265. * - node/%/edit
  266. * - node/%/%
  267. * - node/12345
  268. * - node/%
  269. * - node
  270. *
  271. * To generate these, we will use binary numbers. Each bit represents a
  272. * part of the path. If the bit is 1, then it represents the original
  273. * value while 0 means wildcard. If the path is node/12/edit/foo
  274. * then the 1011 bitstring represents node/%/edit/foo where % means that
  275. * any argument matches that part. We limit ourselves to using binary
  276. * numbers that correspond the patterns of wildcards of router items that
  277. * actually exists. This list of 'masks' is built in menu_rebuild().
  278. *
  279. * @param $parts
  280. * An array of path parts; for the above example,
  281. * array('node', '12345', 'edit').
  282. *
  283. * @return
  284. * An array which contains the ancestors and placeholders. Placeholders
  285. * simply contain as many '%s' as the ancestors.
  286. */
  287. function menu_get_ancestors($parts) {
  288. $number_parts = count($parts);
  289. $ancestors = array();
  290. $length = $number_parts - 1;
  291. $end = (1 << $number_parts) - 1;
  292. $masks = variable_get('menu_masks');
  293. // If the optimized menu_masks array is not available use brute force to get
  294. // the correct $ancestors and $placeholders returned. Do not use this as the
  295. // default value of the menu_masks variable to avoid building such a big
  296. // array.
  297. if (!$masks) {
  298. $masks = range(511, 1);
  299. }
  300. // Only examine patterns that actually exist as router items (the masks).
  301. foreach ($masks as $i) {
  302. if ($i > $end) {
  303. // Only look at masks that are not longer than the path of interest.
  304. continue;
  305. }
  306. elseif ($i < (1 << $length)) {
  307. // We have exhausted the masks of a given length, so decrease the length.
  308. --$length;
  309. }
  310. $current = '';
  311. for ($j = $length; $j >= 0; $j--) {
  312. // Check the bit on the $j offset.
  313. if ($i & (1 << $j)) {
  314. // Bit one means the original value.
  315. $current .= $parts[$length - $j];
  316. }
  317. else {
  318. // Bit zero means means wildcard.
  319. $current .= '%';
  320. }
  321. // Unless we are at offset 0, add a slash.
  322. if ($j) {
  323. $current .= '/';
  324. }
  325. }
  326. $ancestors[] = $current;
  327. }
  328. return $ancestors;
  329. }
  330. /**
  331. * Unserializes menu data, using a map to replace path elements.
  332. *
  333. * The menu system stores various path-related information (such as the 'page
  334. * arguments' and 'access arguments' components of a menu item) in the database
  335. * using serialized arrays, where integer values in the arrays represent
  336. * arguments to be replaced by values from the path. This function first
  337. * unserializes such menu information arrays, and then does the path
  338. * replacement.
  339. *
  340. * The path replacement acts on each integer-valued element of the unserialized
  341. * menu data array ($data) using a map array ($map, which is typically an array
  342. * of path arguments) as a list of replacements. For instance, if there is an
  343. * element of $data whose value is the number 2, then it is replaced in $data
  344. * with $map[2]; non-integer values in $data are left alone.
  345. *
  346. * As an example, an unserialized $data array with elements ('node_load', 1)
  347. * represents instructions for calling the node_load() function. Specifically,
  348. * this instruction says to use the path component at index 1 as the input
  349. * parameter to node_load(). If the path is 'node/123', then $map will be the
  350. * array ('node', 123), and the returned array from this function will have
  351. * elements ('node_load', 123), since $map[1] is 123. This return value will
  352. * indicate specifically that node_load(123) is to be called to load the node
  353. * whose ID is 123 for this menu item.
  354. *
  355. * @param $data
  356. * A serialized array of menu data, as read from the database.
  357. * @param $map
  358. * A path argument array, used to replace integer values in $data; an integer
  359. * value N in $data will be replaced by value $map[N]. Typically, the $map
  360. * array is generated from a call to the arg() function.
  361. *
  362. * @return
  363. * The unserialized $data array, with path arguments replaced.
  364. */
  365. function menu_unserialize($data, $map) {
  366. if ($data = unserialize($data)) {
  367. foreach ($data as $k => $v) {
  368. if (is_int($v)) {
  369. $data[$k] = isset($map[$v]) ? $map[$v] : '';
  370. }
  371. }
  372. return $data;
  373. }
  374. else {
  375. return array();
  376. }
  377. }
  378. /**
  379. * Replaces the statically cached item for a given path.
  380. *
  381. * @param $path
  382. * The path.
  383. * @param $router_item
  384. * The router item. Usually a router entry from menu_get_item() is either
  385. * modified or set to a different path. This allows the navigation block,
  386. * the page title, the breadcrumb, and the page help to be modified in one
  387. * call.
  388. */
  389. function menu_set_item($path, $router_item) {
  390. menu_get_item($path, $router_item);
  391. }
  392. /**
  393. * Gets a router item.
  394. *
  395. * @param $path
  396. * The path; for example, 'node/5'. The function will find the corresponding
  397. * node/% item and return that. Defaults to the current path.
  398. * @param $router_item
  399. * Internal use only.
  400. *
  401. * @return
  402. * The router item or, if an error occurs in _menu_translate(), FALSE. A
  403. * router item is an associative array corresponding to one row in the
  404. * menu_router table. The value corresponding to the key 'map' holds the
  405. * loaded objects. The value corresponding to the key 'access' is TRUE if the
  406. * current user can access this page. The values corresponding to the keys
  407. * 'title', 'page_arguments', 'access_arguments', and 'theme_arguments' will
  408. * be filled in based on the database values and the objects loaded.
  409. */
  410. function menu_get_item($path = NULL, $router_item = NULL) {
  411. $router_items = &drupal_static(__FUNCTION__);
  412. if (!isset($path)) {
  413. $path = $_GET['q'];
  414. }
  415. if (isset($router_item)) {
  416. $router_items[$path] = $router_item;
  417. }
  418. if (!isset($router_items[$path])) {
  419. // Rebuild if we know it's needed, or if the menu masks are missing which
  420. // occurs rarely, likely due to a race condition of multiple rebuilds.
  421. if (variable_get('menu_rebuild_needed', FALSE) || !variable_get('menu_masks', array())) {
  422. if (_menu_check_rebuild()) {
  423. menu_rebuild();
  424. }
  425. }
  426. $original_map = arg(NULL, $path);
  427. $parts = array_slice($original_map, 0, MENU_MAX_PARTS);
  428. $ancestors = menu_get_ancestors($parts);
  429. $router_item = db_query_range('SELECT * FROM {menu_router} WHERE path IN (:ancestors) ORDER BY fit DESC', 0, 1, array(':ancestors' => $ancestors))->fetchAssoc();
  430. if ($router_item) {
  431. // Allow modules to alter the router item before it is translated and
  432. // checked for access.
  433. drupal_alter('menu_get_item', $router_item, $path, $original_map);
  434. $map = _menu_translate($router_item, $original_map);
  435. $router_item['original_map'] = $original_map;
  436. if ($map === FALSE) {
  437. $router_items[$path] = FALSE;
  438. return FALSE;
  439. }
  440. if ($router_item['access']) {
  441. $router_item['map'] = $map;
  442. $router_item['page_arguments'] = array_merge(menu_unserialize($router_item['page_arguments'], $map), array_slice($map, $router_item['number_parts']));
  443. $router_item['theme_arguments'] = array_merge(menu_unserialize($router_item['theme_arguments'], $map), array_slice($map, $router_item['number_parts']));
  444. }
  445. }
  446. $router_items[$path] = $router_item;
  447. }
  448. return $router_items[$path];
  449. }
  450. /**
  451. * Execute the page callback associated with the current path.
  452. *
  453. * @param $path
  454. * The drupal path whose handler is to be be executed. If set to NULL, then
  455. * the current path is used.
  456. * @param $deliver
  457. * (optional) A boolean to indicate whether the content should be sent to the
  458. * browser using the appropriate delivery callback (TRUE) or whether to return
  459. * the result to the caller (FALSE).
  460. */
  461. function menu_execute_active_handler($path = NULL, $deliver = TRUE) {
  462. // Check if site is offline.
  463. $page_callback_result = _menu_site_is_offline() ? MENU_SITE_OFFLINE : MENU_SITE_ONLINE;
  464. // Allow other modules to change the site status but not the path because that
  465. // would not change the global variable. hook_url_inbound_alter() can be used
  466. // to change the path. Code later will not use the $read_only_path variable.
  467. $read_only_path = !empty($path) ? $path : $_GET['q'];
  468. drupal_alter('menu_site_status', $page_callback_result, $read_only_path);
  469. // Only continue if the site status is not set.
  470. if ($page_callback_result == MENU_SITE_ONLINE) {
  471. if ($router_item = menu_get_item($path)) {
  472. if ($router_item['access']) {
  473. if ($router_item['include_file']) {
  474. require_once DRUPAL_ROOT . '/' . $router_item['include_file'];
  475. }
  476. $page_callback_result = call_user_func_array($router_item['page_callback'], $router_item['page_arguments']);
  477. }
  478. else {
  479. $page_callback_result = MENU_ACCESS_DENIED;
  480. }
  481. }
  482. else {
  483. $page_callback_result = MENU_NOT_FOUND;
  484. }
  485. }
  486. // Deliver the result of the page callback to the browser, or if requested,
  487. // return it raw, so calling code can do more processing.
  488. if ($deliver) {
  489. $default_delivery_callback = (isset($router_item) && $router_item) ? $router_item['delivery_callback'] : NULL;
  490. drupal_deliver_page($page_callback_result, $default_delivery_callback);
  491. }
  492. else {
  493. return $page_callback_result;
  494. }
  495. }
  496. /**
  497. * Loads objects into the map as defined in the $item['load_functions'].
  498. *
  499. * @param $item
  500. * A menu router or menu link item
  501. * @param $map
  502. * An array of path arguments; for example, array('node', '5').
  503. *
  504. * @return
  505. * Returns TRUE for success, FALSE if an object cannot be loaded.
  506. * Names of object loading functions are placed in $item['load_functions'].
  507. * Loaded objects are placed in $map[]; keys are the same as keys in the
  508. * $item['load_functions'] array.
  509. * $item['access'] is set to FALSE if an object cannot be loaded.
  510. */
  511. function _menu_load_objects(&$item, &$map) {
  512. if ($load_functions = $item['load_functions']) {
  513. // If someone calls this function twice, then unserialize will fail.
  514. if (!is_array($load_functions)) {
  515. $load_functions = unserialize($load_functions);
  516. }
  517. $path_map = $map;
  518. foreach ($load_functions as $index => $function) {
  519. if ($function) {
  520. $value = isset($path_map[$index]) ? $path_map[$index] : '';
  521. if (is_array($function)) {
  522. // Set up arguments for the load function. These were pulled from
  523. // 'load arguments' in the hook_menu() entry, but they need
  524. // some processing. In this case the $function is the key to the
  525. // load_function array, and the value is the list of arguments.
  526. list($function, $args) = each($function);
  527. $load_functions[$index] = $function;
  528. // Some arguments are placeholders for dynamic items to process.
  529. foreach ($args as $i => $arg) {
  530. if ($arg === '%index') {
  531. // Pass on argument index to the load function, so multiple
  532. // occurrences of the same placeholder can be identified.
  533. $args[$i] = $index;
  534. }
  535. if ($arg === '%map') {
  536. // Pass on menu map by reference. The accepting function must
  537. // also declare this as a reference if it wants to modify
  538. // the map.
  539. $args[$i] = &$map;
  540. }
  541. if (is_int($arg)) {
  542. $args[$i] = isset($path_map[$arg]) ? $path_map[$arg] : '';
  543. }
  544. }
  545. array_unshift($args, $value);
  546. $return = call_user_func_array($function, $args);
  547. }
  548. else {
  549. $return = $function($value);
  550. }
  551. // If callback returned an error or there is no callback, trigger 404.
  552. if ($return === FALSE) {
  553. $item['access'] = FALSE;
  554. $map = FALSE;
  555. return FALSE;
  556. }
  557. $map[$index] = $return;
  558. }
  559. }
  560. $item['load_functions'] = $load_functions;
  561. }
  562. return TRUE;
  563. }
  564. /**
  565. * Checks access to a menu item using the access callback.
  566. *
  567. * @param $item
  568. * A menu router or menu link item
  569. * @param $map
  570. * An array of path arguments; for example, array('node', '5').
  571. *
  572. * @return
  573. * $item['access'] becomes TRUE if the item is accessible, FALSE otherwise.
  574. */
  575. function _menu_check_access(&$item, $map) {
  576. $item['access'] = FALSE;
  577. // Determine access callback, which will decide whether or not the current
  578. // user has access to this path.
  579. $callback = empty($item['access_callback']) ? 0 : trim($item['access_callback']);
  580. // Check for a TRUE or FALSE value.
  581. if (is_numeric($callback)) {
  582. $item['access'] = (bool) $callback;
  583. }
  584. else {
  585. $arguments = menu_unserialize($item['access_arguments'], $map);
  586. // As call_user_func_array is quite slow and user_access is a very common
  587. // callback, it is worth making a special case for it.
  588. if ($callback == 'user_access') {
  589. $item['access'] = (count($arguments) == 1) ? user_access($arguments[0]) : user_access($arguments[0], $arguments[1]);
  590. }
  591. elseif (function_exists($callback)) {
  592. $item['access'] = call_user_func_array($callback, $arguments);
  593. }
  594. }
  595. }
  596. /**
  597. * Localizes the router item title using t() or another callback.
  598. *
  599. * Translate the title and description to allow storage of English title
  600. * strings in the database, yet display of them in the language required
  601. * by the current user.
  602. *
  603. * @param $item
  604. * A menu router item or a menu link item.
  605. * @param $map
  606. * The path as an array with objects already replaced. E.g., for path
  607. * node/123 $map would be array('node', $node) where $node is the node
  608. * object for node 123.
  609. * @param $link_translate
  610. * TRUE if we are translating a menu link item; FALSE if we are
  611. * translating a menu router item.
  612. *
  613. * @return
  614. * No return value.
  615. * $item['title'] is localized according to $item['title_callback'].
  616. * If an item's callback is check_plain(), $item['options']['html'] becomes
  617. * TRUE.
  618. * $item['description'] is translated using t().
  619. * When doing link translation and the $item['options']['attributes']['title']
  620. * (link title attribute) matches the description, it is translated as well.
  621. */
  622. function _menu_item_localize(&$item, $map, $link_translate = FALSE) {
  623. $callback = $item['title_callback'];
  624. $item['localized_options'] = $item['options'];
  625. // All 'class' attributes are assumed to be an array during rendering, but
  626. // links stored in the database may use an old string value.
  627. // @todo In order to remove this code we need to implement a database update
  628. // including unserializing all existing link options and running this code
  629. // on them, as well as adding validation to menu_link_save().
  630. if (isset($item['options']['attributes']['class']) && is_string($item['options']['attributes']['class'])) {
  631. $item['localized_options']['attributes']['class'] = explode(' ', $item['options']['attributes']['class']);
  632. }
  633. // If we are translating the title of a menu link, and its title is the same
  634. // as the corresponding router item, then we can use the title information
  635. // from the router. If it's customized, then we need to use the link title
  636. // itself; can't localize.
  637. // If we are translating a router item (tabs, page, breadcrumb), then we
  638. // can always use the information from the router item.
  639. if (!$link_translate || ($item['title'] == $item['link_title'])) {
  640. // t() is a special case. Since it is used very close to all the time,
  641. // we handle it directly instead of using indirect, slower methods.
  642. if ($callback == 't') {
  643. if (empty($item['title_arguments'])) {
  644. $item['title'] = t($item['title']);
  645. }
  646. else {
  647. $item['title'] = t($item['title'], menu_unserialize($item['title_arguments'], $map));
  648. }
  649. }
  650. elseif ($callback && function_exists($callback)) {
  651. if (empty($item['title_arguments'])) {
  652. $item['title'] = $callback($item['title']);
  653. }
  654. else {
  655. $item['title'] = call_user_func_array($callback, menu_unserialize($item['title_arguments'], $map));
  656. }
  657. // Avoid calling check_plain again on l() function.
  658. if ($callback == 'check_plain') {
  659. $item['localized_options']['html'] = TRUE;
  660. }
  661. }
  662. }
  663. elseif ($link_translate) {
  664. $item['title'] = $item['link_title'];
  665. }
  666. // Translate description, see the motivation above.
  667. if (!empty($item['description'])) {
  668. $original_description = $item['description'];
  669. $item['description'] = t($item['description']);
  670. if ($link_translate && isset($item['options']['attributes']['title']) && $item['options']['attributes']['title'] == $original_description) {
  671. $item['localized_options']['attributes']['title'] = $item['description'];
  672. }
  673. }
  674. }
  675. /**
  676. * Handles dynamic path translation and menu access control.
  677. *
  678. * When a user arrives on a page such as node/5, this function determines
  679. * what "5" corresponds to, by inspecting the page's menu path definition,
  680. * node/%node. This will call node_load(5) to load the corresponding node
  681. * object.
  682. *
  683. * It also works in reverse, to allow the display of tabs and menu items which
  684. * contain these dynamic arguments, translating node/%node to node/5.
  685. *
  686. * Translation of menu item titles and descriptions are done here to
  687. * allow for storage of English strings in the database, and translation
  688. * to the language required to generate the current page.
  689. *
  690. * @param $router_item
  691. * A menu router item
  692. * @param $map
  693. * An array of path arguments; for example, array('node', '5').
  694. * @param $to_arg
  695. * Execute $item['to_arg_functions'] or not. Use only if you want to render a
  696. * path from the menu table, for example tabs.
  697. *
  698. * @return
  699. * Returns the map with objects loaded as defined in the
  700. * $item['load_functions']. $item['access'] becomes TRUE if the item is
  701. * accessible, FALSE otherwise. $item['href'] is set according to the map.
  702. * If an error occurs during calling the load_functions (like trying to load
  703. * a non-existent node) then this function returns FALSE.
  704. */
  705. function _menu_translate(&$router_item, $map, $to_arg = FALSE) {
  706. if ($to_arg && !empty($router_item['to_arg_functions'])) {
  707. // Fill in missing path elements, such as the current uid.
  708. _menu_link_map_translate($map, $router_item['to_arg_functions']);
  709. }
  710. // The $path_map saves the pieces of the path as strings, while elements in
  711. // $map may be replaced with loaded objects.
  712. $path_map = $map;
  713. if (!empty($router_item['load_functions']) && !_menu_load_objects($router_item, $map)) {
  714. // An error occurred loading an object.
  715. $router_item['access'] = FALSE;
  716. return FALSE;
  717. }
  718. // Generate the link path for the page request or local tasks.
  719. $link_map = explode('/', $router_item['path']);
  720. if (isset($router_item['tab_root'])) {
  721. $tab_root_map = explode('/', $router_item['tab_root']);
  722. }
  723. if (isset($router_item['tab_parent'])) {
  724. $tab_parent_map = explode('/', $router_item['tab_parent']);
  725. }
  726. for ($i = 0; $i < $router_item['number_parts']; $i++) {
  727. if ($link_map[$i] == '%') {
  728. $link_map[$i] = $path_map[$i];
  729. }
  730. if (isset($tab_root_map[$i]) && $tab_root_map[$i] == '%') {
  731. $tab_root_map[$i] = $path_map[$i];
  732. }
  733. if (isset($tab_parent_map[$i]) && $tab_parent_map[$i] == '%') {
  734. $tab_parent_map[$i] = $path_map[$i];
  735. }
  736. }
  737. $router_item['href'] = implode('/', $link_map);
  738. $router_item['tab_root_href'] = implode('/', $tab_root_map);
  739. $router_item['tab_parent_href'] = implode('/', $tab_parent_map);
  740. $router_item['options'] = array();
  741. _menu_check_access($router_item, $map);
  742. // For performance, don't localize an item the user can't access.
  743. if ($router_item['access']) {
  744. _menu_item_localize($router_item, $map);
  745. }
  746. return $map;
  747. }
  748. /**
  749. * Translates the path elements in the map using any to_arg helper function.
  750. *
  751. * @param $map
  752. * An array of path arguments; for example, array('node', '5').
  753. * @param $to_arg_functions
  754. * An array of helper functions; for example, array(2 => 'menu_tail_to_arg').
  755. *
  756. * @see hook_menu()
  757. */
  758. function _menu_link_map_translate(&$map, $to_arg_functions) {
  759. $to_arg_functions = unserialize($to_arg_functions);
  760. foreach ($to_arg_functions as $index => $function) {
  761. // Translate place-holders into real values.
  762. $arg = $function(!empty($map[$index]) ? $map[$index] : '', $map, $index);
  763. if (!empty($map[$index]) || isset($arg)) {
  764. $map[$index] = $arg;
  765. }
  766. else {
  767. unset($map[$index]);
  768. }
  769. }
  770. }
  771. /**
  772. * Returns a string containing the path relative to the current index.
  773. */
  774. function menu_tail_to_arg($arg, $map, $index) {
  775. return implode('/', array_slice($map, $index));
  776. }
  777. /**
  778. * Loads the path as one string relative to the current index.
  779. *
  780. * To use this load function, you must specify the load arguments
  781. * in the router item as:
  782. * @code
  783. * $item['load arguments'] = array('%map', '%index');
  784. * @endcode
  785. *
  786. * @see search_menu().
  787. */
  788. function menu_tail_load($arg, &$map, $index) {
  789. $arg = implode('/', array_slice($map, $index));
  790. $map = array_slice($map, 0, $index);
  791. return $arg;
  792. }
  793. /**
  794. * Provides menu link access control, translation, and argument handling.
  795. *
  796. * This function is similar to _menu_translate(), but it also does
  797. * link-specific preparation (such as always calling to_arg() functions).
  798. *
  799. * @param $item
  800. * A menu link.
  801. * @param $translate
  802. * (optional) Whether to try to translate a link containing dynamic path
  803. * argument placeholders (%) based on the menu router item of the current
  804. * path. Defaults to FALSE. Internally used for breadcrumbs.
  805. *
  806. * @return
  807. * Returns the map of path arguments with objects loaded as defined in the
  808. * $item['load_functions'].
  809. * $item['access'] becomes TRUE if the item is accessible, FALSE otherwise.
  810. * $item['href'] is generated from link_path, possibly by to_arg functions.
  811. * $item['title'] is generated from link_title, and may be localized.
  812. * $item['options'] is unserialized; it is also changed within the call here
  813. * to $item['localized_options'] by _menu_item_localize().
  814. */
  815. function _menu_link_translate(&$item, $translate = FALSE) {
  816. if (!is_array($item['options'])) {
  817. $item['options'] = unserialize($item['options']);
  818. }
  819. if ($item['external']) {
  820. $item['access'] = 1;
  821. $map = array();
  822. $item['href'] = $item['link_path'];
  823. $item['title'] = $item['link_title'];
  824. $item['localized_options'] = $item['options'];
  825. }
  826. else {
  827. // Complete the path of the menu link with elements from the current path,
  828. // if it contains dynamic placeholders (%).
  829. $map = explode('/', $item['link_path']);
  830. if (strpos($item['link_path'], '%') !== FALSE) {
  831. // Invoke registered to_arg callbacks.
  832. if (!empty($item['to_arg_functions'])) {
  833. _menu_link_map_translate($map, $item['to_arg_functions']);
  834. }
  835. // Or try to derive the path argument map from the current router item,
  836. // if this $item's path is within the router item's path. This means
  837. // that if we are on the current path 'foo/%/bar/%/baz', then
  838. // menu_get_item() will have translated the menu router item for the
  839. // current path, and we can take over the argument map for a link like
  840. // 'foo/%/bar'. This inheritance is only valid for breadcrumb links.
  841. // @see _menu_tree_check_access()
  842. // @see menu_get_active_breadcrumb()
  843. elseif ($translate && ($current_router_item = menu_get_item())) {
  844. // If $translate is TRUE, then this link is in the active trail.
  845. // Only translate paths within the current path.
  846. if (strpos($current_router_item['path'], $item['link_path']) === 0) {
  847. $count = count($map);
  848. $map = array_slice($current_router_item['original_map'], 0, $count);
  849. $item['original_map'] = $map;
  850. if (isset($current_router_item['map'])) {
  851. $item['map'] = array_slice($current_router_item['map'], 0, $count);
  852. }
  853. // Reset access to check it (for the first time).
  854. unset($item['access']);
  855. }
  856. }
  857. }
  858. $item['href'] = implode('/', $map);
  859. // Skip links containing untranslated arguments.
  860. if (strpos($item['href'], '%') !== FALSE) {
  861. $item['access'] = FALSE;
  862. return FALSE;
  863. }
  864. // menu_tree_check_access() may set this ahead of time for links to nodes.
  865. if (!isset($item['access'])) {
  866. if (!empty($item['load_functions']) && !_menu_load_objects($item, $map)) {
  867. // An error occurred loading an object.
  868. $item['access'] = FALSE;
  869. return FALSE;
  870. }
  871. _menu_check_access($item, $map);
  872. }
  873. // For performance, don't localize a link the user can't access.
  874. if ($item['access']) {
  875. _menu_item_localize($item, $map, TRUE);
  876. }
  877. }
  878. // Allow other customizations - e.g. adding a page-specific query string to the
  879. // options array. For performance reasons we only invoke this hook if the link
  880. // has the 'alter' flag set in the options array.
  881. if (!empty($item['options']['alter'])) {
  882. drupal_alter('translated_menu_link', $item, $map);
  883. }
  884. return $map;
  885. }
  886. /**
  887. * Gets a loaded object from a router item.
  888. *
  889. * menu_get_object() provides access to objects loaded by the current router
  890. * item. For example, on the page node/%node, the router loads the %node object,
  891. * and calling menu_get_object() will return that. Normally, it is necessary to
  892. * specify the type of object referenced, however node is the default.
  893. * The following example tests to see whether the node being displayed is of the
  894. * "story" content type:
  895. * @code
  896. * $node = menu_get_object();
  897. * $story = $node->type == 'story';
  898. * @endcode
  899. *
  900. * @param $type
  901. * Type of the object. These appear in hook_menu definitions as %type. Core
  902. * provides aggregator_feed, aggregator_category, contact, filter_format,
  903. * forum_term, menu, menu_link, node, taxonomy_vocabulary, user. See the
  904. * relevant {$type}_load function for more on each. Defaults to node.
  905. * @param $position
  906. * The position of the object in the path, where the first path segment is 0.
  907. * For node/%node, the position of %node is 1, but for comment/reply/%node,
  908. * it's 2. Defaults to 1.
  909. * @param $path
  910. * See menu_get_item() for more on this. Defaults to the current path.
  911. */
  912. function menu_get_object($type = 'node', $position = 1, $path = NULL) {
  913. $router_item = menu_get_item($path);
  914. if (isset($router_item['load_functions'][$position]) && !empty($router_item['map'][$position]) && $router_item['load_functions'][$position] == $type . '_load') {
  915. return $router_item['map'][$position];
  916. }
  917. }
  918. /**
  919. * Renders a menu tree based on the current path.
  920. *
  921. * The tree is expanded based on the current path and dynamic paths are also
  922. * changed according to the defined to_arg functions (for example the 'My
  923. * account' link is changed from user/% to a link with the current user's uid).
  924. *
  925. * @param $menu_name
  926. * The name of the menu.
  927. *
  928. * @return
  929. * A structured array representing the specified menu on the current page, to
  930. * be rendered by drupal_render().
  931. */
  932. function menu_tree($menu_name) {
  933. $menu_output = &drupal_static(__FUNCTION__, array());
  934. if (!isset($menu_output[$menu_name])) {
  935. $tree = menu_tree_page_data($menu_name);
  936. $menu_output[$menu_name] = menu_tree_output($tree);
  937. }
  938. return $menu_output[$menu_name];
  939. }
  940. /**
  941. * Returns an output structure for rendering a menu tree.
  942. *
  943. * The menu item's LI element is given one of the following classes:
  944. * - expanded: The menu item is showing its submenu.
  945. * - collapsed: The menu item has a submenu which is not shown.
  946. * - leaf: The menu item has no submenu.
  947. *
  948. * @param $tree
  949. * A data structure representing the tree as returned from menu_tree_data.
  950. *
  951. * @return
  952. * A structured array to be rendered by drupal_render().
  953. */
  954. function menu_tree_output($tree) {
  955. $build = array();
  956. $items = array();
  957. // Pull out just the menu links we are going to render so that we
  958. // get an accurate count for the first/last classes.
  959. foreach ($tree as $data) {
  960. if ($data['link']['access'] && !$data['link']['hidden']) {
  961. $items[] = $data;
  962. }
  963. }
  964. $router_item = menu_get_item();
  965. $num_items = count($items);
  966. foreach ($items as $i => $data) {
  967. $class = array();
  968. if ($i == 0) {
  969. $class[] = 'first';
  970. }
  971. if ($i == $num_items - 1) {
  972. $class[] = 'last';
  973. }
  974. // Set a class for the <li>-tag. Since $data['below'] may contain local
  975. // tasks, only set 'expanded' class if the link also has children within
  976. // the current menu.
  977. if ($data['link']['has_children'] && $data['below']) {
  978. $class[] = 'expanded';
  979. }
  980. elseif ($data['link']['has_children']) {
  981. $class[] = 'collapsed';
  982. }
  983. else {
  984. $class[] = 'leaf';
  985. }
  986. // Set a class if the link is in the active trail.
  987. if ($data['link']['in_active_trail']) {
  988. $class[] = 'active-trail';
  989. $data['link']['localized_options']['attributes']['class'][] = 'active-trail';
  990. }
  991. // Normally, l() compares the href of every link with $_GET['q'] and sets
  992. // the active class accordingly. But local tasks do not appear in menu
  993. // trees, so if the current path is a local task, and this link is its
  994. // tab root, then we have to set the class manually.
  995. if ($data['link']['href'] == $router_item['tab_root_href'] && $data['link']['href'] != $_GET['q']) {
  996. $data['link']['localized_options']['attributes']['class'][] = 'active';
  997. }
  998. // Allow menu-specific theme overrides.
  999. $element['#theme'] = 'menu_link__' . strtr($data['link']['menu_name'], '-', '_');
  1000. $element['#attributes']['class'] = $class;
  1001. $element['#title'] = $data['link']['title'];
  1002. $element['#href'] = $data['link']['href'];
  1003. $element['#localized_options'] = !empty($data['link']['localized_options']) ? $data['link']['localized_options'] : array();
  1004. $element['#below'] = $data['below'] ? menu_tree_output($data['below']) : $data['below'];
  1005. $element['#original_link'] = $data['link'];
  1006. // Index using the link's unique mlid.
  1007. $build[$data['link']['mlid']] = $element;
  1008. }
  1009. if ($build) {
  1010. // Make sure drupal_render() does not re-order the links.
  1011. $build['#sorted'] = TRUE;
  1012. // Add the theme wrapper for outer markup.
  1013. // Allow menu-specific theme overrides.
  1014. $build['#theme_wrappers'][] = 'menu_tree__' . strtr($data['link']['menu_name'], '-', '_');
  1015. }
  1016. return $build;
  1017. }
  1018. /**
  1019. * Gets the data structure representing a named menu tree.
  1020. *
  1021. * Since this can be the full tree including hidden items, the data returned
  1022. * may be used for generating an an admin interface or a select.
  1023. *
  1024. * @param $menu_name
  1025. * The named menu links to return
  1026. * @param $link
  1027. * A fully loaded menu link, or NULL. If a link is supplied, only the
  1028. * path to root will be included in the returned tree - as if this link
  1029. * represented the current page in a visible menu.
  1030. * @param $max_depth
  1031. * Optional maximum depth of links to retrieve. Typically useful if only one
  1032. * or two levels of a sub tree are needed in conjunction with a non-NULL
  1033. * $link, in which case $max_depth should be greater than $link['depth'].
  1034. *
  1035. * @return
  1036. * An tree of menu links in an array, in the order they should be rendered.
  1037. */
  1038. function menu_tree_all_data($menu_name, $link = NULL, $max_depth = NULL) {
  1039. $tree = &drupal_static(__FUNCTION__, array());
  1040. // Use $mlid as a flag for whether the data being loaded is for the whole tree.
  1041. $mlid = isset($link['mlid']) ? $link['mlid'] : 0;
  1042. // Generate a cache ID (cid) specific for this $menu_name, $link, $language, and depth.
  1043. $cid = 'links:' . $menu_name . ':all:' . $mlid . ':' . $GLOBALS['language']->language . ':' . (int) $max_depth;
  1044. if (!isset($tree[$cid])) {
  1045. // If the static variable doesn't have the data, check {cache_menu}.
  1046. $cache = cache_get($cid, 'cache_menu');
  1047. if ($cache && isset($cache->data)) {
  1048. // If the cache entry exists, it contains the parameters for
  1049. // menu_build_tree().
  1050. $tree_parameters = $cache->data;
  1051. }
  1052. // If the tree data was not in the cache, build $tree_parameters.
  1053. if (!isset($tree_parameters)) {
  1054. $tree_parameters = array(
  1055. 'min_depth' => 1,
  1056. 'max_depth' => $max_depth,
  1057. );
  1058. if ($mlid) {
  1059. // The tree is for a single item, so we need to match the values in its
  1060. // p columns and 0 (the top level) with the plid values of other links.
  1061. $parents = array(0);
  1062. for ($i = 1; $i < MENU_MAX_DEPTH; $i++) {
  1063. if (!empty($link["p$i"])) {
  1064. $parents[] = $link["p$i"];
  1065. }
  1066. }
  1067. $tree_parameters['expanded'] = $parents;
  1068. $tree_parameters['active_trail'] = $parents;
  1069. $tree_parameters['active_trail'][] = $mlid;
  1070. }
  1071. // Cache the tree building parameters using the page-specific cid.
  1072. cache_set($cid, $tree_parameters, 'cache_menu');
  1073. }
  1074. // Build the tree using the parameters; the resulting tree will be cached
  1075. // by _menu_build_tree()).
  1076. $tree[$cid] = menu_build_tree($menu_name, $tree_parameters);
  1077. }
  1078. return $tree[$cid];
  1079. }
  1080. /**
  1081. * Sets the path for determining the active trail of the specified menu tree.
  1082. *
  1083. * This path will also affect the breadcrumbs under some circumstances.
  1084. * Breadcrumbs are built using the preferred link returned by
  1085. * menu_link_get_preferred(). If the preferred link is inside one of the menus
  1086. * specified in calls to menu_tree_set_path(), the preferred link will be
  1087. * overridden by the corresponding path returned by menu_tree_get_path().
  1088. *
  1089. * Setting this path does not affect the main content; for that use
  1090. * menu_set_active_item() instead.
  1091. *
  1092. * @param $menu_name
  1093. * The name of the affected menu tree.
  1094. * @param $path
  1095. * The path to use when finding the active trail.
  1096. */
  1097. function menu_tree_set_path($menu_name, $path = NULL) {
  1098. $paths = &drupal_static(__FUNCTION__);
  1099. if (isset($path)) {
  1100. $paths[$menu_name] = $path;
  1101. }
  1102. return isset($paths[$menu_name]) ? $paths[$menu_name] : NULL;
  1103. }
  1104. /**
  1105. * Gets the path for determining the active trail of the specified menu tree.
  1106. *
  1107. * @param $menu_name
  1108. * The menu name of the requested tree.
  1109. *
  1110. * @return
  1111. * A string containing the path. If no path has been specified with
  1112. * menu_tree_set_path(), NULL is returned.
  1113. */
  1114. function menu_tree_get_path($menu_name) {
  1115. return menu_tree_set_path($menu_name);
  1116. }
  1117. /**
  1118. * Gets the data structure for a named menu tree, based on the current page.
  1119. *
  1120. * The tree order is maintained by storing each parent in an individual
  1121. * field, see http://drupal.org/node/141866 for more.
  1122. *
  1123. * @param $menu_name
  1124. * The named menu links to return.
  1125. * @param $max_depth
  1126. * (optional) The maximum depth of links to retrieve.
  1127. * @param $only_active_trail
  1128. * (optional) Whether to only return the links in the active trail (TRUE)
  1129. * instead of all links on every level of the menu link tree (FALSE). Defaults
  1130. * to FALSE. Internally used for breadcrumbs only.
  1131. *
  1132. * @return
  1133. * An array of menu links, in the order they should be rendered. The array
  1134. * is a list of associative arrays -- these have two keys, link and below.
  1135. * link is a menu item, ready for theming as a link. Below represents the
  1136. * submenu below the link if there is one, and it is a subtree that has the
  1137. * same structure described for the top-level array.
  1138. */
  1139. function menu_tree_page_data($menu_name, $max_depth = NULL, $only_active_trail = FALSE) {
  1140. $tree = &drupal_static(__FUNCTION__, array());
  1141. // Check if the active trail has been overridden for this menu tree.
  1142. $active_path = menu_tree_get_path($menu_name);
  1143. // Load the menu item corresponding to the current page.
  1144. if ($item = menu_get_item($active_path)) {
  1145. if (isset($max_depth)) {
  1146. $max_depth = min($max_depth, MENU_MAX_DEPTH);
  1147. }
  1148. // Generate a cache ID (cid) specific for this page.
  1149. $cid = 'links:' . $menu_name . ':page:' . $item['href'] . ':' . $GLOBALS['language']->language . ':' . (int) $item['access'] . ':' . (int) $max_depth;
  1150. // If we are asked for the active trail only, and $menu_name has not been
  1151. // built and cached for this page yet, then this likely means that it
  1152. // won't be built anymore, as this function is invoked from
  1153. // template_process_page(). So in order to not build a giant menu tree
  1154. // that needs to be checked for access on all levels, we simply check
  1155. // whether we have the menu already in cache, or otherwise, build a minimum
  1156. // tree containing the breadcrumb/active trail only.
  1157. // @see menu_set_active_trail()
  1158. if (!isset($tree[$cid]) && $only_active_trail) {
  1159. $cid .= ':trail';
  1160. }
  1161. if (!isset($tree[$cid])) {
  1162. // If the static variable doesn't have the data, check {cache_menu}.
  1163. $cache = cache_get($cid, 'cache_menu');
  1164. if ($cache && isset($cache->data)) {
  1165. // If the cache entry exists, it contains the parameters for
  1166. // menu_build_tree().
  1167. $tree_parameters = $cache->data;
  1168. }
  1169. // If the tree data was not in the cache, build $tree_parameters.
  1170. if (!isset($tree_parameters)) {
  1171. $tree_parameters = array(
  1172. 'min_depth' => 1,
  1173. 'max_depth' => $max_depth,
  1174. );
  1175. // Parent mlids; used both as key and value to ensure uniqueness.
  1176. // We always want all the top-level links with plid == 0.
  1177. $active_trail = array(0 => 0);
  1178. // If the item for the current page is accessible, build the tree
  1179. // parameters accordingly.
  1180. if ($item['access']) {
  1181. // Find a menu link corresponding to the current path. If $active_path
  1182. // is NULL, let menu_link_get_preferred() determine the path.
  1183. if ($active_link = menu_link_get_preferred($active_path, $menu_name)) {
  1184. // The active link may only be taken into account to build the
  1185. // active trail, if it resides in the requested menu. Otherwise,
  1186. // we'd needlessly re-run _menu_build_tree() queries for every menu
  1187. // on every page.
  1188. if ($active_link['menu_name'] == $menu_name) {
  1189. // Use all the coordinates, except the last one because there
  1190. // can be no child beyond the last column.
  1191. for ($i = 1; $i < MENU_MAX_DEPTH; $i++) {
  1192. if ($active_link['p' . $i]) {
  1193. $active_trail[$active_link['p' . $i]] = $active_link['p' . $i];
  1194. }
  1195. }
  1196. // If we are asked to build links for the active trail only, skip
  1197. // the entire 'expanded' handling.
  1198. if ($only_active_trail) {
  1199. $tree_parameters['only_active_trail'] = TRUE;
  1200. }
  1201. }
  1202. }
  1203. $parents = $active_trail;
  1204. $expanded = variable_get('menu_expanded', array());
  1205. // Check whether the current menu has any links set to be expanded.
  1206. if (!$only_active_trail && in_array($menu_name, $expanded)) {
  1207. // Collect all the links set to be expanded, and then add all of
  1208. // their children to the list as well.
  1209. do {
  1210. $result = db_select('menu_links', NULL, array('fetch' => PDO::FETCH_ASSOC))
  1211. ->fields('menu_links', array('mlid'))
  1212. ->condition('menu_name', $menu_name)
  1213. ->condition('expanded', 1)
  1214. ->condition('has_children', 1)
  1215. ->condition('plid', $parents, 'IN')
  1216. ->condition('mlid', $parents, 'NOT IN')
  1217. ->execute();
  1218. $num_rows = FALSE;
  1219. foreach ($result as $item) {
  1220. $parents[$item['mlid']] = $item['mlid'];
  1221. $num_rows = TRUE;
  1222. }
  1223. } while ($num_rows);
  1224. }
  1225. $tree_parameters['expanded'] = $parents;
  1226. $tree_parameters['active_trail'] = $active_trail;
  1227. }
  1228. // If access is denied, we only show top-level links in menus.
  1229. else {
  1230. $tree_parameters['expanded'] = $active_trail;
  1231. $tree_parameters['active_trail'] = $active_trail;
  1232. }
  1233. // Cache the tree building parameters using the page-specific cid.
  1234. cache_set($cid, $tree_parameters, 'cache_menu');
  1235. }
  1236. // Build the tree using the parameters; the resulting tree will be cached
  1237. // by _menu_build_tree().
  1238. $tree[$cid] = menu_build_tree($menu_name, $tree_parameters);
  1239. }
  1240. return $tree[$cid];
  1241. }
  1242. return array();
  1243. }
  1244. /**
  1245. * Builds a menu tree, translates links, and checks access.
  1246. *
  1247. * @param $menu_name
  1248. * The name of the menu.
  1249. * @param $parameters
  1250. * (optional) An associative array of build parameters. Possible keys:
  1251. * - expanded: An array of parent link ids to return only menu links that are
  1252. * children of one of the plids in this list. If empty, the whole menu tree
  1253. * is built, unless 'only_active_trail' is TRUE.
  1254. * - active_trail: An array of mlids, representing the coordinates of the
  1255. * currently active menu link.
  1256. * - only_active_trail: Whether to only return links that are in the active
  1257. * trail. This option is ignored, if 'expanded' is non-empty. Internally
  1258. * used for breadcrumbs.
  1259. * - min_depth: The minimum depth of menu links in the resulting tree.
  1260. * Defaults to 1, which is the default to build a whole tree for a menu
  1261. * (excluding menu container itself).
  1262. * - max_depth: The maximum depth of menu links in the resulting tree.
  1263. * - conditions: An associative array of custom database select query
  1264. * condition key/value pairs; see _menu_build_tree() for the actual query.
  1265. *
  1266. * @return
  1267. * A fully built menu tree.
  1268. */
  1269. function menu_build_tree($menu_name, array $parameters = array()) {
  1270. // Build the menu tree.
  1271. $data = _menu_build_tree($menu_name, $parameters);
  1272. // Check access for the current user to each item in the tree.
  1273. menu_tree_check_access($data['tree'], $data['node_links']);
  1274. return $data['tree'];
  1275. }
  1276. /**
  1277. * Builds a menu tree.
  1278. *
  1279. * This function may be used build the data for a menu tree only, for example
  1280. * to further massage the data manually before further processing happens.
  1281. * menu_tree_check_access() needs to be invoked afterwards.
  1282. *
  1283. * @see menu_build_tree()
  1284. */
  1285. function _menu_build_tree($menu_name, array $parameters = array()) {
  1286. // Static cache of already built menu trees.
  1287. $trees = &drupal_static(__FUNCTION__, array());
  1288. // Build the cache id; sort parents to prevent duplicate storage and remove
  1289. // default parameter values.
  1290. if (isset($parameters['expanded'])) {
  1291. sort($parameters['expanded']);
  1292. }
  1293. $tree_cid = 'links:' . $menu_name . ':tree-data:' . $GLOBALS['language']->language . ':' . hash('sha256', serialize($parameters));
  1294. // If we do not have this tree in the static cache, check {cache_menu}.
  1295. if (!isset($trees[$tree_cid])) {
  1296. $cache = cache_get($tree_cid, 'cache_menu');
  1297. if ($cache && isset($cache->data)) {
  1298. $trees[$tree_cid] = $cache->data;
  1299. }
  1300. }
  1301. if (!isset($trees[$tree_cid])) {
  1302. // Select the links from the table, and recursively build the tree. We
  1303. // LEFT JOIN since there is no match in {menu_router} for an external
  1304. // link.
  1305. $query = db_select('menu_links', 'ml', array('fetch' => PDO::FETCH_ASSOC));
  1306. $query->addTag('translatable');
  1307. $query->leftJoin('menu_router', 'm', 'm.path = ml.router_path');
  1308. $query->fields('ml');
  1309. $query->fields('m', array(
  1310. 'load_functions',
  1311. 'to_arg_functions',
  1312. 'access_callback',
  1313. 'access_arguments',
  1314. 'page_callback',
  1315. 'page_arguments',
  1316. 'delivery_callback',
  1317. 'tab_parent',
  1318. 'tab_root',
  1319. 'title',
  1320. 'title_callback',
  1321. 'title_arguments',
  1322. 'theme_callback',
  1323. 'theme_arguments',
  1324. 'type',
  1325. 'description',
  1326. ));
  1327. for ($i = 1; $i <= MENU_MAX_DEPTH; $i++) {
  1328. $query->orderBy('p' . $i, 'ASC');
  1329. }
  1330. $query->condition('ml.menu_name', $menu_name);
  1331. if (!empty($parameters['expanded'])) {
  1332. $query->condition('ml.plid', $parameters['expanded'], 'IN');
  1333. }
  1334. elseif (!empty($parameters['only_active_trail'])) {
  1335. $query->condition('ml.mlid', $parameters['active_trail'], 'IN');
  1336. }
  1337. $min_depth = (isset($parameters['min_depth']) ? $parameters['min_depth'] : 1);
  1338. if ($min_depth != 1) {
  1339. $query->condition('ml.depth', $min_depth, '>=');
  1340. }
  1341. if (isset($parameters['max_depth'])) {
  1342. $query->condition('ml.depth', $parameters['max_depth'], '<=');
  1343. }
  1344. // Add custom query conditions, if any were passed.
  1345. if (isset($parameters['conditions'])) {
  1346. foreach ($parameters['conditions'] as $column => $value) {
  1347. $query->condition($column, $value);
  1348. }
  1349. }
  1350. // Build an ordered array of links using the query result object.
  1351. $links = array();
  1352. foreach ($query->execute() as $item) {
  1353. $links[] = $item;
  1354. }
  1355. $active_trail = (isset($parameters['active_trail']) ? $parameters['active_trail'] : array());
  1356. $data['tree'] = menu_tree_data($links, $active_trail, $min_depth);
  1357. $data['node_links'] = array();
  1358. menu_tree_collect_node_links($data['tree'], $data['node_links']);
  1359. // Cache the data, if it is not already in the cache.
  1360. cache_set($tree_cid, $data, 'cache_menu');
  1361. $trees[$tree_cid] = $data;
  1362. }
  1363. return $trees[$tree_cid];
  1364. }
  1365. /**
  1366. * Collects node links from a given menu tree recursively.
  1367. *
  1368. * @param $tree
  1369. * The menu tree you wish to collect node links from.
  1370. * @param $node_links
  1371. * An array in which to store the collected node links.
  1372. */
  1373. function menu_tree_collect_node_links(&$tree, &$node_links) {
  1374. foreach ($tree as $key => $v) {
  1375. if ($tree[$key]['link']['router_path'] == 'node/%') {
  1376. $nid = substr($tree[$key]['link']['link_path'], 5);
  1377. if (is_numeric($nid)) {
  1378. $node_links[$nid][$tree[$key]['link']['mlid']] = &$tree[$key]['link'];
  1379. $tree[$key]['link']['access'] = FALSE;
  1380. }
  1381. }
  1382. if ($tree[$key]['below']) {
  1383. menu_tree_collect_node_links($tree[$key]['below'], $node_links);
  1384. }
  1385. }
  1386. }
  1387. /**
  1388. * Checks access and performs dynamic operations for each link in the tree.
  1389. *
  1390. * @param $tree
  1391. * The menu tree you wish to operate on.
  1392. * @param $node_links
  1393. * A collection of node link references generated from $tree by
  1394. * menu_tree_collect_node_links().
  1395. */
  1396. function menu_tree_check_access(&$tree, $node_links = array()) {
  1397. if ($node_links && (user_access('access content') || user_access('bypass node access'))) {
  1398. $nids = array_keys($node_links);
  1399. $select = db_select('node', 'n');
  1400. $select->addField('n', 'nid');
  1401. $select->condition('n.status', 1);
  1402. $select->condition('n.nid', $nids, 'IN');
  1403. $select->addTag('node_access');
  1404. $nids = $select->execute()->fetchCol();
  1405. foreach ($nids as $nid) {
  1406. foreach ($node_links[$nid] as $mlid => $link) {
  1407. $node_links[$nid][$mlid]['access'] = TRUE;
  1408. }
  1409. }
  1410. }
  1411. _menu_tree_check_access($tree);
  1412. }
  1413. /**
  1414. * Sorts the menu tree and recursively checks access for each item.
  1415. */
  1416. function _menu_tree_check_access(&$tree) {
  1417. $new_tree = array();
  1418. foreach ($tree as $key => $v) {
  1419. $item = &$tree[$key]['link'];
  1420. _menu_link_translate($item);
  1421. if ($item['access'] || ($item['in_active_trail'] && strpos($item['href'], '%') !== FALSE)) {
  1422. if ($tree[$key]['below']) {
  1423. _menu_tree_check_access($tree[$key]['below']);
  1424. }
  1425. // The weights are made a uniform 5 digits by adding 50000 as an offset.
  1426. // After _menu_link_translate(), $item['title'] has the localized link title.
  1427. // Adding the mlid to the end of the index insures that it is unique.
  1428. $new_tree[(50000 + $item['weight']) . ' ' . $item['title'] . ' ' . $item['mlid']] = $tree[$key];
  1429. }
  1430. }
  1431. // Sort siblings in the tree based on the weights and localized titles.
  1432. ksort($new_tree);
  1433. $tree = $new_tree;
  1434. }
  1435. /**
  1436. * Sorts and returns the built data representing a menu tree.
  1437. *
  1438. * @param $links
  1439. * A flat array of menu links that are part of the menu. Each array element
  1440. * is an associative array of information about the menu link, containing the
  1441. * fields from the {menu_links} table, and optionally additional information
  1442. * from the {menu_router} table, if the menu item appears in both tables.
  1443. * This array must be ordered depth-first. See _menu_build_tree() for a sample
  1444. * query.
  1445. * @param $parents
  1446. * An array of the menu link ID values that are in the path from the current
  1447. * page to the root of the menu tree.
  1448. * @param $depth
  1449. * The minimum depth to include in the returned menu tree.
  1450. *
  1451. * @return
  1452. * An array of menu links in the form of a tree. Each item in the tree is an
  1453. * associative array containing:
  1454. * - link: The menu link item from $links, with additional element
  1455. * 'in_active_trail' (TRUE if the link ID was in $parents).
  1456. * - below: An array containing the sub-tree of this item, where each element
  1457. * is a tree item array with 'link' and 'below' elements. This array will be
  1458. * empty if the menu item has no items in its sub-tree having a depth
  1459. * greater than or equal to $depth.
  1460. */
  1461. function menu_tree_data(array $links, array $parents = array(), $depth = 1) {
  1462. // Reverse the array so we can use the more efficient array_pop() function.
  1463. $links = array_reverse($links);
  1464. return _menu_tree_data($links, $parents, $depth);
  1465. }
  1466. /**
  1467. * Builds the data representing a menu tree.
  1468. *
  1469. * The function is a bit complex because the rendering of a link depends on
  1470. * the next menu link.
  1471. */
  1472. function _menu_tree_data(&$links, $parents, $depth) {
  1473. $tree = array();
  1474. while ($item = array_pop($links)) {
  1475. // We need to determine if we're on the path to root so we can later build
  1476. // the correct active trail and breadcrumb.
  1477. $item['in_active_trail'] = in_array($item['mlid'], $parents);
  1478. // Add the current link to the tree.
  1479. $tree[$item['mlid']] = array(
  1480. 'link' => $item,
  1481. 'below' => array(),
  1482. );
  1483. // Look ahead to the next link, but leave it on the array so it's available
  1484. // to other recursive function calls if we return or build a sub-tree.
  1485. $next = end($links);
  1486. // Check whether the next link is the first in a new sub-tree.
  1487. if ($next && $next['depth'] > $depth) {
  1488. // Recursively call _menu_tree_data to build the sub-tree.
  1489. $tree[$item['mlid']]['below'] = _menu_tree_data($links, $parents, $next['depth']);
  1490. // Fetch next link after filling the sub-tree.
  1491. $next = end($links);
  1492. }
  1493. // Determine if we should exit the loop and return.
  1494. if (!$next || $next['depth'] < $depth) {
  1495. break;
  1496. }
  1497. }
  1498. return $tree;
  1499. }
  1500. /**
  1501. * Implements template_preprocess_HOOK() for theme_menu_tree().
  1502. */
  1503. function template_preprocess_menu_tree(&$variables) {
  1504. $variables['#tree'] = $variables['tree'];
  1505. $variables['tree'] = $variables['tree']['#children'];
  1506. }
  1507. /**
  1508. * Returns HTML for a wrapper for a menu sub-tree.
  1509. *
  1510. * @param $variables
  1511. * An associative array containing:
  1512. * - tree: An HTML string containing the tree's items.
  1513. *
  1514. * @see template_preprocess_menu_tree()
  1515. * @ingroup themeable
  1516. */
  1517. function theme_menu_tree($variables) {
  1518. return '<ul class="menu">' . $variables['tree'] . '</ul>';
  1519. }
  1520. /**
  1521. * Returns HTML for a menu link and submenu.
  1522. *
  1523. * @param $variables
  1524. * An associative array containing:
  1525. * - element: Structured array data for a menu link.
  1526. *
  1527. * @ingroup themeable
  1528. */
  1529. function theme_menu_link(array $variables) {
  1530. $element = $variables['element'];
  1531. $sub_menu = '';
  1532. if ($element['#below']) {
  1533. $sub_menu = drupal_render($element['#below']);
  1534. }
  1535. $output = l($element['#title'], $element['#href'], $element['#localized_options']);
  1536. return '<li' . drupal_attributes($element['#attributes']) . '>' . $output . $sub_menu . "</li>\n";
  1537. }
  1538. /**
  1539. * Returns HTML for a single local task link.
  1540. *
  1541. * @param $variables
  1542. * An associative array containing:
  1543. * - element: A render element containing:
  1544. * - #link: A menu link array with 'title', 'href', and 'localized_options'
  1545. * keys.
  1546. * - #active: A boolean indicating whether the local task is active.
  1547. *
  1548. * @ingroup themeable
  1549. */
  1550. function theme_menu_local_task($variables) {
  1551. $link = $variables['element']['#link'];
  1552. $link_text = $link['title'];
  1553. if (!empty($variables['element']['#active'])) {
  1554. // Add text to indicate active tab for non-visual users.
  1555. $active = '<span class="element-invisible">' . t('(active tab)') . '</span>';
  1556. // If the link does not contain HTML already, check_plain() it now.
  1557. // After we set 'html'=TRUE the link will not be sanitized by l().
  1558. if (empty($link['localized_options']['html'])) {
  1559. $link['title'] = check_plain($link['title']);
  1560. }
  1561. $link['localized_options']['html'] = TRUE;
  1562. $link_text = t('!local-task-title!active', array('!local-task-title' => $link['title'], '!active' => $active));
  1563. }
  1564. return '<li' . (!empty($variables['element']['#active']) ? ' class="active"' : '') . '>' . l($link_text, $link['href'], $link['localized_options']) . "</li>\n";
  1565. }
  1566. /**
  1567. * Returns HTML for a single local action link.
  1568. *
  1569. * @param $variables
  1570. * An associative array containing:
  1571. * - element: A render element containing:
  1572. * - #link: A menu link array with 'title', 'href', and 'localized_options'
  1573. * keys.
  1574. *
  1575. * @ingroup themeable
  1576. */
  1577. function theme_menu_local_action($variables) {
  1578. $link = $variables['element']['#link'];
  1579. $output = '<li>';
  1580. if (isset($link['href'])) {
  1581. $output .= l($link['title'], $link['href'], isset($link['localized_options']) ? $link['localized_options'] : array());
  1582. }
  1583. elseif (!empty($link['localized_options']['html'])) {
  1584. $output .= $link['title'];
  1585. }
  1586. else {
  1587. $output .= check_plain($link['title']);
  1588. }
  1589. $output .= "</li>\n";
  1590. return $output;
  1591. }
  1592. /**
  1593. * Generates elements for the $arg array in the help hook.
  1594. */
  1595. function drupal_help_arg($arg = array()) {
  1596. // Note - the number of empty elements should be > MENU_MAX_PARTS.
  1597. return $arg + array('', '', '', '', '', '', '', '', '', '', '', '');
  1598. }
  1599. /**
  1600. * Returns the help associated with the active menu item.
  1601. */
  1602. function menu_get_active_help() {
  1603. $output = '';
  1604. $router_path = menu_tab_root_path();
  1605. // We will always have a path unless we are on a 403 or 404.
  1606. if (!$router_path) {
  1607. return '';
  1608. }
  1609. $arg = drupal_help_arg(arg(NULL));
  1610. foreach (module_implements('help') as $module) {
  1611. $function = $module . '_help';
  1612. // Lookup help for this path.
  1613. if ($help = $function($router_path, $arg)) {
  1614. $output .= $help . "\n";
  1615. }
  1616. }
  1617. return $output;
  1618. }
  1619. /**
  1620. * Gets the custom theme for the current page, if there is one.
  1621. *
  1622. * @param $initialize
  1623. * This parameter should only be used internally; it is set to TRUE in order
  1624. * to force the custom theme to be initialized for the current page request.
  1625. *
  1626. * @return
  1627. * The machine-readable name of the custom theme, if there is one.
  1628. *
  1629. * @see menu_set_custom_theme()
  1630. */
  1631. function menu_get_custom_theme($initialize = FALSE) {
  1632. $custom_theme = &drupal_static(__FUNCTION__);
  1633. // Skip this if the site is offline or being installed or updated, since the
  1634. // menu system may not be correctly initialized then.
  1635. if ($initialize && !_menu_site_is_offline(TRUE) && (!defined('MAINTENANCE_MODE') || (MAINTENANCE_MODE != 'update' && MAINTENANCE_MODE != 'install'))) {
  1636. // First allow modules to dynamically set a custom theme for the current
  1637. // page. Since we can only have one, the last module to return a valid
  1638. // theme takes precedence.
  1639. $custom_themes = array_filter(module_invoke_all('custom_theme'), 'drupal_theme_access');
  1640. if (!empty($custom_themes)) {
  1641. $custom_theme = array_pop($custom_themes);
  1642. }
  1643. // If there is a theme callback function for the current page, execute it.
  1644. // If this returns a valid theme, it will override any theme that was set
  1645. // by a hook_custom_theme() implementation above.
  1646. $router_item = menu_get_item();
  1647. if (!empty($router_item['access']) && !empty($router_item['theme_callback']) && function_exists($router_item['theme_callback'])) {
  1648. $theme_name = call_user_func_array($router_item['theme_callback'], $router_item['theme_arguments']);
  1649. if (drupal_theme_access($theme_name)) {
  1650. $custom_theme = $theme_name;
  1651. }
  1652. }
  1653. }
  1654. return $custom_theme;
  1655. }
  1656. /**
  1657. * Sets a custom theme for the current page, if there is one.
  1658. */
  1659. function menu_set_custom_theme() {
  1660. menu_get_custom_theme(TRUE);
  1661. }
  1662. /**
  1663. * Build a list of named menus.
  1664. */
  1665. function menu_get_names() {
  1666. $names = &drupal_static(__FUNCTION__);
  1667. if (empty($names)) {
  1668. $names = db_select('menu_links')
  1669. ->distinct()
  1670. ->fields('menu_links', array('menu_name'))
  1671. ->orderBy('menu_name')
  1672. ->execute()->fetchCol();
  1673. }
  1674. return $names;
  1675. }
  1676. /**
  1677. * Returns an array containing the names of system-defined (default) menus.
  1678. */
  1679. function menu_list_system_menus() {
  1680. return array(
  1681. 'navigation' => 'Navigation',
  1682. 'management' => 'Management',
  1683. 'user-menu' => 'User menu',
  1684. 'main-menu' => 'Main menu',
  1685. );
  1686. }
  1687. /**
  1688. * Returns an array of links to be rendered as the Main menu.
  1689. */
  1690. function menu_main_menu() {
  1691. return menu_navigation_links(variable_get('menu_main_links_source', 'main-menu'));
  1692. }
  1693. /**
  1694. * Returns an array of links to be rendered as the Secondary links.
  1695. */
  1696. function menu_secondary_menu() {
  1697. // If the secondary menu source is set as the primary menu, we display the
  1698. // second level of the primary menu.
  1699. if (variable_get('menu_secondary_links_source', 'user-menu') == variable_get('menu_main_links_source', 'main-menu')) {
  1700. return menu_navigation_links(variable_get('menu_main_links_source', 'main-menu'), 1);
  1701. }
  1702. else {
  1703. return menu_navigation_links(variable_get('menu_secondary_links_source', 'user-menu'), 0);
  1704. }
  1705. }
  1706. /**
  1707. * Returns an array of links for a navigation menu.
  1708. *
  1709. * @param $menu_name
  1710. * The name of the menu.
  1711. * @param $level
  1712. * Optional, the depth of the menu to be returned.
  1713. *
  1714. * @return
  1715. * An array of links of the specified menu and level.
  1716. */
  1717. function menu_navigation_links($menu_name, $level = 0) {
  1718. // Don't even bother querying the menu table if no menu is specified.
  1719. if (empty($menu_name)) {
  1720. return array();
  1721. }
  1722. // Get the menu hierarchy for the current page.
  1723. $tree = menu_tree_page_data($menu_name, $level + 1);
  1724. // Go down the active trail until the right level is reached.
  1725. while ($level-- > 0 && $tree) {
  1726. // Loop through the current level's items until we find one that is in trail.
  1727. while ($item = array_shift($tree)) {
  1728. if ($item['link']['in_active_trail']) {
  1729. // If the item is in the active trail, we continue in the subtree.
  1730. $tree = empty($item['below']) ? array() : $item['below'];
  1731. break;
  1732. }
  1733. }
  1734. }
  1735. // Create a single level of links.
  1736. $router_item = menu_get_item();
  1737. $links = array();
  1738. foreach ($tree as $item) {
  1739. if (!$item['link']['hidden']) {
  1740. $class = '';
  1741. $l = $item['link']['localized_options'];
  1742. $l['href'] = $item['link']['href'];
  1743. $l['title'] = $item['link']['title'];
  1744. if ($item['link']['in_active_trail']) {
  1745. $class = ' active-trail';
  1746. $l['attributes']['class'][] = 'active-trail';
  1747. }
  1748. // Normally, l() compares the href of every link with $_GET['q'] and sets
  1749. // the active class accordingly. But local tasks do not appear in menu
  1750. // trees, so if the current path is a local task, and this link is its
  1751. // tab root, then we have to set the class manually.
  1752. if ($item['link']['href'] == $router_item['tab_root_href'] && $item['link']['href'] != $_GET['q']) {
  1753. $l['attributes']['class'][] = 'active';
  1754. }
  1755. // Keyed with the unique mlid to generate classes in theme_links().
  1756. $links['menu-' . $item['link']['mlid'] . $class] = $l;
  1757. }
  1758. }
  1759. return $links;
  1760. }
  1761. /**
  1762. * Collects the local tasks (tabs), action links, and the root path.
  1763. *
  1764. * @param $level
  1765. * The level of tasks you ask for. Primary tasks are 0, secondary are 1.
  1766. *
  1767. * @return
  1768. * An array containing
  1769. * - tabs: Local tasks for the requested level:
  1770. * - count: The number of local tasks.
  1771. * - output: The themed output of local tasks.
  1772. * - actions: Action links for the requested level:
  1773. * - count: The number of action links.
  1774. * - output: The themed output of action links.
  1775. * - root_path: The router path for the current page. If the current page is
  1776. * a default local task, then this corresponds to the parent tab.
  1777. */
  1778. function menu_local_tasks($level = 0) {
  1779. $data = &drupal_static(__FUNCTION__);
  1780. $root_path = &drupal_static(__FUNCTION__ . ':root_path', '');
  1781. $empty = array(
  1782. 'tabs' => array('count' => 0, 'output' => array()),
  1783. 'actions' => array('count' => 0, 'output' => array()),
  1784. 'root_path' => &$root_path,
  1785. );
  1786. if (!isset($data)) {
  1787. $data = array();
  1788. // Set defaults in case there are no actions or tabs.
  1789. $actions = $empty['actions'];
  1790. $tabs = array();
  1791. $router_item = menu_get_item();
  1792. // If this router item points to its parent, start from the parents to
  1793. // compute tabs and actions.
  1794. if ($router_item && ($router_item['type'] & MENU_LINKS_TO_PARENT)) {
  1795. $router_item = menu_get_item($router_item['tab_parent_href']);
  1796. }
  1797. // If we failed to fetch a router item or the current user doesn't have
  1798. // access to it, don't bother computing the tabs.
  1799. if (!$router_item || !$router_item['access']) {
  1800. return $empty;
  1801. }
  1802. // Get all tabs (also known as local tasks) and the root page.
  1803. $cid = 'local_tasks:' . $router_item['tab_root'];
  1804. if ($cache = cache_get($cid, 'cache_menu')) {
  1805. $result = $cache->data;
  1806. }
  1807. else {
  1808. $result = db_select('menu_router', NULL, array('fetch' => PDO::FETCH_ASSOC))
  1809. ->fields('menu_router')
  1810. ->condition('tab_root', $router_item['tab_root'])
  1811. ->condition('context', MENU_CONTEXT_INLINE, '<>')
  1812. ->orderBy('weight')
  1813. ->orderBy('title')
  1814. ->execute()
  1815. ->fetchAll();
  1816. cache_set($cid, $result, 'cache_menu');
  1817. }
  1818. $map = $router_item['original_map'];
  1819. $children = array();
  1820. $tasks = array();
  1821. $root_path = $router_item['path'];
  1822. foreach ($result as $item) {
  1823. _menu_translate($item, $map, TRUE);
  1824. if ($item['tab_parent']) {
  1825. // All tabs, but not the root page.
  1826. $children[$item['tab_parent']][$item['path']] = $item;
  1827. }
  1828. // Store the translated item for later use.
  1829. $tasks[$item['path']] = $item;
  1830. }
  1831. // Find all tabs below the current path.
  1832. $path = $router_item['path'];
  1833. // Tab parenting may skip levels, so the number of parts in the path may not
  1834. // equal the depth. Thus we use the $depth counter (offset by 1000 for ksort).
  1835. $depth = 1001;
  1836. $actions['count'] = 0;
  1837. $actions['output'] = array();
  1838. while (isset($children[$path])) {
  1839. $tabs_current = array();
  1840. $actions_current = array();
  1841. $next_path = '';
  1842. $tab_count = 0;
  1843. $action_count = 0;
  1844. foreach ($children[$path] as $item) {
  1845. // Local tasks can be normal items too, so bitmask with
  1846. // MENU_IS_LOCAL_TASK before checking.
  1847. if (!($item['type'] & MENU_IS_LOCAL_TASK)) {
  1848. // This item is not a tab, skip it.
  1849. continue;
  1850. }
  1851. if ($item['access']) {
  1852. $link = $item;
  1853. // The default task is always active. As tabs can be normal items
  1854. // too, so bitmask with MENU_LINKS_TO_PARENT before checking.
  1855. if (($item['type'] & MENU_LINKS_TO_PARENT) == MENU_LINKS_TO_PARENT) {
  1856. // Find the first parent which is not a default local task or action.
  1857. for ($p = $item['tab_parent']; ($tasks[$p]['type'] & MENU_LINKS_TO_PARENT) == MENU_LINKS_TO_PARENT; $p = $tasks[$p]['tab_parent']);
  1858. // Use the path of the parent instead.
  1859. $link['href'] = $tasks[$p]['href'];
  1860. // Mark the link as active, if the current path happens to be the
  1861. // path of the default local task itself (i.e., instead of its
  1862. // tab_parent_href or tab_root_href). Normally, links for default
  1863. // local tasks link to their parent, but the path of default local
  1864. // tasks can still be accessed directly, in which case this link
  1865. // would not be marked as active, since l() only compares the href
  1866. // with $_GET['q'].
  1867. if ($link['href'] != $_GET['q']) {
  1868. $link['localized_options']['attributes']['class'][] = 'active';
  1869. }
  1870. $tabs_current[] = array(
  1871. '#theme' => 'menu_local_task',
  1872. '#link' => $link,
  1873. '#active' => TRUE,
  1874. );
  1875. $next_path = $item['path'];
  1876. $tab_count++;
  1877. }
  1878. else {
  1879. // Actions can be normal items too, so bitmask with
  1880. // MENU_IS_LOCAL_ACTION before checking.
  1881. if (($item['type'] & MENU_IS_LOCAL_ACTION) == MENU_IS_LOCAL_ACTION) {
  1882. // The item is an action, display it as such.
  1883. $actions_current[] = array(
  1884. '#theme' => 'menu_local_action',
  1885. '#link' => $link,
  1886. );
  1887. $action_count++;
  1888. }
  1889. else {
  1890. // Otherwise, it's a normal tab.
  1891. $tabs_current[] = array(
  1892. '#theme' => 'menu_local_task',
  1893. '#link' => $link,
  1894. );
  1895. $tab_count++;
  1896. }
  1897. }
  1898. }
  1899. }
  1900. $path = $next_path;
  1901. $tabs[$depth]['count'] = $tab_count;
  1902. $tabs[$depth]['output'] = $tabs_current;
  1903. $actions['count'] += $action_count;
  1904. $actions['output'] = array_merge($actions['output'], $actions_current);
  1905. $depth++;
  1906. }
  1907. $data['actions'] = $actions;
  1908. // Find all tabs at the same level or above the current one.
  1909. $parent = $router_item['tab_parent'];
  1910. $path = $router_item['path'];
  1911. $current = $router_item;
  1912. $depth = 1000;
  1913. while (isset($children[$parent])) {
  1914. $tabs_current = array();
  1915. $next_path = '';
  1916. $next_parent = '';
  1917. $count = 0;
  1918. foreach ($children[$parent] as $item) {
  1919. // Skip local actions.
  1920. if ($item['type'] & MENU_IS_LOCAL_ACTION) {
  1921. continue;
  1922. }
  1923. if ($item['access']) {
  1924. $count++;
  1925. $link = $item;
  1926. // Local tasks can be normal items too, so bitmask with
  1927. // MENU_LINKS_TO_PARENT before checking.
  1928. if (($item['type'] & MENU_LINKS_TO_PARENT) == MENU_LINKS_TO_PARENT) {
  1929. // Find the first parent which is not a default local task.
  1930. for ($p = $item['tab_parent']; ($tasks[$p]['type'] & MENU_LINKS_TO_PARENT) == MENU_LINKS_TO_PARENT; $p = $tasks[$p]['tab_parent']);
  1931. // Use the path of the parent instead.
  1932. $link['href'] = $tasks[$p]['href'];
  1933. if ($item['path'] == $router_item['path']) {
  1934. $root_path = $tasks[$p]['path'];
  1935. }
  1936. }
  1937. // We check for the active tab.
  1938. if ($item['path'] == $path) {
  1939. // Mark the link as active, if the current path is a (second-level)
  1940. // local task of a default local task. Since this default local task
  1941. // links to its parent, l() will not mark it as active, as it only
  1942. // compares the link's href to $_GET['q'].
  1943. if ($link['href'] != $_GET['q']) {
  1944. $link['localized_options']['attributes']['class'][] = 'active';
  1945. }
  1946. $tabs_current[] = array(
  1947. '#theme' => 'menu_local_task',
  1948. '#link' => $link,
  1949. '#active' => TRUE,
  1950. );
  1951. $next_path = $item['tab_parent'];
  1952. if (isset($tasks[$next_path])) {
  1953. $next_parent = $tasks[$next_path]['tab_parent'];
  1954. }
  1955. }
  1956. else {
  1957. $tabs_current[] = array(
  1958. '#theme' => 'menu_local_task',
  1959. '#link' => $link,
  1960. );
  1961. }
  1962. }
  1963. }
  1964. $path = $next_path;
  1965. $parent = $next_parent;
  1966. $tabs[$depth]['count'] = $count;
  1967. $tabs[$depth]['output'] = $tabs_current;
  1968. $depth--;
  1969. }
  1970. // Sort by depth.
  1971. ksort($tabs);
  1972. // Remove the depth, we are interested only in their relative placement.
  1973. $tabs = array_values($tabs);
  1974. $data['tabs'] = $tabs;
  1975. // Allow modules to alter local tasks or dynamically append further tasks.
  1976. drupal_alter('menu_local_tasks', $data, $router_item, $root_path);
  1977. }
  1978. if (isset($data['tabs'][$level])) {
  1979. return array(
  1980. 'tabs' => $data['tabs'][$level],
  1981. 'actions' => $data['actions'],
  1982. 'root_path' => $root_path,
  1983. );
  1984. }
  1985. // @todo If there are no tabs, then there still can be actions; for example,
  1986. // when added via hook_menu_local_tasks_alter().
  1987. elseif (!empty($data['actions']['output'])) {
  1988. return array('actions' => $data['actions']) + $empty;
  1989. }
  1990. return $empty;
  1991. }
  1992. /**
  1993. * Retrieves contextual links for a path based on registered local tasks.
  1994. *
  1995. * This leverages the menu system to retrieve the first layer of registered
  1996. * local tasks for a given system path. All local tasks of the tab type
  1997. * MENU_CONTEXT_INLINE are taken into account.
  1998. *
  1999. * For example, when considering the following registered local tasks:
  2000. * - node/%node/view (default local task) with no 'context' defined
  2001. * - node/%node/edit with context: MENU_CONTEXT_PAGE | MENU_CONTEXT_INLINE
  2002. * - node/%node/revisions with context: MENU_CONTEXT_PAGE
  2003. * - node/%node/report-as-spam with context: MENU_CONTEXT_INLINE
  2004. *
  2005. * If the path "node/123" is passed to this function, then it will return the
  2006. * links for 'edit' and 'report-as-spam'.
  2007. *
  2008. * @param $module
  2009. * The name of the implementing module. This is used to prefix the key for
  2010. * each contextual link, which is transformed into a CSS class during
  2011. * rendering by theme_links(). For example, if $module is 'block' and the
  2012. * retrieved local task path argument is 'edit', then the resulting CSS class
  2013. * will be 'block-edit'.
  2014. * @param $parent_path
  2015. * The static menu router path of the object to retrieve local tasks for, for
  2016. * example 'node' or 'admin/structure/block/manage'.
  2017. * @param $args
  2018. * A list of dynamic path arguments to append to $parent_path to form the
  2019. * fully-qualified menu router path; for example, array(123) for a certain
  2020. * node or array('system', 'navigation') for a certain block.
  2021. *
  2022. * @return
  2023. * A list of menu router items that are local tasks for the passed-in path.
  2024. *
  2025. * @see contextual_links_preprocess()
  2026. * @see hook_menu()
  2027. */
  2028. function menu_contextual_links($module, $parent_path, $args) {
  2029. static $path_empty = array();
  2030. $links = array();
  2031. // Performance: In case a previous invocation for the same parent path did not
  2032. // return any links, we immediately return here.
  2033. if (isset($path_empty[$parent_path]) && strpos($parent_path, '%') !== FALSE) {
  2034. return $links;
  2035. }
  2036. // Construct the item-specific parent path.
  2037. $path = $parent_path . '/' . implode('/', $args);
  2038. // Get the router item for the given parent link path.
  2039. $router_item = menu_get_item($path);
  2040. if (!$router_item || !$router_item['access']) {
  2041. $path_empty[$parent_path] = TRUE;
  2042. return $links;
  2043. }
  2044. $data = &drupal_static(__FUNCTION__, array());
  2045. $root_path = $router_item['path'];
  2046. // Performance: For a single, normalized path (such as 'node/%') we only query
  2047. // available tasks once per request.
  2048. if (!isset($data[$root_path])) {
  2049. // Get all contextual links that are direct children of the router item and
  2050. // not of the tab type 'view'.
  2051. $data[$root_path] = db_select('menu_router', 'm')
  2052. ->fields('m')
  2053. ->condition('tab_parent', $router_item['tab_root'])
  2054. ->condition('context', MENU_CONTEXT_NONE, '<>')
  2055. ->condition('context', MENU_CONTEXT_PAGE, '<>')
  2056. ->orderBy('weight')
  2057. ->orderBy('title')
  2058. ->execute()
  2059. ->fetchAllAssoc('path', PDO::FETCH_ASSOC);
  2060. }
  2061. $parent_length = drupal_strlen($root_path) + 1;
  2062. $map = $router_item['original_map'];
  2063. foreach ($data[$root_path] as $item) {
  2064. // Extract the actual "task" string from the path argument.
  2065. $key = drupal_substr($item['path'], $parent_length);
  2066. // Denormalize and translate the contextual link.
  2067. _menu_translate($item, $map, TRUE);
  2068. if (!$item['access']) {
  2069. continue;
  2070. }
  2071. // All contextual links are keyed by the actual "task" path argument,
  2072. // prefixed with the name of the implementing module.
  2073. $links[$module . '-' . $key] = $item;
  2074. }
  2075. // Allow modules to alter contextual links.
  2076. drupal_alter('menu_contextual_links', $links, $router_item, $root_path);
  2077. // Performance: If the current user does not have access to any links for this
  2078. // router path and no other module added further links, we assign FALSE here
  2079. // to skip the entire process the next time the same router path is requested.
  2080. if (empty($links)) {
  2081. $path_empty[$parent_path] = TRUE;
  2082. }
  2083. return $links;
  2084. }
  2085. /**
  2086. * Returns the rendered local tasks at the top level.
  2087. */
  2088. function menu_primary_local_tasks() {
  2089. $links = menu_local_tasks(0);
  2090. // Do not display single tabs.
  2091. return ($links['tabs']['count'] > 1 ? $links['tabs']['output'] : '');
  2092. }
  2093. /**
  2094. * Returns the rendered local tasks at the second level.
  2095. */
  2096. function menu_secondary_local_tasks() {
  2097. $links = menu_local_tasks(1);
  2098. // Do not display single tabs.
  2099. return ($links['tabs']['count'] > 1 ? $links['tabs']['output'] : '');
  2100. }
  2101. /**
  2102. * Returns the rendered local actions at the current level.
  2103. */
  2104. function menu_local_actions() {
  2105. $links = menu_local_tasks();
  2106. return $links['actions']['output'];
  2107. }
  2108. /**
  2109. * Returns the router path, or the path for a default local task's parent.
  2110. */
  2111. function menu_tab_root_path() {
  2112. $links = menu_local_tasks();
  2113. return $links['root_path'];
  2114. }
  2115. /**
  2116. * Returns a renderable element for the primary and secondary tabs.
  2117. */
  2118. function menu_local_tabs() {
  2119. return array(
  2120. '#theme' => 'menu_local_tasks',
  2121. '#primary' => menu_primary_local_tasks(),
  2122. '#secondary' => menu_secondary_local_tasks(),
  2123. );
  2124. }
  2125. /**
  2126. * Returns HTML for primary and secondary local tasks.
  2127. *
  2128. * @param $variables
  2129. * An associative array containing:
  2130. * - primary: (optional) An array of local tasks (tabs).
  2131. * - secondary: (optional) An array of local tasks (tabs).
  2132. *
  2133. * @ingroup themeable
  2134. * @see menu_local_tasks()
  2135. */
  2136. function theme_menu_local_tasks(&$variables) {
  2137. $output = '';
  2138. if (!empty($variables['primary'])) {
  2139. $variables['primary']['#prefix'] = '<h2 class="element-invisible">' . t('Primary tabs') . '</h2>';
  2140. $variables['primary']['#prefix'] .= '<ul class="tabs primary">';
  2141. $variables['primary']['#suffix'] = '</ul>';
  2142. $output .= drupal_render($variables['primary']);
  2143. }
  2144. if (!empty($variables['secondary'])) {
  2145. $variables['secondary']['#prefix'] = '<h2 class="element-invisible">' . t('Secondary tabs') . '</h2>';
  2146. $variables['secondary']['#prefix'] .= '<ul class="tabs secondary">';
  2147. $variables['secondary']['#suffix'] = '</ul>';
  2148. $output .= drupal_render($variables['secondary']);
  2149. }
  2150. return $output;
  2151. }
  2152. /**
  2153. * Sets (or gets) the active menu for the current page.
  2154. *
  2155. * The active menu for the page determines the active trail.
  2156. *
  2157. * @return
  2158. * An array of menu machine names, in order of preference. The
  2159. * 'menu_default_active_menus' variable may be used to assert a menu order
  2160. * different from the order of creation, or to prevent a particular menu from
  2161. * being used at all in the active trail.
  2162. * E.g., $conf['menu_default_active_menus'] = array('navigation', 'main-menu')
  2163. */
  2164. function menu_set_active_menu_names($menu_names = NULL) {
  2165. $active = &drupal_static(__FUNCTION__);
  2166. if (isset($menu_names) && is_array($menu_names)) {
  2167. $active = $menu_names;
  2168. }
  2169. elseif (!isset($active)) {
  2170. $active = variable_get('menu_default_active_menus', array_keys(menu_list_system_menus()));
  2171. }
  2172. return $active;
  2173. }
  2174. /**
  2175. * Gets the active menu for the current page.
  2176. */
  2177. function menu_get_active_menu_names() {
  2178. return menu_set_active_menu_names();
  2179. }
  2180. /**
  2181. * Sets the active path, which determines which page is loaded.
  2182. *
  2183. * Note that this may not have the desired effect unless invoked very early
  2184. * in the page load, such as during hook_boot(), or unless you call
  2185. * menu_execute_active_handler() to generate your page output.
  2186. *
  2187. * @param $path
  2188. * A Drupal path - not a path alias.
  2189. */
  2190. function menu_set_active_item($path) {
  2191. $_GET['q'] = $path;
  2192. // Since the active item has changed, the active menu trail may also be out
  2193. // of date.
  2194. drupal_static_reset('menu_set_active_trail');
  2195. }
  2196. /**
  2197. * Sets the active trail (path to the menu tree root) of the current page.
  2198. *
  2199. * Any trail set by this function will only be used for functionality that calls
  2200. * menu_get_active_trail(). Drupal core only uses trails set here for
  2201. * breadcrumbs and the page title and not for menu trees or page content.
  2202. * Additionally, breadcrumbs set by drupal_set_breadcrumb() will override any
  2203. * trail set here.
  2204. *
  2205. * To affect the trail used by menu trees, use menu_tree_set_path(). To affect
  2206. * the page content, use menu_set_active_item() instead.
  2207. *
  2208. * @param $new_trail
  2209. * Menu trail to set; the value is saved in a static variable and can be
  2210. * retrieved by menu_get_active_trail(). The format of this array should be
  2211. * the same as the return value of menu_get_active_trail().
  2212. *
  2213. * @return
  2214. * The active trail. See menu_get_active_trail() for details.
  2215. */
  2216. function menu_set_active_trail($new_trail = NULL) {
  2217. $trail = &drupal_static(__FUNCTION__);
  2218. if (isset($new_trail)) {
  2219. $trail = $new_trail;
  2220. }
  2221. elseif (!isset($trail)) {
  2222. $trail = array();
  2223. $trail[] = array(
  2224. 'title' => t('Home'),
  2225. 'href' => '<front>',
  2226. 'link_path' => '',
  2227. 'localized_options' => array(),
  2228. 'type' => 0,
  2229. );
  2230. // Try to retrieve a menu link corresponding to the current path. If more
  2231. // than one exists, the link from the most preferred menu is returned.
  2232. $preferred_link = menu_link_get_preferred();
  2233. $current_item = menu_get_item();
  2234. // There is a link for the current path.
  2235. if ($preferred_link) {
  2236. // Pass TRUE for $only_active_trail to make menu_tree_page_data() build
  2237. // a stripped down menu tree containing the active trail only, in case
  2238. // the given menu has not been built in this request yet.
  2239. $tree = menu_tree_page_data($preferred_link['menu_name'], NULL, TRUE);
  2240. list($key, $curr) = each($tree);
  2241. }
  2242. // There is no link for the current path.
  2243. else {
  2244. $preferred_link = $current_item;
  2245. $curr = FALSE;
  2246. }
  2247. while ($curr) {
  2248. $link = $curr['link'];
  2249. if ($link['in_active_trail']) {
  2250. // Add the link to the trail, unless it links to its parent.
  2251. if (!($link['type'] & MENU_LINKS_TO_PARENT)) {
  2252. // The menu tree for the active trail may contain additional links
  2253. // that have not been translated yet, since they contain dynamic
  2254. // argument placeholders (%). Such links are not contained in regular
  2255. // menu trees, and have only been loaded for the additional
  2256. // translation that happens here, so as to be able to display them in
  2257. // the breadcrumb for the current page.
  2258. // @see _menu_tree_check_access()
  2259. // @see _menu_link_translate()
  2260. if (strpos($link['href'], '%') !== FALSE) {
  2261. _menu_link_translate($link, TRUE);
  2262. }
  2263. if ($link['access']) {
  2264. $trail[] = $link;
  2265. }
  2266. }
  2267. $tree = $curr['below'] ? $curr['below'] : array();
  2268. }
  2269. list($key, $curr) = each($tree);
  2270. }
  2271. // Make sure the current page is in the trail to build the page title, by
  2272. // appending either the preferred link or the menu router item for the
  2273. // current page. Exclude it if we are on the front page.
  2274. $last = end($trail);
  2275. if ($preferred_link && $last['href'] != $preferred_link['href'] && !drupal_is_front_page()) {
  2276. $trail[] = $preferred_link;
  2277. }
  2278. }
  2279. return $trail;
  2280. }
  2281. /**
  2282. * Looks up the preferred menu link for a given system path.
  2283. *
  2284. * @param $path
  2285. * The path; for example, 'node/5'. The function will find the corresponding
  2286. * menu link ('node/5' if it exists, or fallback to 'node/%').
  2287. * @param $selected_menu
  2288. * The name of a menu used to restrict the search for a preferred menu link.
  2289. * If not specified, all the menus returned by menu_get_active_menu_names()
  2290. * will be used.
  2291. *
  2292. * @return
  2293. * A fully translated menu link, or FALSE if no matching menu link was
  2294. * found. The most specific menu link ('node/5' preferred over 'node/%') in
  2295. * the most preferred menu (as defined by menu_get_active_menu_names()) is
  2296. * returned.
  2297. */
  2298. function menu_link_get_preferred($path = NULL, $selected_menu = NULL) {
  2299. $preferred_links = &drupal_static(__FUNCTION__);
  2300. if (!isset($path)) {
  2301. $path = $_GET['q'];
  2302. }
  2303. if (empty($selected_menu)) {
  2304. // Use an illegal menu name as the key for the preferred menu link.
  2305. $selected_menu = MENU_PREFERRED_LINK;
  2306. }
  2307. if (!isset($preferred_links[$path])) {
  2308. // Look for the correct menu link by building a list of candidate paths,
  2309. // which are ordered by priority (translated hrefs are preferred over
  2310. // untranslated paths). Afterwards, the most relevant path is picked from
  2311. // the menus, ordered by menu preference.
  2312. $item = menu_get_item($path);
  2313. $path_candidates = array();
  2314. // 1. The current item href.
  2315. $path_candidates[$item['href']] = $item['href'];
  2316. // 2. The tab root href of the current item (if any).
  2317. if ($item['tab_parent'] && ($tab_root = menu_get_item($item['tab_root_href']))) {
  2318. $path_candidates[$tab_root['href']] = $tab_root['href'];
  2319. }
  2320. // 3. The current item path (with wildcards).
  2321. $path_candidates[$item['path']] = $item['path'];
  2322. // 4. The tab root path of the current item (if any).
  2323. if (!empty($tab_root)) {
  2324. $path_candidates[$tab_root['path']] = $tab_root['path'];
  2325. }
  2326. // Retrieve a list of menu names, ordered by preference.
  2327. $menu_names = menu_get_active_menu_names();
  2328. // Put the selected menu at the front of the list.
  2329. array_unshift($menu_names, $selected_menu);
  2330. $query = db_select('menu_links', 'ml', array('fetch' => PDO::FETCH_ASSOC));
  2331. $query->leftJoin('menu_router', 'm', 'm.path = ml.router_path');
  2332. $query->fields('ml');
  2333. // Weight must be taken from {menu_links}, not {menu_router}.
  2334. $query->addField('ml', 'weight', 'link_weight');
  2335. $query->fields('m');
  2336. $query->condition('ml.link_path', $path_candidates, 'IN');
  2337. $query->addTag('preferred_menu_links');
  2338. // Sort candidates by link path and menu name.
  2339. $candidates = array();
  2340. foreach ($query->execute() as $candidate) {
  2341. $candidate['weight'] = $candidate['link_weight'];
  2342. $candidates[$candidate['link_path']][$candidate['menu_name']] = $candidate;
  2343. // Add any menus not already in the menu name search list.
  2344. if (!in_array($candidate['menu_name'], $menu_names)) {
  2345. $menu_names[] = $candidate['menu_name'];
  2346. }
  2347. }
  2348. // Store the most specific link for each menu. Also save the most specific
  2349. // link of the most preferred menu in $preferred_link.
  2350. foreach ($path_candidates as $link_path) {
  2351. if (isset($candidates[$link_path])) {
  2352. foreach ($menu_names as $menu_name) {
  2353. if (empty($preferred_links[$path][$menu_name]) && isset($candidates[$link_path][$menu_name])) {
  2354. $candidate_item = $candidates[$link_path][$menu_name];
  2355. $map = explode('/', $path);
  2356. _menu_translate($candidate_item, $map);
  2357. if ($candidate_item['access']) {
  2358. $preferred_links[$path][$menu_name] = $candidate_item;
  2359. if (empty($preferred_links[$path][MENU_PREFERRED_LINK])) {
  2360. // Store the most specific link.
  2361. $preferred_links[$path][MENU_PREFERRED_LINK] = $candidate_item;
  2362. }
  2363. }
  2364. }
  2365. }
  2366. }
  2367. }
  2368. }
  2369. return isset($preferred_links[$path][$selected_menu]) ? $preferred_links[$path][$selected_menu] : FALSE;
  2370. }
  2371. /**
  2372. * Gets the active trail (path to root menu root) of the current page.
  2373. *
  2374. * If a trail is supplied to menu_set_active_trail(), that value is returned. If
  2375. * a trail is not supplied to menu_set_active_trail(), the path to the current
  2376. * page is calculated and returned. The calculated trail is also saved as a
  2377. * static value for use by subsequent calls to menu_get_active_trail().
  2378. *
  2379. * @return
  2380. * Path to menu root of the current page, as an array of menu link items,
  2381. * starting with the site's home page. Each link item is an associative array
  2382. * with the following components:
  2383. * - title: Title of the item.
  2384. * - href: Drupal path of the item.
  2385. * - localized_options: Options for passing into the l() function.
  2386. * - type: A menu type constant, such as MENU_DEFAULT_LOCAL_TASK, or 0 to
  2387. * indicate it's not really in the menu (used for the home page item).
  2388. */
  2389. function menu_get_active_trail() {
  2390. return menu_set_active_trail();
  2391. }
  2392. /**
  2393. * Gets the breadcrumb for the current page, as determined by the active trail.
  2394. *
  2395. * @see menu_set_active_trail()
  2396. */
  2397. function menu_get_active_breadcrumb() {
  2398. $breadcrumb = array();
  2399. // No breadcrumb for the front page.
  2400. if (drupal_is_front_page()) {
  2401. return $breadcrumb;
  2402. }
  2403. $item = menu_get_item();
  2404. if (!empty($item['access'])) {
  2405. $active_trail = menu_get_active_trail();
  2406. // Allow modules to alter the breadcrumb, if possible, as that is much
  2407. // faster than rebuilding an entirely new active trail.
  2408. drupal_alter('menu_breadcrumb', $active_trail, $item);
  2409. // Don't show a link to the current page in the breadcrumb trail.
  2410. $end = end($active_trail);
  2411. if ($item['href'] == $end['href']) {
  2412. array_pop($active_trail);
  2413. }
  2414. // Remove the tab root (parent) if the current path links to its parent.
  2415. // Normally, the tab root link is included in the breadcrumb, as soon as we
  2416. // are on a local task or any other child link. However, if we are on a
  2417. // default local task (e.g., node/%/view), then we do not want the tab root
  2418. // link (e.g., node/%) to appear, as it would be identical to the current
  2419. // page. Since this behavior also needs to work recursively (i.e., on
  2420. // default local tasks of default local tasks), and since the last non-task
  2421. // link in the trail is used as page title (see menu_get_active_title()),
  2422. // this condition cannot be cleanly integrated into menu_get_active_trail().
  2423. // menu_get_active_trail() already skips all links that link to their parent
  2424. // (commonly MENU_DEFAULT_LOCAL_TASK). In order to also hide the parent link
  2425. // itself, we always remove the last link in the trail, if the current
  2426. // router item links to its parent.
  2427. if (($item['type'] & MENU_LINKS_TO_PARENT) == MENU_LINKS_TO_PARENT) {
  2428. array_pop($active_trail);
  2429. }
  2430. foreach ($active_trail as $parent) {
  2431. $breadcrumb[] = l($parent['title'], $parent['href'], $parent['localized_options']);
  2432. }
  2433. }
  2434. return $breadcrumb;
  2435. }
  2436. /**
  2437. * Gets the title of the current page, as determined by the active trail.
  2438. */
  2439. function menu_get_active_title() {
  2440. $active_trail = menu_get_active_trail();
  2441. $local_task_title = NULL;
  2442. foreach (array_reverse($active_trail) as $item) {
  2443. // Local task titles are displayed as tabs and therefore should not be
  2444. // repeated as the page title. However, if the local task appears in a
  2445. // top-level menu, it is no longer a "local task" anymore (the front page
  2446. // of the site does not have tabs) so it is better to use the local task
  2447. // title in that case than to fall back on the front page link in the
  2448. // active trail (which is usually "Home" and would not make sense in this
  2449. // context).
  2450. if ((bool) ($item['type'] & MENU_IS_LOCAL_TASK)) {
  2451. // A local task title is being skipped; track it in case it needs to be
  2452. // used later.
  2453. $local_task_title = $item['title'];
  2454. }
  2455. else {
  2456. // This is not a local task, so use it for the page title (unless the
  2457. // conditions described above are met).
  2458. if (isset($local_task_title) && isset($item['href']) && $item['href'] == '<front>') {
  2459. return $local_task_title;
  2460. }
  2461. else {
  2462. return $item['title'];
  2463. }
  2464. }
  2465. }
  2466. }
  2467. /**
  2468. * Gets a translated, access-checked menu link that is ready for rendering.
  2469. *
  2470. * This function should never be called from within node_load() or any other
  2471. * function used as a menu object load function since an infinite recursion may
  2472. * occur.
  2473. *
  2474. * @param $mlid
  2475. * The mlid of the menu item.
  2476. *
  2477. * @return
  2478. * A menu link, with $item['access'] filled and link translated for
  2479. * rendering.
  2480. */
  2481. function menu_link_load($mlid) {
  2482. if (is_numeric($mlid)) {
  2483. $query = db_select('menu_links', 'ml');
  2484. $query->leftJoin('menu_router', 'm', 'm.path = ml.router_path');
  2485. $query->fields('ml');
  2486. // Weight should be taken from {menu_links}, not {menu_router}.
  2487. $query->addField('ml', 'weight', 'link_weight');
  2488. $query->fields('m');
  2489. $query->condition('ml.mlid', $mlid);
  2490. if ($item = $query->execute()->fetchAssoc()) {
  2491. $item['weight'] = $item['link_weight'];
  2492. _menu_link_translate($item);
  2493. return $item;
  2494. }
  2495. }
  2496. return FALSE;
  2497. }
  2498. /**
  2499. * Clears the cached data for a single named menu.
  2500. */
  2501. function menu_cache_clear($menu_name = 'navigation') {
  2502. $cache_cleared = &drupal_static(__FUNCTION__, array());
  2503. if (empty($cache_cleared[$menu_name])) {
  2504. cache_clear_all('links:' . $menu_name . ':', 'cache_menu', TRUE);
  2505. $cache_cleared[$menu_name] = 1;
  2506. }
  2507. elseif ($cache_cleared[$menu_name] == 1) {
  2508. drupal_register_shutdown_function('cache_clear_all', 'links:' . $menu_name . ':', 'cache_menu', TRUE);
  2509. $cache_cleared[$menu_name] = 2;
  2510. }
  2511. // Also clear the menu system static caches.
  2512. menu_reset_static_cache();
  2513. }
  2514. /**
  2515. * Clears all cached menu data.
  2516. *
  2517. * This should be called any time broad changes
  2518. * might have been made to the router items or menu links.
  2519. */
  2520. function menu_cache_clear_all() {
  2521. cache_clear_all('*', 'cache_menu', TRUE);
  2522. menu_reset_static_cache();
  2523. }
  2524. /**
  2525. * Resets the menu system static cache.
  2526. */
  2527. function menu_reset_static_cache() {
  2528. drupal_static_reset('_menu_build_tree');
  2529. drupal_static_reset('menu_tree');
  2530. drupal_static_reset('menu_tree_all_data');
  2531. drupal_static_reset('menu_tree_page_data');
  2532. drupal_static_reset('menu_load_all');
  2533. drupal_static_reset('menu_link_get_preferred');
  2534. }
  2535. /**
  2536. * Checks whether a menu_rebuild() is necessary.
  2537. */
  2538. function _menu_check_rebuild() {
  2539. // To absolutely ensure that the menu rebuild is required, re-load the
  2540. // variables in case they were set by another process.
  2541. $variables = variable_initialize();
  2542. if (empty($variables['menu_rebuild_needed']) && !empty($variables['menu_masks'])) {
  2543. unset($GLOBALS['conf']['menu_rebuild_needed']);
  2544. $GLOBALS['conf']['menu_masks'] = $variables['menu_masks'];
  2545. return FALSE;
  2546. }
  2547. return TRUE;
  2548. }
  2549. /**
  2550. * Populates the database tables used by various menu functions.
  2551. *
  2552. * This function will clear and populate the {menu_router} table, add entries
  2553. * to {menu_links} for new router items, and then remove stale items from
  2554. * {menu_links}. If called from update.php or install.php, it will also
  2555. * schedule a call to itself on the first real page load from
  2556. * menu_execute_active_handler(), because the maintenance page environment
  2557. * is different and leaves stale data in the menu tables.
  2558. *
  2559. * @return
  2560. * TRUE if the menu was rebuilt, FALSE if another thread was rebuilding
  2561. * in parallel and the current thread just waited for completion.
  2562. */
  2563. function menu_rebuild() {
  2564. if (!lock_acquire('menu_rebuild')) {
  2565. // Wait for another request that is already doing this work.
  2566. // We choose to block here since otherwise the router item may not
  2567. // be available in menu_execute_active_handler() resulting in a 404.
  2568. lock_wait('menu_rebuild');
  2569. if (_menu_check_rebuild()) {
  2570. // If we get here and menu_masks was not set, then it is possible a menu
  2571. // is being reloaded, or that the process rebuilding the menu was unable
  2572. // to complete successfully. A missing menu_masks variable could result
  2573. // in a 404, so re-run the function.
  2574. return menu_rebuild();
  2575. }
  2576. return FALSE;
  2577. }
  2578. $transaction = db_transaction();
  2579. try {
  2580. list($menu, $masks) = menu_router_build();
  2581. _menu_router_save($menu, $masks);
  2582. _menu_navigation_links_rebuild($menu);
  2583. // Clear the menu, page and block caches.
  2584. menu_cache_clear_all();
  2585. _menu_clear_page_cache();
  2586. if (defined('MAINTENANCE_MODE')) {
  2587. variable_set('menu_rebuild_needed', TRUE);
  2588. }
  2589. else {
  2590. variable_del('menu_rebuild_needed');
  2591. }
  2592. }
  2593. catch (Exception $e) {
  2594. $transaction->rollback();
  2595. watchdog_exception('menu', $e);
  2596. }
  2597. // Explicitly commit the transaction now; this ensures that the database
  2598. // operations during the menu rebuild are committed before the lock is made
  2599. // available again, since locks may not always reside in the same database
  2600. // connection. The lock is acquired outside of the transaction so should also
  2601. // be released outside of it.
  2602. unset($transaction);
  2603. lock_release('menu_rebuild');
  2604. return TRUE;
  2605. }
  2606. /**
  2607. * Collects and alters the menu definitions.
  2608. */
  2609. function menu_router_build() {
  2610. // We need to manually call each module so that we can know which module
  2611. // a given item came from.
  2612. $callbacks = array();
  2613. foreach (module_implements('menu') as $module) {
  2614. $router_items = call_user_func($module . '_menu');
  2615. if (isset($router_items) && is_array($router_items)) {
  2616. foreach (array_keys($router_items) as $path) {
  2617. $router_items[$path]['module'] = $module;
  2618. }
  2619. $callbacks = array_merge($callbacks, $router_items);
  2620. }
  2621. }
  2622. // Alter the menu as defined in modules, keys are like user/%user.
  2623. drupal_alter('menu', $callbacks);
  2624. list($menu, $masks) = _menu_router_build($callbacks);
  2625. _menu_router_cache($menu);
  2626. return array($menu, $masks);
  2627. }
  2628. /**
  2629. * Stores the menu router if we have it in memory.
  2630. */
  2631. function _menu_router_cache($new_menu = NULL) {
  2632. $menu = &drupal_static(__FUNCTION__);
  2633. if (isset($new_menu)) {
  2634. $menu = $new_menu;
  2635. }
  2636. return $menu;
  2637. }
  2638. /**
  2639. * Gets the menu router.
  2640. */
  2641. function menu_get_router() {
  2642. // Check first if we have it in memory already.
  2643. $menu = _menu_router_cache();
  2644. if (empty($menu)) {
  2645. list($menu, $masks) = menu_router_build();
  2646. }
  2647. return $menu;
  2648. }
  2649. /**
  2650. * Builds a link from a router item.
  2651. */
  2652. function _menu_link_build($item) {
  2653. // Suggested items are disabled by default.
  2654. if ($item['type'] == MENU_SUGGESTED_ITEM) {
  2655. $item['hidden'] = 1;
  2656. }
  2657. // Hide all items that are not visible in the tree.
  2658. elseif (!($item['type'] & MENU_VISIBLE_IN_TREE)) {
  2659. $item['hidden'] = -1;
  2660. }
  2661. // Note, we set this as 'system', so that we can be sure to distinguish all
  2662. // the menu links generated automatically from entries in {menu_router}.
  2663. $item['module'] = 'system';
  2664. $item += array(
  2665. 'menu_name' => 'navigation',
  2666. 'link_title' => $item['title'],
  2667. 'link_path' => $item['path'],
  2668. 'hidden' => 0,
  2669. 'options' => empty($item['description']) ? array() : array('attributes' => array('title' => $item['description'])),
  2670. );
  2671. return $item;
  2672. }
  2673. /**
  2674. * Builds menu links for the items in the menu router.
  2675. */
  2676. function _menu_navigation_links_rebuild($menu) {
  2677. // Add normal and suggested items as links.
  2678. $menu_links = array();
  2679. foreach ($menu as $path => $item) {
  2680. if ($item['_visible']) {
  2681. $menu_links[$path] = $item;
  2682. $sort[$path] = $item['_number_parts'];
  2683. }
  2684. }
  2685. if ($menu_links) {
  2686. // Keep an array of processed menu links, to allow menu_link_save() to
  2687. // check this for parents instead of querying the database.
  2688. $parent_candidates = array();
  2689. // Make sure no child comes before its parent.
  2690. array_multisort($sort, SORT_NUMERIC, $menu_links);
  2691. foreach ($menu_links as $key => $item) {
  2692. $existing_item = db_select('menu_links')
  2693. ->fields('menu_links')
  2694. ->condition('link_path', $item['path'])
  2695. ->condition('module', 'system')
  2696. ->execute()->fetchAssoc();
  2697. if ($existing_item) {
  2698. $item['mlid'] = $existing_item['mlid'];
  2699. // A change in hook_menu may move the link to a different menu
  2700. if (empty($item['menu_name']) || ($item['menu_name'] == $existing_item['menu_name'])) {
  2701. $item['menu_name'] = $existing_item['menu_name'];
  2702. $item['plid'] = $existing_item['plid'];
  2703. }
  2704. else {
  2705. // It moved to a new menu. Let menu_link_save() try to find a new
  2706. // parent based on the path.
  2707. unset($item['plid']);
  2708. }
  2709. $item['has_children'] = $existing_item['has_children'];
  2710. $item['updated'] = $existing_item['updated'];
  2711. }
  2712. if ($existing_item && $existing_item['customized']) {
  2713. $parent_candidates[$existing_item['mlid']] = $existing_item;
  2714. }
  2715. else {
  2716. $item = _menu_link_build($item);
  2717. menu_link_save($item, $existing_item, $parent_candidates);
  2718. $parent_candidates[$item['mlid']] = $item;
  2719. unset($menu_links[$key]);
  2720. }
  2721. }
  2722. }
  2723. $paths = array_keys($menu);
  2724. // Updated and customized items whose router paths are gone need new ones.
  2725. $result = db_select('menu_links', NULL, array('fetch' => PDO::FETCH_ASSOC))
  2726. ->fields('menu_links', array(
  2727. 'link_path',
  2728. 'mlid',
  2729. 'router_path',
  2730. 'updated',
  2731. ))
  2732. ->condition(db_or()
  2733. ->condition('updated', 1)
  2734. ->condition(db_and()
  2735. ->condition('router_path', $paths, 'NOT IN')
  2736. ->condition('external', 0)
  2737. ->condition('customized', 1)
  2738. )
  2739. )
  2740. ->execute();
  2741. foreach ($result as $item) {
  2742. $router_path = _menu_find_router_path($item['link_path']);
  2743. if (!empty($router_path) && ($router_path != $item['router_path'] || $item['updated'])) {
  2744. // If the router path and the link path matches, it's surely a working
  2745. // item, so we clear the updated flag.
  2746. $updated = $item['updated'] && $router_path != $item['link_path'];
  2747. db_update('menu_links')
  2748. ->fields(array(
  2749. 'router_path' => $router_path,
  2750. 'updated' => (int) $updated,
  2751. ))
  2752. ->condition('mlid', $item['mlid'])
  2753. ->execute();
  2754. }
  2755. }
  2756. // Find any item whose router path does not exist any more.
  2757. $result = db_select('menu_links')
  2758. ->fields('menu_links')
  2759. ->condition('router_path', $paths, 'NOT IN')
  2760. ->condition('external', 0)
  2761. ->condition('updated', 0)
  2762. ->condition('customized', 0)
  2763. ->orderBy('depth', 'DESC')
  2764. ->execute();
  2765. // Remove all such items. Starting from those with the greatest depth will
  2766. // minimize the amount of re-parenting done by menu_link_delete().
  2767. foreach ($result as $item) {
  2768. _menu_delete_item($item, TRUE);
  2769. }
  2770. }
  2771. /**
  2772. * Clones an array of menu links.
  2773. *
  2774. * @param $links
  2775. * An array of menu links to clone.
  2776. * @param $menu_name
  2777. * (optional) The name of a menu that the links will be cloned for. If not
  2778. * set, the cloned links will be in the same menu as the original set of
  2779. * links that were passed in.
  2780. *
  2781. * @return
  2782. * An array of menu links with the same properties as the passed-in array,
  2783. * but with the link identifiers removed so that a new link will be created
  2784. * when any of them is passed in to menu_link_save().
  2785. *
  2786. * @see menu_link_save()
  2787. */
  2788. function menu_links_clone($links, $menu_name = NULL) {
  2789. foreach ($links as &$link) {
  2790. unset($link['mlid']);
  2791. unset($link['plid']);
  2792. if (isset($menu_name)) {
  2793. $link['menu_name'] = $menu_name;
  2794. }
  2795. }
  2796. return $links;
  2797. }
  2798. /**
  2799. * Returns an array containing all links for a menu.
  2800. *
  2801. * @param $menu_name
  2802. * The name of the menu whose links should be returned.
  2803. *
  2804. * @return
  2805. * An array of menu links.
  2806. */
  2807. function menu_load_links($menu_name) {
  2808. $links = db_select('menu_links', 'ml', array('fetch' => PDO::FETCH_ASSOC))
  2809. ->fields('ml')
  2810. ->condition('ml.menu_name', $menu_name)
  2811. // Order by weight so as to be helpful for menus that are only one level
  2812. // deep.
  2813. ->orderBy('weight')
  2814. ->execute()
  2815. ->fetchAll();
  2816. foreach ($links as &$link) {
  2817. $link['options'] = unserialize($link['options']);
  2818. }
  2819. return $links;
  2820. }
  2821. /**
  2822. * Deletes all links for a menu.
  2823. *
  2824. * @param $menu_name
  2825. * The name of the menu whose links will be deleted.
  2826. */
  2827. function menu_delete_links($menu_name) {
  2828. $links = menu_load_links($menu_name);
  2829. foreach ($links as $link) {
  2830. // To speed up the deletion process, we reset some link properties that
  2831. // would trigger re-parenting logic in _menu_delete_item() and
  2832. // _menu_update_parental_status().
  2833. $link['has_children'] = FALSE;
  2834. $link['plid'] = 0;
  2835. _menu_delete_item($link);
  2836. }
  2837. }
  2838. /**
  2839. * Delete one or several menu links.
  2840. *
  2841. * @param $mlid
  2842. * A valid menu link mlid or NULL. If NULL, $path is used.
  2843. * @param $path
  2844. * The path to the menu items to be deleted. $mlid must be NULL.
  2845. */
  2846. function menu_link_delete($mlid, $path = NULL) {
  2847. if (isset($mlid)) {
  2848. _menu_delete_item(db_query("SELECT * FROM {menu_links} WHERE mlid = :mlid", array(':mlid' => $mlid))->fetchAssoc());
  2849. }
  2850. else {
  2851. $result = db_query("SELECT * FROM {menu_links} WHERE link_path = :link_path", array(':link_path' => $path));
  2852. foreach ($result as $link) {
  2853. _menu_delete_item($link);
  2854. }
  2855. }
  2856. }
  2857. /**
  2858. * Deletes a single menu link.
  2859. *
  2860. * @param $item
  2861. * Item to be deleted.
  2862. * @param $force
  2863. * Forces deletion. Internal use only, setting to TRUE is discouraged.
  2864. *
  2865. * @see menu_link_delete()
  2866. */
  2867. function _menu_delete_item($item, $force = FALSE) {
  2868. $item = is_object($item) ? get_object_vars($item) : $item;
  2869. if ($item && ($item['module'] != 'system' || $item['updated'] || $force)) {
  2870. // Children get re-attached to the item's parent.
  2871. if ($item['has_children']) {
  2872. $result = db_query("SELECT mlid FROM {menu_links} WHERE plid = :plid", array(':plid' => $item['mlid']));
  2873. foreach ($result as $m) {
  2874. $child = menu_link_load($m->mlid);
  2875. $child['plid'] = $item['plid'];
  2876. menu_link_save($child);
  2877. }
  2878. }
  2879. // Notify modules we are deleting the item.
  2880. module_invoke_all('menu_link_delete', $item);
  2881. db_delete('menu_links')->condition('mlid', $item['mlid'])->execute();
  2882. // Update the has_children status of the parent.
  2883. _menu_update_parental_status($item);
  2884. menu_cache_clear($item['menu_name']);
  2885. _menu_clear_page_cache();
  2886. }
  2887. }
  2888. /**
  2889. * Saves a menu link.
  2890. *
  2891. * After calling this function, rebuild the menu cache using
  2892. * menu_cache_clear_all().
  2893. *
  2894. * @param $item
  2895. * An associative array representing a menu link item, with elements:
  2896. * - link_path: (required) The path of the menu item, which should be
  2897. * normalized first by calling drupal_get_normal_path() on it.
  2898. * - link_title: (required) Title to appear in menu for the link.
  2899. * - menu_name: (optional) The machine name of the menu for the link.
  2900. * Defaults to 'navigation'.
  2901. * - weight: (optional) Integer to determine position in menu. Default is 0.
  2902. * - expanded: (optional) Boolean that determines if the item is expanded.
  2903. * - options: (optional) An array of options, see l() for more.
  2904. * - mlid: (optional) Menu link identifier, the primary integer key for each
  2905. * menu link. Can be set to an existing value, or to 0 or NULL
  2906. * to insert a new link.
  2907. * - plid: (optional) The mlid of the parent.
  2908. * - router_path: (optional) The path of the relevant router item.
  2909. * @param $existing_item
  2910. * Optional, the current record from the {menu_links} table as an array.
  2911. * @param $parent_candidates
  2912. * Optional array of menu links keyed by mlid. Used by
  2913. * _menu_navigation_links_rebuild() only.
  2914. *
  2915. * @return
  2916. * The mlid of the saved menu link, or FALSE if the menu link could not be
  2917. * saved.
  2918. */
  2919. function menu_link_save(&$item, $existing_item = array(), $parent_candidates = array()) {
  2920. drupal_alter('menu_link', $item);
  2921. // This is the easiest way to handle the unique internal path '<front>',
  2922. // since a path marked as external does not need to match a router path.
  2923. $item['external'] = (url_is_external($item['link_path']) || $item['link_path'] == '<front>') ? 1 : 0;
  2924. // Load defaults.
  2925. $item += array(
  2926. 'menu_name' => 'navigation',
  2927. 'weight' => 0,
  2928. 'link_title' => '',
  2929. 'hidden' => 0,
  2930. 'has_children' => 0,
  2931. 'expanded' => 0,
  2932. 'options' => array(),
  2933. 'module' => 'menu',
  2934. 'customized' => 0,
  2935. 'updated' => 0,
  2936. );
  2937. if (isset($item['mlid'])) {
  2938. if (!$existing_item) {
  2939. $existing_item = db_query('SELECT * FROM {menu_links} WHERE mlid = :mlid', array('mlid' => $item['mlid']))->fetchAssoc();
  2940. }
  2941. if ($existing_item) {
  2942. $existing_item['options'] = unserialize($existing_item['options']);
  2943. }
  2944. }
  2945. else {
  2946. $existing_item = FALSE;
  2947. }
  2948. // Try to find a parent link. If found, assign it and derive its menu.
  2949. $parent = _menu_link_find_parent($item, $parent_candidates);
  2950. if (!empty($parent['mlid'])) {
  2951. $item['plid'] = $parent['mlid'];
  2952. $item['menu_name'] = $parent['menu_name'];
  2953. }
  2954. // If no corresponding parent link was found, move the link to the top-level.
  2955. else {
  2956. $item['plid'] = 0;
  2957. }
  2958. $menu_name = $item['menu_name'];
  2959. if (!$existing_item) {
  2960. $item['mlid'] = db_insert('menu_links')
  2961. ->fields(array(
  2962. 'menu_name' => $item['menu_name'],
  2963. 'plid' => $item['plid'],
  2964. 'link_path' => $item['link_path'],
  2965. 'hidden' => $item['hidden'],
  2966. 'external' => $item['external'],
  2967. 'has_children' => $item['has_children'],
  2968. 'expanded' => $item['expanded'],
  2969. 'weight' => $item['weight'],
  2970. 'module' => $item['module'],
  2971. 'link_title' => $item['link_title'],
  2972. 'options' => serialize($item['options']),
  2973. 'customized' => $item['customized'],
  2974. 'updated' => $item['updated'],
  2975. ))
  2976. ->execute();
  2977. }
  2978. // Directly fill parents for top-level links.
  2979. if ($item['plid'] == 0) {
  2980. $item['p1'] = $item['mlid'];
  2981. for ($i = 2; $i <= MENU_MAX_DEPTH; $i++) {
  2982. $item["p$i"] = 0;
  2983. }
  2984. $item['depth'] = 1;
  2985. }
  2986. // Otherwise, ensure that this link's depth is not beyond the maximum depth
  2987. // and fill parents based on the parent link.
  2988. else {
  2989. if ($item['has_children'] && $existing_item) {
  2990. $limit = MENU_MAX_DEPTH - menu_link_children_relative_depth($existing_item) - 1;
  2991. }
  2992. else {
  2993. $limit = MENU_MAX_DEPTH - 1;
  2994. }
  2995. if ($parent['depth'] > $limit) {
  2996. return FALSE;
  2997. }
  2998. $item['depth'] = $parent['depth'] + 1;
  2999. _menu_link_parents_set($item, $parent);
  3000. }
  3001. // Need to check both plid and menu_name, since plid can be 0 in any menu.
  3002. if ($existing_item && ($item['plid'] != $existing_item['plid'] || $menu_name != $existing_item['menu_name'])) {
  3003. _menu_link_move_children($item, $existing_item);
  3004. }
  3005. // Find the router_path.
  3006. if (empty($item['router_path']) || !$existing_item || ($existing_item['link_path'] != $item['link_path'])) {
  3007. if ($item['external']) {
  3008. $item['router_path'] = '';
  3009. }
  3010. else {
  3011. // Find the router path which will serve this path.
  3012. $item['parts'] = explode('/', $item['link_path'], MENU_MAX_PARTS);
  3013. $item['router_path'] = _menu_find_router_path($item['link_path']);
  3014. }
  3015. }
  3016. // If every value in $existing_item is the same in the $item, there is no
  3017. // reason to run the update queries or clear the caches. We use
  3018. // array_intersect_key() with the $item as the first parameter because
  3019. // $item may have additional keys left over from building a router entry.
  3020. // The intersect removes the extra keys, allowing a meaningful comparison.
  3021. if (!$existing_item || (array_intersect_key($item, $existing_item) != $existing_item)) {
  3022. db_update('menu_links')
  3023. ->fields(array(
  3024. 'menu_name' => $item['menu_name'],
  3025. 'plid' => $item['plid'],
  3026. 'link_path' => $item['link_path'],
  3027. 'router_path' => $item['router_path'],
  3028. 'hidden' => $item['hidden'],
  3029. 'external' => $item['external'],
  3030. 'has_children' => $item['has_children'],
  3031. 'expanded' => $item['expanded'],
  3032. 'weight' => $item['weight'],
  3033. 'depth' => $item['depth'],
  3034. 'p1' => $item['p1'],
  3035. 'p2' => $item['p2'],
  3036. 'p3' => $item['p3'],
  3037. 'p4' => $item['p4'],
  3038. 'p5' => $item['p5'],
  3039. 'p6' => $item['p6'],
  3040. 'p7' => $item['p7'],
  3041. 'p8' => $item['p8'],
  3042. 'p9' => $item['p9'],
  3043. 'module' => $item['module'],
  3044. 'link_title' => $item['link_title'],
  3045. 'options' => serialize($item['options']),
  3046. 'customized' => $item['customized'],
  3047. ))
  3048. ->condition('mlid', $item['mlid'])
  3049. ->execute();
  3050. // Check the has_children status of the parent.
  3051. _menu_update_parental_status($item);
  3052. menu_cache_clear($menu_name);
  3053. if ($existing_item && $menu_name != $existing_item['menu_name']) {
  3054. menu_cache_clear($existing_item['menu_name']);
  3055. }
  3056. // Notify modules we have acted on a menu item.
  3057. $hook = 'menu_link_insert';
  3058. if ($existing_item) {
  3059. $hook = 'menu_link_update';
  3060. }
  3061. module_invoke_all($hook, $item);
  3062. // Now clear the cache.
  3063. _menu_clear_page_cache();
  3064. }
  3065. return $item['mlid'];
  3066. }
  3067. /**
  3068. * Finds a possible parent for a given menu link.
  3069. *
  3070. * Because the parent of a given link might not exist anymore in the database,
  3071. * we apply a set of heuristics to determine a proper parent:
  3072. *
  3073. * - use the passed parent link if specified and existing.
  3074. * - else, use the first existing link down the previous link hierarchy
  3075. * - else, for system menu links (derived from hook_menu()), reparent
  3076. * based on the path hierarchy.
  3077. *
  3078. * @param $menu_link
  3079. * A menu link.
  3080. * @param $parent_candidates
  3081. * An array of menu links keyed by mlid.
  3082. *
  3083. * @return
  3084. * A menu link structure of the possible parent or FALSE if no valid parent
  3085. * has been found.
  3086. */
  3087. function _menu_link_find_parent($menu_link, $parent_candidates = array()) {
  3088. $parent = FALSE;
  3089. // This item is explicitely top-level, skip the rest of the parenting.
  3090. if (isset($menu_link['plid']) && empty($menu_link['plid'])) {
  3091. return $parent;
  3092. }
  3093. // If we have a parent link ID, try to use that.
  3094. $candidates = array();
  3095. if (isset($menu_link['plid'])) {
  3096. $candidates[] = $menu_link['plid'];
  3097. }
  3098. // Else, if we have a link hierarchy try to find a valid parent in there.
  3099. if (!empty($menu_link['depth']) && $menu_link['depth'] > 1) {
  3100. for ($depth = $menu_link['depth'] - 1; $depth >= 1; $depth--) {
  3101. $candidates[] = $menu_link['p' . $depth];
  3102. }
  3103. }
  3104. foreach ($candidates as $mlid) {
  3105. if (isset($parent_candidates[$mlid])) {
  3106. $parent = $parent_candidates[$mlid];
  3107. }
  3108. else {
  3109. $parent = db_query("SELECT * FROM {menu_links} WHERE mlid = :mlid", array(':mlid' => $mlid))->fetchAssoc();
  3110. }
  3111. if ($parent) {
  3112. return $parent;
  3113. }
  3114. }
  3115. // If everything else failed, try to derive the parent from the path
  3116. // hierarchy. This only makes sense for links derived from menu router
  3117. // items (ie. from hook_menu()).
  3118. if ($menu_link['module'] == 'system') {
  3119. $query = db_select('menu_links');
  3120. $query->condition('module', 'system');
  3121. // We always respect the link's 'menu_name'; inheritance for router items is
  3122. // ensured in _menu_router_build().
  3123. $query->condition('menu_name', $menu_link['menu_name']);
  3124. // Find the parent - it must be unique.
  3125. $parent_path = $menu_link['link_path'];
  3126. do {
  3127. $parent = FALSE;
  3128. $parent_path = substr($parent_path, 0, strrpos($parent_path, '/'));
  3129. $new_query = clone $query;
  3130. $new_query->condition('link_path', $parent_path);
  3131. // Only valid if we get a unique result.
  3132. if ($new_query->countQuery()->execute()->fetchField() == 1) {
  3133. $parent = $new_query->fields('menu_links')->execute()->fetchAssoc();
  3134. }
  3135. } while ($parent === FALSE && $parent_path);
  3136. }
  3137. return $parent;
  3138. }
  3139. /**
  3140. * Clears the page and block caches at most twice per page load.
  3141. */
  3142. function _menu_clear_page_cache() {
  3143. $cache_cleared = &drupal_static(__FUNCTION__, 0);
  3144. // Clear the page and block caches, but at most twice, including at
  3145. // the end of the page load when there are multiple links saved or deleted.
  3146. if ($cache_cleared == 0) {
  3147. cache_clear_all();
  3148. // Keep track of which menus have expanded items.
  3149. _menu_set_expanded_menus();
  3150. $cache_cleared = 1;
  3151. }
  3152. elseif ($cache_cleared == 1) {
  3153. drupal_register_shutdown_function('cache_clear_all');
  3154. // Keep track of which menus have expanded items.
  3155. drupal_register_shutdown_function('_menu_set_expanded_menus');
  3156. $cache_cleared = 2;
  3157. }
  3158. }
  3159. /**
  3160. * Updates a list of menus with expanded items.
  3161. */
  3162. function _menu_set_expanded_menus() {
  3163. $names = db_query("SELECT menu_name FROM {menu_links} WHERE expanded <> 0 GROUP BY menu_name")->fetchCol();
  3164. variable_set('menu_expanded', $names);
  3165. }
  3166. /**
  3167. * Finds the router path which will serve this path.
  3168. *
  3169. * @param $link_path
  3170. * The path for we are looking up its router path.
  3171. *
  3172. * @return
  3173. * A path from $menu keys or empty if $link_path points to a nonexisting
  3174. * place.
  3175. */
  3176. function _menu_find_router_path($link_path) {
  3177. // $menu will only have data during a menu rebuild.
  3178. $menu = _menu_router_cache();
  3179. $router_path = $link_path;
  3180. $parts = explode('/', $link_path, MENU_MAX_PARTS);
  3181. $ancestors = menu_get_ancestors($parts);
  3182. if (empty($menu)) {
  3183. // Not during a menu rebuild, so look up in the database.
  3184. $router_path = (string) db_select('menu_router')
  3185. ->fields('menu_router', array('path'))
  3186. ->condition('path', $ancestors, 'IN')
  3187. ->orderBy('fit', 'DESC')
  3188. ->range(0, 1)
  3189. ->execute()->fetchField();
  3190. }
  3191. elseif (!isset($menu[$router_path])) {
  3192. // Add an empty router path as a fallback.
  3193. $ancestors[] = '';
  3194. foreach ($ancestors as $key => $router_path) {
  3195. if (isset($menu[$router_path])) {
  3196. // Exit the loop leaving $router_path as the first match.
  3197. break;
  3198. }
  3199. }
  3200. // If we did not find the path, $router_path will be the empty string
  3201. // at the end of $ancestors.
  3202. }
  3203. return $router_path;
  3204. }
  3205. /**
  3206. * Inserts, updates, or deletes an uncustomized menu link related to a module.
  3207. *
  3208. * @param $module
  3209. * The name of the module.
  3210. * @param $op
  3211. * Operation to perform: insert, update or delete.
  3212. * @param $link_path
  3213. * The path this link points to.
  3214. * @param $link_title
  3215. * Title of the link to insert or new title to update the link to.
  3216. * Unused for delete.
  3217. *
  3218. * @return
  3219. * The insert op returns the mlid of the new item. Others op return NULL.
  3220. */
  3221. function menu_link_maintain($module, $op, $link_path, $link_title) {
  3222. switch ($op) {
  3223. case 'insert':
  3224. $menu_link = array(
  3225. 'link_title' => $link_title,
  3226. 'link_path' => $link_path,
  3227. 'module' => $module,
  3228. );
  3229. return menu_link_save($menu_link);
  3230. break;
  3231. case 'update':
  3232. $result = db_query("SELECT * FROM {menu_links} WHERE link_path = :link_path AND module = :module AND customized = 0", array(':link_path' => $link_path, ':module' => $module))->fetchAll(PDO::FETCH_ASSOC);
  3233. foreach ($result as $link) {
  3234. $link['link_title'] = $link_title;
  3235. $link['options'] = unserialize($link['options']);
  3236. menu_link_save($link);
  3237. }
  3238. break;
  3239. case 'delete':
  3240. menu_link_delete(NULL, $link_path);
  3241. break;
  3242. }
  3243. }
  3244. /**
  3245. * Finds the depth of an item's children relative to its depth.
  3246. *
  3247. * For example, if the item has a depth of 2, and the maximum of any child in
  3248. * the menu link tree is 5, the relative depth is 3.
  3249. *
  3250. * @param $item
  3251. * An array representing a menu link item.
  3252. *
  3253. * @return
  3254. * The relative depth, or zero.
  3255. *
  3256. */
  3257. function menu_link_children_relative_depth($item) {
  3258. $query = db_select('menu_links');
  3259. $query->addField('menu_links', 'depth');
  3260. $query->condition('menu_name', $item['menu_name']);
  3261. $query->orderBy('depth', 'DESC');
  3262. $query->range(0, 1);
  3263. $i = 1;
  3264. $p = 'p1';
  3265. while ($i <= MENU_MAX_DEPTH && $item[$p]) {
  3266. $query->condition($p, $item[$p]);
  3267. $p = 'p' . ++$i;
  3268. }
  3269. $max_depth = $query->execute()->fetchField();
  3270. return ($max_depth > $item['depth']) ? $max_depth - $item['depth'] : 0;
  3271. }
  3272. /**
  3273. * Updates the children of a menu link that is being moved.
  3274. *
  3275. * The menu name, parents (p1 - p6), and depth are updated for all children of
  3276. * the link, and the has_children status of the previous parent is updated.
  3277. */
  3278. function _menu_link_move_children($item, $existing_item) {
  3279. $query = db_update('menu_links');
  3280. $query->fields(array('menu_name' => $item['menu_name']));
  3281. $p = 'p1';
  3282. $expressions = array();
  3283. for ($i = 1; $i <= $item['depth']; $p = 'p' . ++$i) {
  3284. $expressions[] = array($p, ":p_$i", array(":p_$i" => $item[$p]));
  3285. }
  3286. $j = $existing_item['depth'] + 1;
  3287. while ($i <= MENU_MAX_DEPTH && $j <= MENU_MAX_DEPTH) {
  3288. $expressions[] = array('p' . $i++, 'p' . $j++, array());
  3289. }
  3290. while ($i <= MENU_MAX_DEPTH) {
  3291. $expressions[] = array('p' . $i++, 0, array());
  3292. }
  3293. $shift = $item['depth'] - $existing_item['depth'];
  3294. if ($shift > 0) {
  3295. // The order of expressions must be reversed so the new values don't
  3296. // overwrite the old ones before they can be used because "Single-table
  3297. // UPDATE assignments are generally evaluated from left to right"
  3298. // see: http://dev.mysql.com/doc/refman/5.0/en/update.html
  3299. $expressions = array_reverse($expressions);
  3300. }
  3301. foreach ($expressions as $expression) {
  3302. $query->expression($expression[0], $expression[1], $expression[2]);
  3303. }
  3304. $query->expression('depth', 'depth + :depth', array(':depth' => $shift));
  3305. $query->condition('menu_name', $existing_item['menu_name']);
  3306. $p = 'p1';
  3307. for ($i = 1; $i <= MENU_MAX_DEPTH && $existing_item[$p]; $p = 'p' . ++$i) {
  3308. $query->condition($p, $existing_item[$p]);
  3309. }
  3310. $query->execute();
  3311. // Check the has_children status of the parent, while excluding this item.
  3312. _menu_update_parental_status($existing_item, TRUE);
  3313. }
  3314. /**
  3315. * Checks and updates the 'has_children' status for the parent of a link.
  3316. */
  3317. function _menu_update_parental_status($item, $exclude = FALSE) {
  3318. // If plid == 0, there is nothing to update.
  3319. if ($item['plid']) {
  3320. // Check if at least one visible child exists in the table.
  3321. $query = db_select('menu_links');
  3322. $query->addField('menu_links', 'mlid');
  3323. $query->condition('menu_name', $item['menu_name']);
  3324. $query->condition('hidden', 0);
  3325. $query->condition('plid', $item['plid']);
  3326. $query->range(0, 1);
  3327. if ($exclude) {
  3328. $query->condition('mlid', $item['mlid'], '<>');
  3329. }
  3330. $parent_has_children = ((bool) $query->execute()->fetchField()) ? 1 : 0;
  3331. db_update('menu_links')
  3332. ->fields(array('has_children' => $parent_has_children))
  3333. ->condition('mlid', $item['plid'])
  3334. ->execute();
  3335. }
  3336. }
  3337. /**
  3338. * Sets the p1 through p9 values for a menu link being saved.
  3339. */
  3340. function _menu_link_parents_set(&$item, $parent) {
  3341. $i = 1;
  3342. while ($i < $item['depth']) {
  3343. $p = 'p' . $i++;
  3344. $item[$p] = $parent[$p];
  3345. }
  3346. $p = 'p' . $i++;
  3347. // The parent (p1 - p9) corresponding to the depth always equals the mlid.
  3348. $item[$p] = $item['mlid'];
  3349. while ($i <= MENU_MAX_DEPTH) {
  3350. $p = 'p' . $i++;
  3351. $item[$p] = 0;
  3352. }
  3353. }
  3354. /**
  3355. * Builds the router table based on the data from hook_menu().
  3356. */
  3357. function _menu_router_build($callbacks) {
  3358. // First pass: separate callbacks from paths, making paths ready for
  3359. // matching. Calculate fitness, and fill some default values.
  3360. $menu = array();
  3361. $masks = array();
  3362. foreach ($callbacks as $path => $item) {
  3363. $load_functions = array();
  3364. $to_arg_functions = array();
  3365. $fit = 0;
  3366. $move = FALSE;
  3367. $parts = explode('/', $path, MENU_MAX_PARTS);
  3368. $number_parts = count($parts);
  3369. // We store the highest index of parts here to save some work in the fit
  3370. // calculation loop.
  3371. $slashes = $number_parts - 1;
  3372. // Extract load and to_arg functions.
  3373. foreach ($parts as $k => $part) {
  3374. $match = FALSE;
  3375. // Look for wildcards in the form allowed to be used in PHP functions,
  3376. // because we are using these to construct the load function names.
  3377. if (preg_match('/^%(|' . DRUPAL_PHP_FUNCTION_PATTERN . ')$/', $part, $matches)) {
  3378. if (empty($matches[1])) {
  3379. $match = TRUE;
  3380. $load_functions[$k] = NULL;
  3381. }
  3382. else {
  3383. if (function_exists($matches[1] . '_to_arg')) {
  3384. $to_arg_functions[$k] = $matches[1] . '_to_arg';
  3385. $load_functions[$k] = NULL;
  3386. $match = TRUE;
  3387. }
  3388. if (function_exists($matches[1] . '_load')) {
  3389. $function = $matches[1] . '_load';
  3390. // Create an array of arguments that will be passed to the _load
  3391. // function when this menu path is checked, if 'load arguments'
  3392. // exists.
  3393. $load_functions[$k] = isset($item['load arguments']) ? array($function => $item['load arguments']) : $function;
  3394. $match = TRUE;
  3395. }
  3396. }
  3397. }
  3398. if ($match) {
  3399. $parts[$k] = '%';
  3400. }
  3401. else {
  3402. $fit |= 1 << ($slashes - $k);
  3403. }
  3404. }
  3405. if ($fit) {
  3406. $move = TRUE;
  3407. }
  3408. else {
  3409. // If there is no %, it fits maximally.
  3410. $fit = (1 << $number_parts) - 1;
  3411. }
  3412. $masks[$fit] = 1;
  3413. $item['_load_functions'] = $load_functions;
  3414. $item['to_arg_functions'] = empty($to_arg_functions) ? '' : serialize($to_arg_functions);
  3415. $item += array(
  3416. 'title' => '',
  3417. 'weight' => 0,
  3418. 'type' => MENU_NORMAL_ITEM,
  3419. 'module' => '',
  3420. '_number_parts' => $number_parts,
  3421. '_parts' => $parts,
  3422. '_fit' => $fit,
  3423. );
  3424. $item += array(
  3425. '_visible' => (bool) ($item['type'] & MENU_VISIBLE_IN_BREADCRUMB),
  3426. '_tab' => (bool) ($item['type'] & MENU_IS_LOCAL_TASK),
  3427. );
  3428. if ($move) {
  3429. $new_path = implode('/', $item['_parts']);
  3430. $menu[$new_path] = $item;
  3431. $sort[$new_path] = $number_parts;
  3432. }
  3433. else {
  3434. $menu[$path] = $item;
  3435. $sort[$path] = $number_parts;
  3436. }
  3437. }
  3438. array_multisort($sort, SORT_NUMERIC, $menu);
  3439. // Apply inheritance rules.
  3440. foreach ($menu as $path => $v) {
  3441. $item = &$menu[$path];
  3442. if (!$item['_tab']) {
  3443. // Non-tab items.
  3444. $item['tab_parent'] = '';
  3445. $item['tab_root'] = $path;
  3446. }
  3447. // If not specified, assign the default tab type for local tasks.
  3448. elseif (!isset($item['context'])) {
  3449. $item['context'] = MENU_CONTEXT_PAGE;
  3450. }
  3451. for ($i = $item['_number_parts'] - 1; $i; $i--) {
  3452. $parent_path = implode('/', array_slice($item['_parts'], 0, $i));
  3453. if (isset($menu[$parent_path])) {
  3454. $parent = &$menu[$parent_path];
  3455. // If we have no menu name, try to inherit it from parent items.
  3456. if (!isset($item['menu_name'])) {
  3457. // If the parent item of this item does not define a menu name (and no
  3458. // previous iteration assigned one already), try to find the menu name
  3459. // of the parent item in the currently stored menu links.
  3460. if (!isset($parent['menu_name'])) {
  3461. $menu_name = db_query("SELECT menu_name FROM {menu_links} WHERE router_path = :router_path AND module = 'system'", array(':router_path' => $parent_path))->fetchField();
  3462. if ($menu_name) {
  3463. $parent['menu_name'] = $menu_name;
  3464. }
  3465. }
  3466. // If the parent item defines a menu name, inherit it.
  3467. if (!empty($parent['menu_name'])) {
  3468. $item['menu_name'] = $parent['menu_name'];
  3469. }
  3470. }
  3471. if (!isset($item['tab_parent'])) {
  3472. // Parent stores the parent of the path.
  3473. $item['tab_parent'] = $parent_path;
  3474. }
  3475. if (!isset($item['tab_root']) && !$parent['_tab']) {
  3476. $item['tab_root'] = $parent_path;
  3477. }
  3478. // If an access callback is not found for a default local task we use
  3479. // the callback from the parent, since we expect them to be identical.
  3480. // In all other cases, the access parameters must be specified.
  3481. if (($item['type'] == MENU_DEFAULT_LOCAL_TASK) && !isset($item['access callback']) && isset($parent['access callback'])) {
  3482. $item['access callback'] = $parent['access callback'];
  3483. if (!isset($item['access arguments']) && isset($parent['access arguments'])) {
  3484. $item['access arguments'] = $parent['access arguments'];
  3485. }
  3486. }
  3487. // Same for page callbacks.
  3488. if (!isset($item['page callback']) && isset($parent['page callback'])) {
  3489. $item['page callback'] = $parent['page callback'];
  3490. if (!isset($item['page arguments']) && isset($parent['page arguments'])) {
  3491. $item['page arguments'] = $parent['page arguments'];
  3492. }
  3493. if (!isset($item['file path']) && isset($parent['file path'])) {
  3494. $item['file path'] = $parent['file path'];
  3495. }
  3496. if (!isset($item['file']) && isset($parent['file'])) {
  3497. $item['file'] = $parent['file'];
  3498. if (empty($item['file path']) && isset($item['module']) && isset($parent['module']) && $item['module'] != $parent['module']) {
  3499. $item['file path'] = drupal_get_path('module', $parent['module']);
  3500. }
  3501. }
  3502. }
  3503. // Same for delivery callbacks.
  3504. if (!isset($item['delivery callback']) && isset($parent['delivery callback'])) {
  3505. $item['delivery callback'] = $parent['delivery callback'];
  3506. }
  3507. // Same for theme callbacks.
  3508. if (!isset($item['theme callback']) && isset($parent['theme callback'])) {
  3509. $item['theme callback'] = $parent['theme callback'];
  3510. if (!isset($item['theme arguments']) && isset($parent['theme arguments'])) {
  3511. $item['theme arguments'] = $parent['theme arguments'];
  3512. }
  3513. }
  3514. // Same for load arguments: if a loader doesn't have any explict
  3515. // arguments, try to find arguments in the parent.
  3516. if (!isset($item['load arguments'])) {
  3517. foreach ($item['_load_functions'] as $k => $function) {
  3518. // This loader doesn't have any explict arguments...
  3519. if (!is_array($function)) {
  3520. // ... check the parent for a loader at the same position
  3521. // using the same function name and defining arguments...
  3522. if (isset($parent['_load_functions'][$k]) && is_array($parent['_load_functions'][$k]) && key($parent['_load_functions'][$k]) === $function) {
  3523. // ... and inherit the arguments on the child.
  3524. $item['_load_functions'][$k] = $parent['_load_functions'][$k];
  3525. }
  3526. }
  3527. }
  3528. }
  3529. }
  3530. }
  3531. if (!isset($item['access callback']) && isset($item['access arguments'])) {
  3532. // Default callback.
  3533. $item['access callback'] = 'user_access';
  3534. }
  3535. if (!isset($item['access callback']) || empty($item['page callback'])) {
  3536. $item['access callback'] = 0;
  3537. }
  3538. if (is_bool($item['access callback'])) {
  3539. $item['access callback'] = intval($item['access callback']);
  3540. }
  3541. $item['load_functions'] = empty($item['_load_functions']) ? '' : serialize($item['_load_functions']);
  3542. $item += array(
  3543. 'access arguments' => array(),
  3544. 'access callback' => '',
  3545. 'page arguments' => array(),
  3546. 'page callback' => '',
  3547. 'delivery callback' => '',
  3548. 'title arguments' => array(),
  3549. 'title callback' => 't',
  3550. 'theme arguments' => array(),
  3551. 'theme callback' => '',
  3552. 'description' => '',
  3553. 'position' => '',
  3554. 'context' => 0,
  3555. 'tab_parent' => '',
  3556. 'tab_root' => $path,
  3557. 'path' => $path,
  3558. 'file' => '',
  3559. 'file path' => '',
  3560. 'include file' => '',
  3561. );
  3562. // Calculate out the file to be included for each callback, if any.
  3563. if ($item['file']) {
  3564. $file_path = $item['file path'] ? $item['file path'] : drupal_get_path('module', $item['module']);
  3565. $item['include file'] = $file_path . '/' . $item['file'];
  3566. }
  3567. }
  3568. // Sort the masks so they are in order of descending fit.
  3569. $masks = array_keys($masks);
  3570. rsort($masks);
  3571. return array($menu, $masks);
  3572. }
  3573. /**
  3574. * Saves data from menu_router_build() to the router table.
  3575. */
  3576. function _menu_router_save($menu, $masks) {
  3577. // Delete the existing router since we have some data to replace it.
  3578. db_truncate('menu_router')->execute();
  3579. // Prepare insert object.
  3580. $insert = db_insert('menu_router')
  3581. ->fields(array(
  3582. 'path',
  3583. 'load_functions',
  3584. 'to_arg_functions',
  3585. 'access_callback',
  3586. 'access_arguments',
  3587. 'page_callback',
  3588. 'page_arguments',
  3589. 'delivery_callback',
  3590. 'fit',
  3591. 'number_parts',
  3592. 'context',
  3593. 'tab_parent',
  3594. 'tab_root',
  3595. 'title',
  3596. 'title_callback',
  3597. 'title_arguments',
  3598. 'theme_callback',
  3599. 'theme_arguments',
  3600. 'type',
  3601. 'description',
  3602. 'position',
  3603. 'weight',
  3604. 'include_file',
  3605. ));
  3606. $num_records = 0;
  3607. foreach ($menu as $path => $item) {
  3608. // Fill in insert object values.
  3609. $insert->values(array(
  3610. 'path' => $item['path'],
  3611. 'load_functions' => $item['load_functions'],
  3612. 'to_arg_functions' => $item['to_arg_functions'],
  3613. 'access_callback' => $item['access callback'],
  3614. 'access_arguments' => serialize($item['access arguments']),
  3615. 'page_callback' => $item['page callback'],
  3616. 'page_arguments' => serialize($item['page arguments']),
  3617. 'delivery_callback' => $item['delivery callback'],
  3618. 'fit' => $item['_fit'],
  3619. 'number_parts' => $item['_number_parts'],
  3620. 'context' => $item['context'],
  3621. 'tab_parent' => $item['tab_parent'],
  3622. 'tab_root' => $item['tab_root'],
  3623. 'title' => $item['title'],
  3624. 'title_callback' => $item['title callback'],
  3625. 'title_arguments' => ($item['title arguments'] ? serialize($item['title arguments']) : ''),
  3626. 'theme_callback' => $item['theme callback'],
  3627. 'theme_arguments' => serialize($item['theme arguments']),
  3628. 'type' => $item['type'],
  3629. 'description' => $item['description'],
  3630. 'position' => $item['position'],
  3631. 'weight' => $item['weight'],
  3632. 'include_file' => $item['include file'],
  3633. ));
  3634. // Execute in batches to avoid the memory overhead of all of those records
  3635. // in the query object.
  3636. if (++$num_records == 20) {
  3637. $insert->execute();
  3638. $num_records = 0;
  3639. }
  3640. }
  3641. // Insert any remaining records.
  3642. $insert->execute();
  3643. // Store the masks.
  3644. variable_set('menu_masks', $masks);
  3645. return $menu;
  3646. }
  3647. /**
  3648. * Checks whether the site is in maintenance mode.
  3649. *
  3650. * This function will log the current user out and redirect to front page
  3651. * if the current user has no 'access site in maintenance mode' permission.
  3652. *
  3653. * @param $check_only
  3654. * If this is set to TRUE, the function will perform the access checks and
  3655. * return the site offline status, but not log the user out or display any
  3656. * messages.
  3657. *
  3658. * @return
  3659. * FALSE if the site is not in maintenance mode, the user login page is
  3660. * displayed, or the user has the 'access site in maintenance mode'
  3661. * permission. TRUE for anonymous users not being on the login page when the
  3662. * site is in maintenance mode.
  3663. */
  3664. function _menu_site_is_offline($check_only = FALSE) {
  3665. // Check if site is in maintenance mode.
  3666. if (variable_get('maintenance_mode', 0)) {
  3667. if (user_access('access site in maintenance mode')) {
  3668. // Ensure that the maintenance mode message is displayed only once
  3669. // (allowing for page redirects) and specifically suppress its display on
  3670. // the maintenance mode settings page.
  3671. if (!$check_only && $_GET['q'] != 'admin/config/development/maintenance') {
  3672. if (user_access('administer site configuration')) {
  3673. drupal_set_message(t('Operating in maintenance mode. <a href="@url">Go online.</a>', array('@url' => url('admin/config/development/maintenance'))), 'status', FALSE);
  3674. }
  3675. else {
  3676. drupal_set_message(t('Operating in maintenance mode.'), 'status', FALSE);
  3677. }
  3678. }
  3679. }
  3680. else {
  3681. return TRUE;
  3682. }
  3683. }
  3684. return FALSE;
  3685. }
  3686. /**
  3687. * @} End of "defgroup menu".
  3688. */

Functions

Namesort descending Description
drupal_help_arg Generates elements for the $arg array in the help hook.
menu_build_tree Builds a menu tree, translates links, and checks access.
menu_cache_clear Clears the cached data for a single named menu.
menu_cache_clear_all Clears all cached menu data.
menu_contextual_links Retrieves contextual links for a path based on registered local tasks.
menu_delete_links Deletes all links for a menu.
menu_execute_active_handler Execute the page callback associated with the current path.
menu_get_active_breadcrumb Gets the breadcrumb for the current page, as determined by the active trail.
menu_get_active_help Returns the help associated with the active menu item.
menu_get_active_menu_names Gets the active menu for the current page.
menu_get_active_title Gets the title of the current page, as determined by the active trail.
menu_get_active_trail Gets the active trail (path to root menu root) of the current page.
menu_get_ancestors Returns the ancestors (and relevant placeholders) for any given path.
menu_get_custom_theme Gets the custom theme for the current page, if there is one.
menu_get_item Gets a router item.
menu_get_names Build a list of named menus.
menu_get_object Gets a loaded object from a router item.
menu_get_router Gets the menu router.
menu_links_clone Clones an array of menu links.
menu_link_children_relative_depth Finds the depth of an item's children relative to its depth.
menu_link_delete Delete one or several menu links.
menu_link_get_preferred Looks up the preferred menu link for a given system path.
menu_link_load Gets a translated, access-checked menu link that is ready for rendering.
menu_link_maintain Inserts, updates, or deletes an uncustomized menu link related to a module.
menu_link_save Saves a menu link.
menu_list_system_menus Returns an array containing the names of system-defined (default) menus.
menu_load_links Returns an array containing all links for a menu.
menu_local_actions Returns the rendered local actions at the current level.
menu_local_tabs Returns a renderable element for the primary and secondary tabs.
menu_local_tasks Collects the local tasks (tabs), action links, and the root path.
menu_main_menu Returns an array of links to be rendered as the Main menu.
menu_navigation_links Returns an array of links for a navigation menu.
menu_primary_local_tasks Returns the rendered local tasks at the top level.
menu_rebuild Populates the database tables used by various menu functions.
menu_reset_static_cache Resets the menu system static cache.
menu_router_build Collects and alters the menu definitions.
menu_secondary_local_tasks Returns the rendered local tasks at the second level.
menu_secondary_menu Returns an array of links to be rendered as the Secondary links.
menu_set_active_item Sets the active path, which determines which page is loaded.
menu_set_active_menu_names Sets (or gets) the active menu for the current page.
menu_set_active_trail Sets the active trail (path to the menu tree root) of the current page.
menu_set_custom_theme Sets a custom theme for the current page, if there is one.
menu_set_item Replaces the statically cached item for a given path.
menu_tab_root_path Returns the router path, or the path for a default local task's parent.
menu_tail_load Loads the path as one string relative to the current index.
menu_tail_to_arg Returns a string containing the path relative to the current index.
menu_tree Renders a menu tree based on the current path.
menu_tree_all_data Gets the data structure representing a named menu tree.
menu_tree_check_access Checks access and performs dynamic operations for each link in the tree.
menu_tree_collect_node_links Collects node links from a given menu tree recursively.
menu_tree_data Sorts and returns the built data representing a menu tree.
menu_tree_get_path Gets the path for determining the active trail of the specified menu tree.
menu_tree_output Returns an output structure for rendering a menu tree.
menu_tree_page_data Gets the data structure for a named menu tree, based on the current page.
menu_tree_set_path Sets the path for determining the active trail of the specified menu tree.
menu_unserialize Unserializes menu data, using a map to replace path elements.
template_preprocess_menu_tree Implements template_preprocess_HOOK() for theme_menu_tree().
theme_menu_link Returns HTML for a menu link and submenu.
theme_menu_local_action Returns HTML for a single local action link.
theme_menu_local_task Returns HTML for a single local task link.
theme_menu_local_tasks Returns HTML for primary and secondary local tasks.
theme_menu_tree Returns HTML for a wrapper for a menu sub-tree.
_menu_build_tree Builds a menu tree.
_menu_check_access Checks access to a menu item using the access callback.
_menu_check_rebuild Checks whether a menu_rebuild() is necessary.
_menu_clear_page_cache Clears the page and block caches at most twice per page load.
_menu_delete_item Deletes a single menu link.
_menu_find_router_path Finds the router path which will serve this path.
_menu_item_localize Localizes the router item title using t() or another callback.
_menu_link_build Builds a link from a router item.
_menu_link_find_parent Finds a possible parent for a given menu link.
_menu_link_map_translate Translates the path elements in the map using any to_arg helper function.
_menu_link_move_children Updates the children of a menu link that is being moved.
_menu_link_parents_set Sets the p1 through p9 values for a menu link being saved.
_menu_link_translate Provides menu link access control, translation, and argument handling.
_menu_load_objects Loads objects into the map as defined in the $item['load_functions'].
_menu_navigation_links_rebuild Builds menu links for the items in the menu router.
_menu_router_build Builds the router table based on the data from hook_menu().
_menu_router_cache Stores the menu router if we have it in memory.
_menu_router_save Saves data from menu_router_build() to the router table.
_menu_set_expanded_menus Updates a list of menus with expanded items.
_menu_site_is_offline Checks whether the site is in maintenance mode.
_menu_translate Handles dynamic path translation and menu access control.
_menu_tree_check_access Sorts the menu tree and recursively checks access for each item.
_menu_tree_data Builds the data representing a menu tree.
_menu_update_parental_status Checks and updates the 'has_children' status for the parent of a link.

Constants

Namesort descending Description
MENU_ACCESS_DENIED Menu status code -- Access denied.
MENU_CALLBACK Menu type -- A hidden, internal callback, typically used for API calls.
MENU_CONTEXT_INLINE Internal menu flag: Local task should be displayed inline.
MENU_CONTEXT_NONE Internal menu flag: Invisible local task.
MENU_CONTEXT_PAGE Internal menu flag: Local task should be displayed in page context.
MENU_CREATED_BY_ADMIN Internal menu flag -- menu item was created by administrator.
MENU_DEFAULT_LOCAL_TASK Menu type -- The "default" local task, which is initially active.
MENU_FOUND Internal menu status code -- Menu item was found.
MENU_IS_LOCAL_ACTION Internal menu flag -- menu item is a local action.
MENU_IS_LOCAL_TASK Internal menu flag -- menu item is a local task.
MENU_IS_ROOT Internal menu flag -- menu item is the root of the menu tree.
MENU_LINKS_TO_PARENT Internal menu flag -- menu item links back to its parent.
MENU_LOCAL_ACTION Menu type -- An action specific to the parent, usually rendered as a link.
MENU_LOCAL_TASK Menu type -- A task specific to the parent item, usually rendered as a tab.
MENU_MAX_DEPTH The maximum depth of a menu links tree - matches the number of p columns.
MENU_MAX_PARTS The maximum number of path elements for a menu callback
MENU_MODIFIED_BY_ADMIN Internal menu flag -- menu item can be modified by administrator.
MENU_NORMAL_ITEM Menu type -- A "normal" menu item that's shown in menu and breadcrumbs.
MENU_NOT_FOUND Menu status code -- Not found.
MENU_PREFERRED_LINK Reserved key to identify the most specific menu link for a given path.
MENU_SITE_OFFLINE Internal menu status code -- Menu item inaccessible because site is offline.
MENU_SITE_ONLINE Internal menu status code -- Everything is working fine.
MENU_SUGGESTED_ITEM Menu type -- A normal menu item, hidden until enabled by an administrator.
MENU_VISIBLE_IN_BREADCRUMB Internal menu flag -- menu item is visible in the breadcrumb.
MENU_VISIBLE_IN_TREE Internal menu flag -- menu item is visible in the menu tree.

Comments

hermes_costell’s picture

Code to copy a menu:

$my_new_menu = array();
$my_new_menu['menu_name'] = 'new-menu-name';
$my_new_menu['title'] = 'i like cake';
$my_new_menu['description'] =  'This is the best menu ever.';
menu_save($my_new_menu);
	
$old_links = menu_load_links('old-menu-name');
$cloned_array = menu_links_clone($old_links,$my_new_menu['menu_name']);
if(count($cloned_array) >0){
   foreach($cloned_array as $new_menu_item){
      menu_link_save($new_menu_item);
   }
}
menu_cache_clear_all();
hermes_costell’s picture

Update: It turns out that menu_links_clone will only work as expected for a menu that is 1 level deep.
Please see
http://api.drupal.org/api/drupal/includes!menu.inc/function/menu_links_clone/7#comment-28879
and
http://drupal.org/node/252200#comment-5892570

kris-o3’s picture

i've addressed this need in a module i just created yesterday (i needed to be able to use one custom menu versus another based on the incoming request's subdomain).. copies one custom menu to one being created, maintaining hierarchy.

http://drupal.org/sandbox/kris-o3/1853420