menu.inc 44.8 KB
Newer Older
Dries's avatar
 
Dries committed
1
<?php
2
// $Id$
Kjartan's avatar
Kjartan committed
3

4 5 6 7 8
/**
 * @file
 * API for the Drupal menu system.
 */

Dries's avatar
 
Dries committed
9 10 11
/**
 * @defgroup menu Menu system
 * @{
Dries's avatar
 
Dries committed
12
 * Define the navigation menus, and route page requests to code based on URLs.
Dries's avatar
 
Dries committed
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
 *
 * The Drupal menu system drives both the navigation system from a user
 * perspective and the callback system that Drupal uses to respond to URLs
 * passed from the browser. For this reason, a good understanding of the
 * menu system is fundamental to the creation of complex modules.
 *
 * Drupal's menu system follows a simple hierarchy defined by paths.
 * Implementations of hook_menu() define menu items and assign them to
 * paths (which should be unique). The menu system aggregates these items
 * and determines the menu hierarchy from the paths. For example, if the
 * paths defined were a, a/b, e, a/b/c/d, f/g, and a/b/h, the menu system
 * would form the structure:
 * - a
 *   - a/b
 *     - a/b/c/d
 *     - a/b/h
 * - e
 * - f/g
 * Note that the number of elements in the path does not necessarily
 * determine the depth of the menu item in the tree.
 *
 * When responding to a page request, the menu system looks to see if the
 * path requested by the browser is registered as a menu item with a
 * callback. If not, the system searches up the menu tree for the most
 * complete match with a callback it can find. If the path a/b/i is
 * requested in the tree above, the callback for a/b would be used.
 *
Steven Wittens's avatar
Steven Wittens committed
40
 * The found callback function is called with any arguments specified
41
 * in the "page arguments" attribute of its menu item. The
Steven Wittens's avatar
Steven Wittens committed
42 43 44 45
 * attribute must be an array. After these arguments, any remaining
 * components of the path are appended as further arguments. In this
 * way, the callback for a/b above could respond to a request for
 * a/b/i differently than a request for a/b/j.
Dries's avatar
 
Dries committed
46 47 48 49
 *
 * For an illustration of this process, see page_example.module.
 *
 * Access to the callback functions is also protected by the menu system.
50 51 52 53
 * The "access callback" with an optional "access arguments" of each menu
 * item is called before the page callback proceeds. If this returns TRUE,
 * then access is granted; if FALSE, then access is denied. Menu items may
 * omit this attribute to use the value provided by an ancestor item.
Dries's avatar
 
Dries committed
54 55 56 57 58 59 60 61 62 63 64 65 66
 *
 * In the default Drupal interface, you will notice many links rendered as
 * tabs. These are known in the menu system as "local tasks", and they are
 * rendered as tabs by default, though other presentations are possible.
 * Local tasks function just as other menu items in most respects. It is
 * convention that the names of these tasks should be short verbs if
 * possible. In addition, a "default" local task should be provided for
 * each set. When visiting a local task's parent menu item, the default
 * local task will be rendered as if it is selected; this provides for a
 * normal tab user experience. This default task is special in that it
 * links not to its provided path, but to its parent item's path instead.
 * The default task's path is only used to place it appropriately in the
 * menu hierarchy.
67 68 69 70 71
 *
 * Everything described so far is stored in the menu_router table. The
 * menu_links table holds the visible menu links. By default these are
 * derived from the same hook_menu definitons, however you are free to
 * add more with menu_link_save().
Dries's avatar
 
Dries committed
72 73
 */

Dries's avatar
 
Dries committed
74
/**
Dries's avatar
 
Dries committed
75
 * @name Menu flags
Dries's avatar
 
Dries committed
76
 * @{
Dries's avatar
 
Dries committed
77 78
 * Flags for use in the "type" attribute of menu items.
 */
Dries's avatar
 
Dries committed
79

Dries's avatar
 
Dries committed
80 81 82
define('MENU_IS_ROOT', 0x0001);
define('MENU_VISIBLE_IN_TREE', 0x0002);
define('MENU_VISIBLE_IN_BREADCRUMB', 0x0004);
83
define('MENU_MODIFIED_BY_ADMIN', 0x0008);
Dries's avatar
 
Dries committed
84
define('MENU_MODIFIABLE_BY_ADMIN', 0x0010);
85 86 87 88
define('MENU_CREATED_BY_ADMIN', 0x0020);
define('MENU_IS_LOCAL_TASK', 0x0040);
define('MENU_EXPANDED', 0x0080);
define('MENU_LINKS_TO_PARENT', 0x00100);
Dries's avatar
 
Dries committed
89

Dries's avatar
 
Dries committed
90
/**
Dries's avatar
 
Dries committed
91
 * @} End of "Menu flags".
Dries's avatar
 
Dries committed
92 93 94
 */

/**
Dries's avatar
 
Dries committed
95
 * @name Menu item types
Dries's avatar
 
Dries committed
96 97 98 99
 * @{
 * Menu item definitions provide one of these constants, which are shortcuts for
 * combinations of the above flags.
 */
Dries's avatar
 
Dries committed
100

Dries's avatar
 
Dries committed
101 102
/**
 * Normal menu items show up in the menu tree and can be moved/hidden by
Dries's avatar
 
Dries committed
103 104
 * the administrator. Use this for most menu items. It is the default value if
 * no menu item type is specified.
Dries's avatar
 
Dries committed
105 106
 */
define('MENU_NORMAL_ITEM', MENU_VISIBLE_IN_TREE | MENU_VISIBLE_IN_BREADCRUMB | MENU_MODIFIABLE_BY_ADMIN);
107

Dries's avatar
 
Dries committed
108 109
/**
 * Callbacks simply register a path so that the correct function is fired
Dries's avatar
 
Dries committed
110
 * when the URL is accessed. They are not shown in the menu.
Dries's avatar
 
Dries committed
111 112
 */
define('MENU_CALLBACK', MENU_VISIBLE_IN_BREADCRUMB);
Dries's avatar
 
Dries committed
113

Dries's avatar
 
Dries committed
114
/**
Dries's avatar
 
Dries committed
115 116
 * Modules may "suggest" menu items that the administrator may enable. They act
 * just as callbacks do until enabled, at which time they act like normal items.
Dries's avatar
 
Dries committed
117
 */
118
define('MENU_SUGGESTED_ITEM', MENU_MODIFIABLE_BY_ADMIN | MENU_VISIBLE_IN_BREADCRUMB);
Dries's avatar
 
Dries committed
119 120

/**
Dries's avatar
 
Dries committed
121 122 123
 * Local tasks are rendered as tabs by default. Use this for menu items that
 * describe actions to be performed on their parent item. An example is the path
 * "node/52/edit", which performs the "edit" task on "node/52".
Dries's avatar
 
Dries committed
124 125 126
 */
define('MENU_LOCAL_TASK', MENU_IS_LOCAL_TASK);

Dries's avatar
 
Dries committed
127 128 129 130 131 132
/**
 * Every set of local tasks should provide one "default" task, that links to the
 * same path as its parent when clicked.
 */
define('MENU_DEFAULT_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_LINKS_TO_PARENT);

Dries's avatar
 
Dries committed
133
/**
Dries's avatar
 
Dries committed
134
 * @} End of "Menu item types".
Dries's avatar
 
Dries committed
135 136 137 138 139
 */

/**
 * @name Menu status codes
 * @{
Dries's avatar
 
Dries committed
140 141
 * Status codes for menu callbacks.
 */
Dries's avatar
 
Dries committed
142

Dries's avatar
 
Dries committed
143 144 145
define('MENU_FOUND', 1);
define('MENU_NOT_FOUND', 2);
define('MENU_ACCESS_DENIED', 3);
146
define('MENU_SITE_OFFLINE', 4);
Dries's avatar
 
Dries committed
147

Dries's avatar
 
Dries committed
148
/**
Dries's avatar
 
Dries committed
149
 * @} End of "Menu status codes".
Dries's avatar
 
Dries committed
150
 */
151

152 153

/**
154 155 156 157
 * @} End of "Menu operations."
 */

/**
158
 * @Name Menu tree parameters
159
 * @{
160
 * Menu tree
161 162
 */

163 164
 /**
 * The maximum number of path elements for a menu callback
165
 */
166 167
define('MENU_MAX_PARTS', 6);

168 169

/**
170
 * The maximum depth of a menu links tree - matches the number of p columns.
171
 */
172 173
define('MENU_MAX_DEPTH', 6);

174 175

/**
176
 * @} End of "Menu tree parameters".
177 178
 */

179
/**
180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
 * Returns the ancestors (and relevant placeholders) for any given path.
 *
 * For example, the ancestors of node/12345/edit are:
 *
 * node/12345/edit
 * node/12345/%
 * node/%/edit
 * node/%/%
 * node/12345
 * node/%
 * node
 *
 * To generate these, we will use binary numbers. Each bit represents a
 * part of the path. If the bit is 1, then it represents the original
 * value while 0 means wildcard. If the path is node/12/edit/foo
 * then the 1011 bitstring represents node/%/edit/foo where % means that
 * any argument matches that part.
 *
 * @param $parts
 *   An array of path parts, for the above example
 *   array('node', '12345', 'edit').
 * @return
 *   An array which contains the ancestors and placeholders. Placeholders
203
 *   simply contain as many '%s' as the ancestors.
204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224
 */
function menu_get_ancestors($parts) {
  $n1 = count($parts);
  $placeholders = array();
  $ancestors = array();
  $end = (1 << $n1) - 1;
  $length = $n1 - 1;
  for ($i = $end; $i > 0; $i--) {
    $current = '';
    $count = 0;
    for ($j = $length; $j >= 0; $j--) {
      if ($i & (1 << $j)) {
        $count++;
        $current .= $parts[$length - $j];
      }
      else {
        $current .= '%';
      }
      if ($j) {
        $current .= '/';
      }
Dries's avatar
 
Dries committed
225
    }
226 227 228 229
    // If the number was like 10...0 then the next number will be 11...11,
    // one bit less wide.
    if ($count == 1) {
      $length--;
Dries's avatar
 
Dries committed
230
    }
231 232
    $placeholders[] = "'%s'";
    $ancestors[] = $current;
233
  }
234
  return array($ancestors, $placeholders);
Dries's avatar
 
Dries committed
235 236 237
}

/**
238 239 240 241
 * The menu system uses serialized arrays stored in the database for
 * arguments. However, often these need to change according to the
 * current path. This function unserializes such an array and does the
 * necessary change.
Dries's avatar
 
Dries committed
242
 *
243
 * Integer values are mapped according to the $map parameter. For
244 245 246 247 248
 * example, if unserialize($data) is array('view', 1) and $map is
 * array('node', '12345') then 'view' will not be changed because
 * it is not an integer, but 1 will as it is an integer. As $map[1]
 * is '12345', 1 will be replaced with '12345'. So the result will
 * be array('node_load', '12345').
249
 *
250 251 252 253
 * @param @data
 *   A serialized array.
 * @param @map
 *   An array of potential replacements.
254
 * @return
255
 *   The $data array unserialized and mapped.
256
 */
257 258 259 260 261 262 263 264
function menu_unserialize($data, $map) {
  if ($data = unserialize($data)) {
    foreach ($data as $k => $v) {
      if (is_int($v)) {
        $data[$k] = isset($map[$v]) ? $map[$v] : '';
      }
    }
    return $data;
265
  }
266 267
  else {
    return array();
268 269 270 271
  }
}

/**
272
 * Get the menu callback for the a path.
273
 *
274
 * @param $path
275
 *   A path, or NULL for the current path
276
 */
277
function menu_get_item($path = NULL) {
278 279 280 281 282
  static $items;
  if (!isset($path)) {
    $path = $_GET['q'];
  }
  if (!isset($items[$path])) {
283
    $original_map = arg(NULL, $path);
284
    $parts = array_slice($original_map, 0, MENU_MAX_PARTS);
285
    list($ancestors, $placeholders) = menu_get_ancestors($parts);
286 287 288 289 290 291 292

    if ($item = db_fetch_object(db_query_range('SELECT * FROM {menu_router} WHERE path IN ('. implode (',', $placeholders) .') ORDER BY fit DESC', $ancestors, 0, 1))) {

      $map = _menu_translate($item, $original_map);
      if ($map === FALSE) {
        $items[$path] = FALSE;
        return FALSE;
293 294 295 296
      }
      if ($item->access) {
        $item->map = $map;
        $item->page_arguments = array_merge(menu_unserialize($item->page_arguments, $map), array_slice($parts, $item->number_parts));
Dries's avatar
 
Dries committed
297 298
      }
    }
299
    $items[$path] = $item;
Dries's avatar
 
Dries committed
300
  }
301
  return drupal_clone($items[$path]);
Dries's avatar
 
Dries committed
302 303 304
}

/**
305
 * Execute the page callback associated with the current path
Dries's avatar
 
Dries committed
306 307
 */
function menu_execute_active_handler() {
308 309
  if ($item = menu_get_item()) {
    return $item->access ? call_user_func_array($item->page_callback, $item->page_arguments) : MENU_ACCESS_DENIED;
Dries's avatar
 
Dries committed
310
  }
311 312
  return MENU_NOT_FOUND;
}
Dries's avatar
 
Dries committed
313

314
/**
315
 * Loads objects into the map as defined in the $item->load_functions.
316
 *
317 318 319 320 321
 * @param $item
 *   A menu item object
 * @param $map
 *   An array of path arguments (ex: array('node', '5'))
 * @return
322 323 324
 *   Returns TRUE for success, FALSE if an object cannot be loaded
 */
function _menu_load_objects($item, &$map) {
325
  if ($item->load_functions) {
326
    $load_functions = unserialize($item->load_functions);
327 328 329 330 331
    $path_map = $map;
    foreach ($load_functions as $index => $function) {
      if ($function) {

        $return = $function(isset($path_map[$index]) ? $path_map[$index] : '');
332 333
        // If callback returned an error or there is no callback, trigger 404.
        if ($return === FALSE) {
334
          $item->access = FALSE;
335
          $map = FALSE;
336
          return FALSE;
337 338 339 340 341
        }
        $map[$index] = $return;
      }
    }
  }
342 343 344 345 346 347 348 349 350 351 352 353 354 355
  return TRUE;
}

/**
 * Check access to a menu item using the access callback
 *
 * @param $item
 *   A menu item object
 * @param $map
 *   An array of path arguments (ex: array('node', '5'))
 * @return
 *   $item->access becomes TRUE if the item is accessible, FALSE otherwise.
 */
function _menu_check_access(&$item, $map) {
356 357
  // Determine access callback, which will decide whether or not the current user has
  // access to this path.
358
  $callback = $item->access_callback;
359
  // Check for a TRUE or FALSE value.
360
  if (is_numeric($callback)) {
361
    $item->access = $callback;
Dries's avatar
 
Dries committed
362
  }
363 364 365 366 367
  else {
    $arguments = menu_unserialize($item->access_arguments, $map);
    // As call_user_func_array is quite slow and user_access is a very common
    // callback, it is worth making a special case for it.
    if ($callback == 'user_access') {
368
      $item->access = (count($arguments) == 1) ? user_access($arguments[0]) : user_access($arguments[0], $arguments[1]);
369 370
    }
    else {
371
      $item->access = call_user_func_array($callback, $arguments);
372
    }
Dries's avatar
 
Dries committed
373
  }
374
}
375

376
function _menu_item_localize(&$item) {
377
  // Translate the title to allow storage of English title strings
378 379
  // in the database, yet display of them in the language required
  // by the current user.
380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403
  $callback = $item->title_callback;
  // t() is a special case. Since it is used very close to all the time,
  // we handle it directly instead of using indirect, slower methods.
  if ($callback == 't') {
    if (empty($item->title_arguments)) {
      $item->title = t($item->title);
    }
    else {
      $item->title = t($item->title, unserialize($item->title_arguments));
    }
  }
  else {
    if (empty($item->title_arguments)) {
      $item->title = $callback($item->title);
    }
    else {
      $item->title = call_user_func_array($callback, unserialize($item->title_arguments));
    }
  }

  // Translate description, see the motivation above.
  if (!empty($item->description)) {
    $item->description = t($item->description);
  }
404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529
}

/**
 * Handles dynamic path translation and menu access control.
 *
 * When a user arrives on a page such as node/5, this function determines
 * what "5" corresponds to, by inspecting the page's menu path definition,
 * node/%node. This will call node_load(5) to load the corresponding node
 * object.
 *
 * It also works in reverse, to allow the display of tabs and menu items which
 * contain these dynamic arguments, translating node/%node to node/5.
 *
 * Translation of menu item titles and descriptions are done here to
 * allow for storage of English strings in the database, and translation
 * to the language required to generate the current page
 *
 * @param $item
 *   A menu item object
 * @param $map
 *   An array of path arguments (ex: array('node', '5'))
 * @param $to_arg
 *   Execute $item->to_arg_functions or not. Use only if you want to render a
 *   path from the menu table, for example tabs.
 * @return
 *   Returns the map with objects loaded as defined in the
 *   $item->load_functions. $item->access becomes TRUE if the item is
 *   accessible, FALSE otherwise. $item->href is set according to the map.
 *   If an error occurs during calling the load_functions (like trying to load
 *   a non existing node) then this function return FALSE.
 */
function _menu_translate(&$item, $map, $to_arg = FALSE) {
  $path_map = $map;
  if (!_menu_load_objects($item, $map)) {
    // An error occurred loading an object.
    $item->access = FALSE;
    return FALSE;
  }
  if ($to_arg) {
    _menu_link_map_translate($path_map, $item->to_arg_functions);
  }

  // Generate the link path for the page request or local tasks.
  $link_map = explode('/', $item->path);
  for ($i = 0; $i < $item->number_parts; $i++) {
    if ($link_map[$i] == '%') {
      $link_map[$i] = $path_map[$i];
    }
  }
  $item->href = implode('/', $link_map);
  _menu_check_access($item, $map);

  _menu_item_localize($item);

  return $map;
}

/**
 * This function translates the path elements in the map using any to_arg
 * helper function. These functions take an argument and return an object.
 * See http://drupal.org/node/109153 for more information.
 *
 * @param map
 *   An array of path arguments (ex: array('node', '5'))
 * @param $to_arg_functions
 *   An array of helper function (ex: array(1 => 'node_load'))
 */
function _menu_link_map_translate(&$map, $to_arg_functions) {
  if ($to_arg_functions) {
    $to_arg_functions = unserialize($to_arg_functions);
    foreach ($to_arg_functions as $index => $function) {
      // Translate place-holders into real values.
      $arg = $function(!empty($map[$index]) ? $map[$index] : '');
      if (!empty($map[$index]) || isset($arg)) {
        $map[$index] = $arg;
      }
      else {
        unset($map[$index]);
      }
    }
  }
}

/**
 * This function is similar to _menu_translate() but does link-specific
 * preparation such as always calling to_arg functions
 *
 * @param $item
 *   A menu item object
 * @return
 *   Returns the map of path arguments with objects loaded as defined in the
 *   $item->load_functions.
 *   $item->access becomes TRUE if the item is accessible, FALSE otherwise.
 *   $item->href is altered if there is a to_arg function.
 */
function _menu_link_translate(&$item) {
  if ($item->external) {
    $item->access = 1;
    $map = array();
  }
  else {
    $map = explode('/', $item->href);
    _menu_link_map_translate($map, $item->to_arg_functions);
    $item->href = implode('/', $map);

    // Note- skip callbacks without real values for their arguments
    if (strpos($item->href, '%') !== FALSE) {
      $item->access = FALSE;
      return FALSE;
    }
    if (!_menu_load_objects($item, $map)) {
      // An error occured loading an object
      $item->access = FALSE;
      return FALSE;
    }
    // TODO: menu_tree may set this ahead of time for links to nodes
    if (!isset($item->access)) {
      _menu_check_access($item, $map);
    }
    // If the link title matches that of a router item, localize it.
    if (isset($item->title) && ($item->title == $item->link_title)) {
      _menu_item_localize($item);
      $item->link_title = $item->title;
    }
  }
  $item->options = unserialize($item->options);
530

531
  return $map;
Dries's avatar
 
Dries committed
532 533
}

534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554
/**
 * Returns a rendered menu tree. The tree is expanded based on the current
 * path and dynamic paths are also changed according to the defined to_arg
 * functions (for example the 'My account' link is changed from user/% to
 * a link with the current user's uid).
 *
 * @param $menu_name
 *   The name of the menu.
 * @return
 *   The rendered HTML of that menu on the current page.
 */
function menu_tree($menu_name = 'navigation') {
  static $menu_output = array();

  if (!isset($menu_output[$menu_name])) {
    $tree = menu_tree_data($menu_name);
    $menu_output[$menu_name] = menu_tree_output($tree);
  }
  return $menu_output[$menu_name];
}

Dries's avatar
 
Dries committed
555
/**
556
 * Returns a rendered menu tree.
557 558 559 560 561
 *
 * @param $tree
 *   A data structure representing the tree as returned from menu_tree_data.
 * @return
 *   The rendered HTML of that data structure.
Dries's avatar
 
Dries committed
562
 */
563 564 565 566 567 568 569 570 571 572 573 574
function menu_tree_output($tree) {
  $output = '';

  foreach ($tree as $data) {
    if (!$data['link']->hidden) {
      $link = theme('menu_item_link', $data['link']);
      if ($data['below']) {
        $output .= theme('menu_item', $link, $data['link']->has_children, menu_tree_output($data['below']));
      }
      else {
        $output .= theme('menu_item', $link, $data['link']->has_children);
      }
575
    }
576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636
  }
  return $output ? theme('menu_tree', $output) : '';
}

/**
 * Get the data structure representing a named menu tree, based on the current
 * page. The tree order is maintained by storing each parent in an invidual
 * field, see http://drupal.org/node/141866 for more.
 *
 * @param $menu_name
 *   The named menu links to return
 * @return
 *   An array of menu links, in the order they should be rendered. The array
 *   is a list of associative arrays -- these have two keys, link and below.
 *   link is a menu item, ready for theming as a link. Below represents the
 *   submenu below the link if there is one and it is a similar list that was
 *   described so far.
 */
function menu_tree_data($menu_name = 'navigation') {
  static $tree = array();

  if ($item = menu_get_item()) {
    if (!isset($tree[$menu_name])) {
      if ($item->access) {
        $parents = db_fetch_array(db_query("SELECT p1, p2, p3, p4, p5 FROM {menu_links} WHERE menu_name = '%s' AND href = '%s'", $menu_name, $item->href));
        // We may be on a local task that's not in the links
        // TODO how do we handle the case like a local task on a specific node in the menu?
        if (empty($parents)) {
          $parents = db_fetch_array(db_query("SELECT p1, p2, p3, p4, p5 FROM {menu_links} WHERE menu_name = '%s' AND href = '%s'", $menu_name, $item->tab_root));
        }
        $parents[] = '0';

        $args = $parents = array_unique($parents);
        $placeholders = implode(', ', array_fill(0, count($args), '%d'));
        $expanded = variable_get('menu_expanded', array());
        if (in_array($menu_name, $expanded)) {
          do {
            $result = db_query("SELECT mlid FROM {menu_links} WHERE expanded != 0 AND AND has_children != 0 AND menu_name = '%s' AND plid IN (". $placeholders .') AND mlid NOT IN ('. $placeholders .')', array_merge(array($menu_name), $args, $args));
            while ($item = db_fetch_array($result)) {
              $args[] = $item['mlid'];
            }
            $placeholders = implode(', ', array_fill(0, count($args), '%d'));
          } while (db_num_rows($result));
        }
        array_unshift($args, $menu_name);
      }
      // Show the root menu for access denied.
      else {
        $args = array('navigation', '0');
        $placeholders = '%d';
      }
      // LEFT JOIN since there is no match in {menu_router} for an external link.
      // No need to order by p6 - there is a sort by weight later.
      list(, $tree[$menu_name]) = _menu_tree_data(db_query("
        SELECT *, ml.weight + 50000 AS weight FROM {menu_links} ml LEFT JOIN {menu_router} m ON m.path = ml.router_path
        WHERE ml.menu_name = '%s' AND ml.plid IN (". $placeholders .")
        ORDER BY p1 ASC, p2 ASC, p3 ASC, p4 ASC, p5 ASC", $args), $parents);

      // TODO: cache_set() for the untranslated links
      // TODO: special case node links and access check via db_rewite_sql()
      // TODO: access check / _menu_link_translate on each here
637
    }
638
    return $tree[$menu_name];
639
  }
Dries's avatar
 
Dries committed
640 641
}

642

643
/**
644
 * Build the data representing a menu tree.
645 646 647 648 649 650 651
 *
 * The function is a bit complex because the rendering of an item depends on
 * the next menu item. So we are always rendering the element previously
 * processed not the current one.
 *
 * @param $result
 *   The database result.
652 653 654
 * @param $parents
 *   An array of the plid values that represent the path from the current page
 *   to the root of the menu tree.
655 656
 * @param $depth
 *   The depth of the current menu tree.
657 658
 * @param $previous_element
 *   The previous menu link in the current menu tree.
659
 * @return
660
 *   See menu_tree_data for a description of the data structure.
661
 */
662
function _menu_tree_data($result = NULL, $parents = array(), $depth = 1, $previous_element = '') {
663
  $remnant = NULL;
664
  $tree = array();
665
  while ($item = db_fetch_object($result)) {
666
    // Access check and handle dynamic path translation.
667 668 669
    // TODO - move this to the parent function, so the untranslated link data
    // can be cached.
    _menu_link_translate($item);
670
    if (!$item->access) {
671
      continue;
Dries's avatar
 
Dries committed
672
    }
673 674 675 676 677 678
    // We need to determine if we're on the path to root so we can later build
    // the correct active trail and breadcrumb.
    $item->path_to_root = in_array($item->mlid, $parents);
    // The weights are uniform 5 digits because of the 50000 offset in the
    // query. We add mlid at the end of the index to insure uniqueness.
    $index = $previous_element ? ($previous_element->weight .' '. $previous_element->title . $previous_element->mlid) : '';
679
    // The current item is the first in a new submenu.
680
    if ($item->depth > $depth) {
681 682 683 684 685 686 687 688 689 690 691
      // _menu_tree returns an item and the menu tree structure.
      list($item, $below) = _menu_tree_data($result, $parents, $item->depth, $item);
      $tree[$index] = array(
        'link' => $previous_element,
        'below' => $below,
      );
      // We need to fall back one level.
      if ($item->depth < $depth) {
        ksort($tree);
        return array($item, $tree);
      }
692
      // This will be the link to be output in the next iteration.
693
      $previous_element = $item;
Dries's avatar
 
Dries committed
694
    }
695
    // We are in the same menu. We render the previous element, $previous_element.
696
    elseif ($item->depth == $depth) {
697 698 699 700 701 702
      if ($previous_element) { // Only the first time
        $tree[$index] = array(
          'link' => $previous_element,
          'below' => '',
        );
      }
703
      // This will be the link to be output in the next iteration.
704
      $previous_element = $item;
Dries's avatar
 
Dries committed
705
    }
706
    // The submenu ended with the previous item, so pass back the current item.
707
    else {
708
      $remnant = $item;
709
      break;
Dries's avatar
 
Dries committed
710
    }
Dries's avatar
 
Dries committed
711
  }
712
  if ($previous_element) {
713
    // We have one more link dangling.
714 715 716 717
    $tree[$previous_element->weight .' '. $previous_element->title .' '. $previous_element->mlid] = array(
      'link' => $previous_element,
      'below' => '',
    );
718
  }
719
  ksort($tree);
720
  return array($remnant, $tree);
Dries's avatar
 
Dries committed
721 722
}

Dries's avatar
 
Dries committed
723
/**
724
 * Generate the HTML output for a single menu link.
Dries's avatar
 
Dries committed
725
 */
726 727
function theme_menu_item_link($link) {
  return l($link->link_title, $link->href, $link->options);
Dries's avatar
 
Dries committed
728 729
}

Dries's avatar
 
Dries committed
730
/**
731
 * Generate the HTML output for a menu tree
Dries's avatar
 
Dries committed
732
 */
733 734 735 736 737 738 739 740
function theme_menu_tree($tree) {
  return '<ul class="menu">'. $tree .'</ul>';
}

/**
 * Generate the HTML output for a menu item and submenu.
 */
function theme_menu_item($link, $has_children, $menu = '') {
741
  return '<li class="'. ($menu ? 'expanded' : ($has_children ? 'collapsed' : 'leaf')) .'">'. $link . $menu .'</li>'."\n";
742 743 744
}

function theme_menu_local_task($link, $active = FALSE) {
745
  return '<li '. ($active ? 'class="active" ' : '') .'>'. $link .'</li>';
746
}
Dries's avatar
 
Dries committed
747

Dries's avatar
 
Dries committed
748
/**
Dries's avatar
 
Dries committed
749 750
 * Returns the help associated with the active menu item.
 */
751
function menu_get_active_help() {
752

Dries's avatar
 
Dries committed
753
  $output = '';
754
  $item = menu_get_item();
Dries's avatar
 
Dries committed
755

756
  if (!$item || !$item->access) {
Dries's avatar
 
Dries committed
757 758 759
    // Don't return help text for areas the user cannot access.
    return;
  }
760
  $path = ($item->type == MENU_DEFAULT_LOCAL_TASK) ? $item->tab_parent : $item->path;
Dries's avatar
 
Dries committed
761

Dries's avatar
 
Dries committed
762 763 764
  foreach (module_list() as $name) {
    if (module_hook($name, 'help')) {
      if ($temp = module_invoke($name, 'help', $path)) {
765
        $output .= $temp ."\n";
Dries's avatar
 
Dries committed
766
      }
767
      if (module_hook('help', 'page')) {
768
        if (arg(0) == "admin") {
769 770
          if (module_invoke($name, 'help', 'admin/help#'. arg(2)) && !empty($output)) {
            $output .= theme("more_help_link", url('admin/help/'. arg(2)));
771
          }
Dries's avatar
 
Dries committed
772 773
        }
      }
Dries's avatar
 
Dries committed
774
    }
Dries's avatar
 
Dries committed
775
  }
Dries's avatar
 
Dries committed
776
  return $output;
777 778
}

779
/**
780
 * Build a list of named menus.
781
 */
782 783 784 785 786 787 788 789 790
function menu_get_names($reset = FALSE) {
  static $names;
  // TODO - use cache system to save this

  if ($reset || empty($names)) {
    $names = array();
    $result = db_query("SELECT DISTINCT(menu_name) FROM {menu_links} ORDER BY menu_name");
    while ($name = db_fetch_array($result)) {
      $names[] = $name['menu_name'];
791 792
    }
  }
793
  return $names;
794 795
}

796
function menu_primary_links() {
797 798
  $tree = menu_tree_data('primary links');
  return array();
Dries's avatar
 
Dries committed
799 800
}

801
function menu_secondary_links() {
802 803
  $tree = menu_tree_data('secondary links');
  return array();
Dries's avatar
 
Dries committed
804 805
}

806 807 808 809
/**
 * Collects the local tasks (tabs) for a given level.
 *
 * @param $level
810
 *   The level of tasks you ask for. Primary tasks are 0, secondary are 1.
811 812 813 814
 * @return
 *   An array of links to the tabs.
 */
function menu_local_tasks($level = 0) {
815 816
  static $tabs = array();

817 818
  if (empty($tabs)) {
    $router_item = menu_get_item();
819 820 821
    if (!$router_item || !$router_item->access) {
      return array();
    }
822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850
    // Get all tabs
    $result = db_query("SELECT * FROM {menu_router} WHERE tab_root = '%s' AND tab_parent != '' ORDER BY weight, title", $router_item->tab_root);
    $map = arg();
    $children = array();
    $tab_parent = array();

    while ($item = db_fetch_object($result)) {
      $children[$item->tab_parent][$item->path] = $item;
      $tab_parent[$item->path] = $item->tab_parent;
    }

    // Find all tabs below the current path
    $path = $router_item->path;
    while (isset($children[$path])) {
      $tabs_current = '';
      $next_path = '';
      foreach ($children[$path] as $item) {
         _menu_translate($item, $map, TRUE);
        if ($item->access) {
          $link = l($item->title, $item->href); // TODO options?
          // The default task is always active.
          if ($item->type == MENU_DEFAULT_LOCAL_TASK) {
            $tabs_current .= theme('menu_local_task', $link, TRUE);
            $next_path = $item->path;
          }
          else {
            $tabs_current .= theme('menu_local_task', $link);
          }
        }
851
      }
852 853 854 855 856 857 858 859 860
      $path = $next_path;
      $tabs[$item->number_parts] = $tabs_current;
    }

    // Find all tabs at the same level or above the current one
    $parent = $router_item->tab_parent;
    $path = $router_item->path;
    $current = $router_item;
    while (isset($children[$parent])) {
861
      $tabs_current = '';
862 863 864 865
      $next_path = '';
      $next_parent = '';
      foreach ($children[$parent] as $item) {
         _menu_translate($item, $map, TRUE);
866
        if ($item->access) {
867
          $link = l($item->title, $item->href); // TODO options?
868
          // We check for the active tab.
869
          if ($item->path == $path) {
870
            $tabs_current .= theme('menu_local_task', $link, TRUE);
871 872 873 874
            $next_path = $item->tab_parent;
            if (isset($tab_parent[$next_path])) {
              $next_parent = $tab_parent[$next_path];
            }
875 876 877 878 879
          }
          else {
            $tabs_current .= theme('menu_local_task', $link);
          }
        }
880
      }
881 882 883 884
      $path = $next_path;
      $parent = $next_parent;
      $tabs[$item->number_parts] = $tabs_current;
    }
885 886 887 888
    // Sort by depth
    ksort($tabs);
    // Remove the depth, we are interested only in their relative placement.
    $tabs = array_values($tabs);
889
  }
890 891 892 893
  return isset($tabs[$level]) ? $tabs[$level] : array();
}

function menu_primary_local_tasks() {
894
  return menu_local_tasks(0);
895
}
896

897
function menu_secondary_local_tasks() {
898
  return menu_local_tasks(1);
Dries's avatar
 
Dries committed
899 900
}

901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916
function menu_set_active_menu_name($menu_name = NULL) {
  static $active;

  if (isset($menu_name)) {
    $active = $menu_name;
  }
  elseif (!isset($active)) {
    $active = 'navigation';
  }
  return $active;
}

function menu_get_active_menu_name() {
  return menu_set_active_menu_name();
}

917
function menu_set_active_item() {
Dries's avatar
 
Dries committed
918 919
}

920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961
function menu_set_active_trail($new_trail = NULL) {
  static $trail;

  if (isset($new_trail)) {
    $trail = $new_trail;
  }
  elseif (!isset($trail)) {
    $trail = array();
    $h = array('link_title' => t('Home'), 'href' => '<front>', 'options' => array(), 'type' => 0, 'title' => '');
    $trail[] = (object)$h;
    $item = menu_get_item();
    // We are on a tab.
    if ($item->tab_parent) {
      $href = $item->tab_root;
    }
    else {
      $href = $item->href;
    }
    $tree = menu_tree_data(menu_get_active_menu_name());
    $curr = array_shift($tree);

    while ($curr) {
      if ($curr['link']->href == $href){
        $trail[] = $curr['link'];
        $curr = FALSE;
      }
      else {
        if ($curr['below'] && $curr['link']->path_to_root) {
          $trail[] = $curr['link'];
          $tree = $curr['below'];
        }
        $curr = array_shift($tree);
      }
    }
  }
  return $trail;
}

function menu_get_active_trail() {
  return menu_set_active_trail();
}

962
function menu_set_location() {
Dries's avatar
 
Dries committed
963 964
}

965
function menu_get_active_breadcrumb() {
966
  $breadcrumb = array();
967
  $item = menu_get_item();
968
  if ($item && $item->access) {
969 970 971 972 973 974 975 976 977 978
    $active_trail = menu_get_active_trail();

    foreach ($active_trail as $parent) {
      $breadcrumb[] = l($parent->link_title, $parent->href, $parent->options);
    }
    $end = end($active_trail);

    // Don't show a link to the current page in the breadcrumb trail.
    if ($item->href == $end->href || ($item->type == MENU_DEFAULT_LOCAL_TASK && $end->href != '<front>')) {
      array_pop($breadcrumb);
979
    }
980 981
  }
  return $breadcrumb;
982
}
983

984
function menu_get_active_title() {
985 986 987 988
  $active_trail = menu_get_active_trail();

  foreach (array_reverse($active_trail) as $item) {
    if (!(bool)($item->type & MENU_IS_LOCAL_TASK)) {
989 990 991
      return $item->title;
    }
  }
992
}
993 994

/**
995
 * Get a menu item by its mlid, access checked and link translated for
996 997
 * rendering.
 *
998 999
 * @param $mlid
 *   The mlid of the menu item.
1000 1001 1002 1003
 * @return
 *   A menu object, with $item->access filled and link translated for
 *   rendering.
 */
1004 1005 1006
function menu_get_item_by_mlid($mlid) {
  if ($item = db_fetch_object(db_query("SELECT * FROM {menu_links} ml LEFT JOIN {menu_router} m ON m.path = ml.router_path WHERE mlid = %d", $mlid))) {
    _menu_link_translate($item);
1007 1008 1009 1010 1011 1012
    if ($item->access) {
      return $item;
    }
  }
  return FALSE;
}
1013 1014 1015 1016 1017 1018 1019 1020

/**
 * Returns the rendered local tasks. The default implementation renders
 * them as tabs.
 *
 * @ingroup themeable
 */
function theme_menu_local_tasks() {
1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068
 $output = '';

 if ($primary = menu_primary_local_tasks()) {
   $output .= "<ul class=\"tabs primary\">\n". $primary ."</ul>\n";
 }
 if ($secondary = menu_secondary_local_tasks()) {
   $output .= "<ul class=\"tabs secondary\">\n". $secondary ."</ul>\n";
 }

 return $output;
}

function menu_cache_clear($menu_name = 'navigation') {
  // TODO: starting stub.  This will be called whenever an item is added to or
  // moved from a named menu

}

/**
 * This should be called any time broad changes might have been made to the
 * router items or menu links.
 */
function menu_cache_clear_all() {
  cache_clear_all('*', 'menu_links', TRUE);
  cache_clear_all('*', 'menu_router', TRUE);
}

/**
 * Populate the database representation of the {menu_router} table (router items)
 * and the navigation menu in the {menu_links} table.
 */
function menu_rebuild() {
  menu_cache_clear_all();
  $menu = menu_router_build(TRUE);
  _menu_navigation_links_rebuild($menu);
}

/**
 * Collect, alter and store the menu definitions.
 */
function menu_router_build() {
  db_query('DELETE FROM {menu_router}');
  $callbacks = module_invoke_all('menu');
  // Alter the menu as defined in modules, keys are like user/%user.
  drupal_alter('menu', $callbacks);
  $menu = _menu_router_build($callbacks);
  return $menu;
}
1069

1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088
function _menu_navigation_links_rebuild($menu) {
  // Add normal and suggested items as links.
  $menu_links = array();
  foreach ($menu as $path => $item) {
    if ($item['type'] == MENU_CALLBACK || $item['type'] == MENU_SUGGESTED_ITEM) {
      $item['hidden'] = $item['type'];
    }
    $item += array(
      'menu name' => 'navigation',
      'link_title' => $item['title'],
      'href' => $path,
      'module' => 'system',
      'hidden' => 0,
    );
    // We add nonexisting items.
    if ($item['_visible'] && !db_result(db_query("SELECT COUNT(*) FROM {menu_links} WHERE menu_name = '%s' AND href = '%s'", $item['menu name'], $item['href']))) {
      $menu_links[$path] = $item;
      $sort[$path] = $item['_number_parts'];
    }
1089
  }
1090 1091 1092 1093 1094 1095 1096
  if ($menu_links) {
    // Make sure no child comes before its parent.
    array_multisort($sort, SORT_NUMERIC, $menu_links);

    foreach ($menu_links as $item) {
      menu_link_save($item, $menu);
    }
1097
  }
1098 1099 1100 1101
  $placeholders = implode(', ', array_fill(0, count($menu), "'%s'"));
  // Remove items if their router path does not exist any more.
  db_query('DELETE FROM {menu_links} WHERE router_path NOT IN ('. $placeholders .')', array_keys($menu));
}
1102

1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429
/**
 * Save a menu link.
 *
 * @param $item
 *   An array representing a menu link item. The only mandatory keys are href
 *   and link_title. Possible keys are
 *     menu name   default is navigation
 *     weight      default is 0
 *     expanded    whether the item is expanded.
 *     options     An array of options, @see l for more.
 *     mlid        If it's an existing item, this comes from the database.
 *                 Never set by hand.
 *     plid        The mlid of the parent.
 *     router_path The path of the relevant router item.
 */
function menu_link_save(&$item, $_menu = NULL) {
  static $menu;

  if (isset($_menu)) {
    $menu = $_menu;
  }
  elseif (!isset($menu)) {
    $menu = menu_router_build();
  }

  drupal_alter('menu_link', $item, $menu);

  $item['_external'] = menu_path_is_external($item['href']);
  // Load defaults.
  $item += array(
    'menu name' => 'navigation',
    'weight' => 0,
    'link_title' => '',
    'hidden' => 0,
    'has_children' => 0,
    'expanded' => 0,
    'options' => empty($item['description']) ? array() : array('attributes' => array('title' => $item['description'])),
  );
  $existing_item = array();
  if (isset($item['mlid'])) {
    $existing_item = db_fetch_array(db_query("SELECT * FROM {menu_links} WHERE mlid = %d", $item['mlid']));
  }
  else {
    $existing_item = db_fetch_array(db_query("SELECT * FROM {menu_links} WHERE menu_name = '%s' AND href = '%s'", $item['menu name'], $item['href']));
  }

  if (empty($existing_item)) {
    $item['mlid'] = db_next_id('{menu_links}_mlid');
  }

  $menu_name = $item['menu name'];
  $new_path = !$existing_item || ($existing_item['href'] != $item['href']);

  // Find the parent.
  if (isset($item['plid'])) {
    $parent = db_fetch_array(db_query("SELECT * FROM {menu_links} WHERE mlid = %d", $item['plid']));
  }
  else { //
    $parent_path = $item['href'];
    do {
      $parent_path = substr($parent_path, 0, strrpos($parent_path, '/'));
      $parent = db_fetch_array(db_query("SELECT * FROM {menu_links} WHERE menu_name = '%s' AND href = '%s'", $menu_name, $parent_path));
    } while ($parent === FALSE && $parent_path);
  }
  // Menu callbacks need to be in the links table for breadcrumbs, but can't
  // be parents if they are generated directly from a router item
  if (empty($parent['mlid']) || $parent['hidden'] == MENU_CALLBACK) {
    $item['plid'] =  0;
  }
  else {
    $item[