1 <?php

     2 // $Id: menu.inc,v 1.255.2.31 2009/04/27 12:50:13 goba Exp $

     3 

     4 /**

     5  * @file

     6  * API for the Drupal menu system.

     7  */

     8 

     9 /**

    10  * @defgroup menu Menu system

    11  * @{

    12  * Define the navigation menus, and route page requests to code based on URLs.

    13  *

    14  * The Drupal menu system drives both the navigation system from a user

    15  * perspective and the callback system that Drupal uses to respond to URLs

    16  * passed from the browser. For this reason, a good understanding of the

    17  * menu system is fundamental to the creation of complex modules.

    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. Menu items may

    53  * omit this attribute to use the value provided by an ancestor item.

    54  *

    55  * In the default Drupal interface, you will notice many links rendered as

    56  * tabs. These are known in the menu system as "local tasks", and they are

    57  * rendered as tabs by default, though other presentations are possible.

    58  * Local tasks function just as other menu items in most respects. It is

    59  * convention that the names of these tasks should be short verbs if

    60  * possible. In addition, a "default" local task should be provided for

    61  * each set. When visiting a local task's parent menu item, the default

    62  * local task will be rendered as if it is selected; this provides for a

    63  * normal tab user experience. This default task is special in that it

    64  * links not to its provided path, but to its parent item's path instead.

    65  * The default task's path is only used to place it appropriately in the

    66  * menu hierarchy.

    67  *

    68  * Everything described so far is stored in the menu_router table. The

    69  * menu_links table holds the visible menu links. By default these are

    70  * derived from the same hook_menu definitions, however you are free to

    71  * add more with menu_link_save().

    72  */

    73 

    74 /**

    75  * @name Menu flags

    76  * @{

    77  * Flags for use in the "type" attribute of menu items.

    78  */

    79 

    80 define('MENU_IS_ROOT', 0x0001);

    81 define('MENU_VISIBLE_IN_TREE', 0x0002);

    82 define('MENU_VISIBLE_IN_BREADCRUMB', 0x0004);

    83 define('MENU_LINKS_TO_PARENT', 0x0008);

    84 define('MENU_MODIFIED_BY_ADMIN', 0x0020);

    85 define('MENU_CREATED_BY_ADMIN', 0x0040);

    86 define('MENU_IS_LOCAL_TASK', 0x0080);

    87 

    88 /**

    89  * @} End of "Menu flags".

    90  */

    91 

    92 /**

    93  * @name Menu item types

    94  * @{

    95  * Menu item definitions provide one of these constants, which are shortcuts for

    96  * combinations of the above flags.

    97  */

    98 

    99 /**

   100  * Normal menu items show up in the menu tree and can be moved/hidden by

   101  * the administrator. Use this for most menu items. It is the default value if

   102  * no menu item type is specified.

   103  */

   104 define('MENU_NORMAL_ITEM', MENU_VISIBLE_IN_TREE | MENU_VISIBLE_IN_BREADCRUMB);

   105 

   106 /**

   107  * Callbacks simply register a path so that the correct function is fired

   108  * when the URL is accessed. They are not shown in the menu.

   109  */

   110 define('MENU_CALLBACK', MENU_VISIBLE_IN_BREADCRUMB);

   111 

   112 /**

   113  * Modules may "suggest" menu items that the administrator may enable. They act

   114  * just as callbacks do until enabled, at which time they act like normal items.

   115  * Note for the value: 0x0010 was a flag which is no longer used, but this way

   116  * the values of MENU_CALLBACK and MENU_SUGGESTED_ITEM are separate.

   117  */

   118 define('MENU_SUGGESTED_ITEM', MENU_VISIBLE_IN_BREADCRUMB | 0x0010);

   119 

   120 /**

   121  * Local tasks are rendered as tabs by default. Use this for menu items that

   122  * describe actions to be performed on their parent item. An example is the path

   123  * "node/52/edit", which performs the "edit" task on "node/52".

   124  */

   125 define('MENU_LOCAL_TASK', MENU_IS_LOCAL_TASK);

   126 

   127 /**

   128  * Every set of local tasks should provide one "default" task, that links to the

   129  * same path as its parent when clicked.

   130  */

   131 define('MENU_DEFAULT_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_LINKS_TO_PARENT);

   132 

   133 /**

   134  * @} End of "Menu item types".

   135  */

   136 

   137 /**

   138  * @name Menu status codes

   139  * @{

   140  * Status codes for menu callbacks.

   141  */

   142 

   143 define('MENU_FOUND', 1);

   144 define('MENU_NOT_FOUND', 2);

   145 define('MENU_ACCESS_DENIED', 3);

   146 define('MENU_SITE_OFFLINE', 4);

   147 

   148 /**

   149  * @} End of "Menu status codes".

   150  */

   151 

   152 /**

   153  * @Name Menu tree parameters

   154  * @{

   155  * Menu tree

   156  */

   157 

   158  /**

   159  * The maximum number of path elements for a menu callback

   160  */

   161 define('MENU_MAX_PARTS', 7);

   162 

   163 

   164 /**

   165  * The maximum depth of a menu links tree - matches the number of p columns.

   166  */

   167 define('MENU_MAX_DEPTH', 9);

   168 

   169 

   170 /**

   171  * @} End of "Menu tree parameters".

   172  */

   173 

   174 /**

   175  * Returns the ancestors (and relevant placeholders) for any given path.

   176  *

   177  * For example, the ancestors of node/12345/edit are:

   178  * - node/12345/edit

   179  * - node/12345/%

   180  * - node/%/edit

   181  * - node/%/%

   182  * - node/12345

   183  * - node/%

   184  * - node

   185  *

   186  * To generate these, we will use binary numbers. Each bit represents a

   187  * part of the path. If the bit is 1, then it represents the original

   188  * value while 0 means wildcard. If the path is node/12/edit/foo

   189  * then the 1011 bitstring represents node/%/edit/foo where % means that

   190  * any argument matches that part.  We limit ourselves to using binary

   191  * numbers that correspond the patterns of wildcards of router items that

   192  * actually exists.  This list of 'masks' is built in menu_rebuild().

   193  *

   194  * @param $parts

   195  *   An array of path parts, for the above example

   196  *   array('node', '12345', 'edit').

   197  * @return

   198  *   An array which contains the ancestors and placeholders. Placeholders

   199  *   simply contain as many '%s' as the ancestors.

   200  */

   201 function menu_get_ancestors($parts) {

   202   $number_parts = count($parts);

   203   $placeholders = array();

   204   $ancestors = array();

   205   $length =  $number_parts - 1;

   206   $end = (1 << $number_parts) - 1;

   207   $masks = variable_get('menu_masks', array());

   208   // Only examine patterns that actually exist as router items (the masks).

   209   foreach ($masks as $i) {

   210     if ($i > $end) {

   211       // Only look at masks that are not longer than the path of interest.

   212       continue;

   213     }

   214     elseif ($i < (1 << $length)) {

   215       // We have exhausted the masks of a given length, so decrease the length.

   216       --$length;

   217     }

   218     $current = '';

   219     for ($j = $length; $j >= 0; $j--) {

   220       if ($i & (1 << $j)) {

   221         $current .= $parts[$length - $j];

   222       }

   223       else {

   224         $current .= '%';

   225       }

   226       if ($j) {

   227         $current .= '/';

   228       }

   229     }

   230     $placeholders[] = "'%s'";

   231     $ancestors[] = $current;

   232   }

   233   return array($ancestors, $placeholders);

   234 }

   235 

   236 /**

   237  * The menu system uses serialized arrays stored in the database for

   238  * arguments. However, often these need to change according to the

   239  * current path. This function unserializes such an array and does the

   240  * necessary change.

   241  *

   242  * Integer values are mapped according to the $map parameter. For

   243  * example, if unserialize($data) is array('view', 1) and $map is

   244  * array('node', '12345') then 'view' will not be changed because

   245  * it is not an integer, but 1 will as it is an integer. As $map[1]

   246  * is '12345', 1 will be replaced with '12345'. So the result will

   247  * be array('node_load', '12345').

   248  *

   249  * @param @data

   250  *   A serialized array.

   251  * @param @map

   252  *   An array of potential replacements.

   253  * @return

   254  *   The $data array unserialized and mapped.

   255  */

   256 function menu_unserialize($data, $map) {

   257   if ($data = unserialize($data)) {

   258     foreach ($data as $k => $v) {

   259       if (is_int($v)) {

   260         $data[$k] = isset($map[$v]) ? $map[$v] : '';

   261       }

   262     }

   263     return $data;

   264   }

   265   else {

   266     return array();

   267   }

   268 }

   269 

   270 

   271 

   272 /**

   273  * Replaces the statically cached item for a given path.

   274  *

   275  * @param $path

   276  *   The path.

   277  * @param $router_item

   278  *   The router item. Usually you take a router entry from menu_get_item and

   279  *   set it back either modified or to a different path. This lets you modify the

   280  *   navigation block, the page title, the breadcrumb and the page help in one

   281  *   call.

   282  */

   283 function menu_set_item($path, $router_item) {

   284   menu_get_item($path, $router_item);

   285 }

   286 

   287 /**

   288  * Get a router item.

   289  *

   290  * @param $path

   291  *   The path, for example node/5. The function will find the corresponding

   292  *   node/% item and return that.

   293  * @param $router_item

   294  *   Internal use only.

   295  * @return

   296  *   The router item, an associate array corresponding to one row in the

   297  *   menu_router table. The value of key map holds the loaded objects. The

   298  *   value of key access is TRUE if the current user can access this page.

   299  *   The values for key title, page_arguments, access_arguments will be

   300  *   filled in based on the database values and the objects loaded.

   301  */

   302 function menu_get_item($path = NULL, $router_item = NULL) {

   303   static $router_items;

   304   if (!isset($path)) {

   305     $path = $_GET['q'];

   306   }

   307   if (isset($router_item)) {

   308     $router_items[$path] = $router_item;

   309   }

   310   if (!isset($router_items[$path])) {

   311     $original_map = arg(NULL, $path);

   312     $parts = array_slice($original_map, 0, MENU_MAX_PARTS);

   313     list($ancestors, $placeholders) = menu_get_ancestors($parts);

   314 

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

   316       $map = _menu_translate($router_item, $original_map);

   317       if ($map === FALSE) {

   318         $router_items[$path] = FALSE;

   319         return FALSE;

   320       }

   321       if ($router_item['access']) {

   322         $router_item['map'] = $map;

   323         $router_item['page_arguments'] = array_merge(menu_unserialize($router_item['page_arguments'], $map), array_slice($map, $router_item['number_parts']));

   324       }

   325     }

   326     $router_items[$path] = $router_item;

   327   }

   328   return $router_items[$path];

   329 }

   330 

   331 /**

   332  * Execute the page callback associated with the current path

   333  */

   334 function menu_execute_active_handler($path = NULL) {

   335   if (_menu_site_is_offline()) {

   336     return MENU_SITE_OFFLINE;

   337   }

   338   // Rebuild if we know it's needed, or if the menu masks are missing which

   339   // occurs rarely, likely due to a race condition of multiple rebuilds.

   340   if (variable_get('menu_rebuild_needed', FALSE) || !variable_get('menu_masks', array())) {

   341     menu_rebuild();

   342   }

   343   if ($router_item = menu_get_item($path)) {

   344     if ($router_item['access']) {

   345       if ($router_item['file']) {

   346         require_once($router_item['file']);

   347       }

   348       return call_user_func_array($router_item['page_callback'], $router_item['page_arguments']);

   349     }

   350     else {

   351       return MENU_ACCESS_DENIED;

   352     }

   353   }

   354   return MENU_NOT_FOUND;

   355 }

   356 

   357 /**

   358  * Loads objects into the map as defined in the $item['load_functions'].

   359  *

   360  * @param $item

   361  *   A menu router or menu link item

   362  * @param $map

   363  *   An array of path arguments (ex: array('node', '5'))

   364  * @return

   365  *   Returns TRUE for success, FALSE if an object cannot be loaded.

   366  *   Names of object loading functions are placed in $item['load_functions'].

   367  *   Loaded objects are placed in $map[]; keys are the same as keys in the

   368  *   $item['load_functions'] array.

   369  *   $item['access'] is set to FALSE if an object cannot be loaded.

   370  */

   371 function _menu_load_objects(&$item, &$map) {

   372   if ($load_functions = $item['load_functions']) {

   373     // If someone calls this function twice, then unserialize will fail.

   374     if ($load_functions_unserialized = unserialize($load_functions)) {

   375       $load_functions = $load_functions_unserialized;

   376     }

   377     $path_map = $map;

   378     foreach ($load_functions as $index => $function) {

   379       if ($function) {

   380         $value = isset($path_map[$index]) ? $path_map[$index] : '';

   381         if (is_array($function)) {

   382           // Set up arguments for the load function. These were pulled from

   383           // 'load arguments' in the hook_menu() entry, but they need

   384           // some processing. In this case the $function is the key to the

   385           // load_function array, and the value is the list of arguments.

   386           list($function, $args) = each($function);

   387           $load_functions[$index] = $function;

   388 

   389           // Some arguments are placeholders for dynamic items to process.

   390           foreach ($args as $i => $arg) {

   391             if ($arg === '%index') {

   392               // Pass on argument index to the load function, so multiple

   393               // occurances of the same placeholder can be identified.

   394               $args[$i] = $index;

   395             }

   396             if ($arg === '%map') {

   397               // Pass on menu map by reference. The accepting function must

   398               // also declare this as a reference if it wants to modify

   399               // the map.

   400               $args[$i] = &$map;

   401             }

   402             if (is_int($arg)) {

   403               $args[$i] = isset($path_map[$arg]) ? $path_map[$arg] : '';

   404             }

   405           }

   406           array_unshift($args, $value);

   407           $return = call_user_func_array($function, $args);

   408         }

   409         else {

   410           $return = $function($value);

   411         }

   412         // If callback returned an error or there is no callback, trigger 404.

   413         if ($return === FALSE) {

   414           $item['access'] = FALSE;

   415           $map = FALSE;

   416           return FALSE;

   417         }

   418         $map[$index] = $return;

   419       }

   420     }

   421     $item['load_functions'] = $load_functions;

   422   }

   423   return TRUE;

   424 }

   425 

   426 /**

   427  * Check access to a menu item using the access callback

   428  *

   429  * @param $item

   430  *   A menu router or menu link item

   431  * @param $map

   432  *   An array of path arguments (ex: array('node', '5'))

   433  * @return

   434  *   $item['access'] becomes TRUE if the item is accessible, FALSE otherwise.

   435  */

   436 function _menu_check_access(&$item, $map) {

   437   // Determine access callback, which will decide whether or not the current

   438   // user has access to this path.

   439   $callback = empty($item['access_callback']) ? 0 : trim($item['access_callback']);

   440   // Check for a TRUE or FALSE value.

   441   if (is_numeric($callback)) {

   442     $item['access'] = (bool)$callback;

   443   }

   444   else {

   445     $arguments = menu_unserialize($item['access_arguments'], $map);

   446     // As call_user_func_array is quite slow and user_access is a very common

   447     // callback, it is worth making a special case for it.

   448     if ($callback == 'user_access') {

   449       $item['access'] = (count($arguments) == 1) ? user_access($arguments[0]) : user_access($arguments[0], $arguments[1]);

   450     }

   451     else {

   452       $item['access'] = call_user_func_array($callback, $arguments);

   453     }

   454   }

   455 }

   456 

   457 /**

   458  * Localize the router item title using t() or another callback.

   459  *

   460  * Translate the title and description to allow storage of English title

   461  * strings in the database, yet display of them in the language required

   462  * by the current user.

   463  *

   464  * @param $item

   465  *   A menu router item or a menu link item.

   466  * @param $map

   467  *   The path as an array with objects already replaced. E.g., for path

   468  *   node/123 $map would be array('node', $node) where $node is the node

   469  *   object for node 123.

   470  * @param $link_translate

   471  *   TRUE if we are translating a menu link item; FALSE if we are

   472  *   translating a menu router item.

   473  * @return

   474  *   No return value.

   475  *   $item['title'] is localized according to $item['title_callback'].

   476  *   If an item's callback is check_plain(), $item['options']['html'] becomes

   477  *   TRUE.

   478  *   $item['description'] is translated using t().

   479  *   When doing link translation and the $item['options']['attributes']['title']

   480  *   (link title attribute) matches the description, it is translated as well.

   481  */

   482 function _menu_item_localize(&$item, $map, $link_translate = FALSE) {

   483   $callback = $item['title_callback'];

   484   $item['localized_options'] = $item['options'];

   485   // If we are translating the title of a menu link, and its title is the same

   486   // as the corresponding router item, then we can use the title information

   487   // from the router. If it's customized, then we need to use the link title

   488   // itself; can't localize.

   489   // If we are translating a router item (tabs, page, breadcrumb), then we

   490   // can always use the information from the router item.

   491   if (!$link_translate || ($item['title'] == $item['link_title'])) {

   492     // t() is a special case. Since it is used very close to all the time,

   493     // we handle it directly instead of using indirect, slower methods.

   494     if ($callback == 't') {

   495       if (empty($item['title_arguments'])) {

   496         $item['title'] = t($item['title']);

   497       }

   498       else {

   499         $item['title'] = t($item['title'], menu_unserialize($item['title_arguments'], $map));

   500       }

   501     }

   502     elseif ($callback) {

   503       if (empty($item['title_arguments'])) {

   504         $item['title'] = $callback($item['title']);

   505       }

   506       else {

   507         $item['title'] = call_user_func_array($callback, menu_unserialize($item['title_arguments'], $map));

   508       }

   509       // Avoid calling check_plain again on l() function.

   510       if ($callback == 'check_plain') {

   511         $item['localized_options']['html'] = TRUE;

   512       }

   513     }

   514   }

   515   elseif ($link_translate) {

   516     $item['title'] = $item['link_title'];

   517   }

   518 

   519   // Translate description, see the motivation above.

   520   if (!empty($item['description'])) {

   521     $original_description = $item['description'];

   522     $item['description'] = t($item['description']);

   523     if ($link_translate && isset($item['options']['attributes']['title']) && $item['options']['attributes']['title'] == $original_description) {

   524       $item['localized_options']['attributes']['title'] = $item['description'];

   525     }

   526   }

   527 }

   528 

   529 /**

   530  * Handles dynamic path translation and menu access control.

   531  *

   532  * When a user arrives on a page such as node/5, this function determines

   533  * what "5" corresponds to, by inspecting the page's menu path definition,

   534  * node/%node. This will call node_load(5) to load the corresponding node

   535  * object.

   536  *

   537  * It also works in reverse, to allow the display of tabs and menu items which

   538  * contain these dynamic arguments, translating node/%node to node/5.

   539  *

   540  * Translation of menu item titles and descriptions are done here to

   541  * allow for storage of English strings in the database, and translation

   542  * to the language required to generate the current page

   543  *

   544  * @param $router_item

   545  *   A menu router item

   546  * @param $map

   547  *   An array of path arguments (ex: array('node', '5'))

   548  * @param $to_arg

   549  *   Execute $item['to_arg_functions'] or not. Use only if you want to render a

   550  *   path from the menu table, for example tabs.

   551  * @return

   552  *   Returns the map with objects loaded as defined in the

   553  *   $item['load_functions. $item['access'] becomes TRUE if the item is

   554  *   accessible, FALSE otherwise. $item['href'] is set according to the map.

   555  *   If an error occurs during calling the load_functions (like trying to load

   556  *   a non existing node) then this function return FALSE.

   557  */

   558 function _menu_translate(&$router_item, $map, $to_arg = FALSE) {

   559   if ($to_arg) {

   560     // Fill in missing path elements, such as the current uid.

   561     _menu_link_map_translate($map, $router_item['to_arg_functions']);

   562   }

   563   // The $path_map saves the pieces of the path as strings, while elements in

   564   // $map may be replaced with loaded objects.

   565   $path_map = $map;

   566   if (!_menu_load_objects($router_item, $map)) {

   567     // An error occurred loading an object.

   568     $router_item['access'] = FALSE;

   569     return FALSE;

   570   }

   571 

   572   // Generate the link path for the page request or local tasks.

   573   $link_map = explode('/', $router_item['path']);

   574   for ($i = 0; $i < $router_item['number_parts']; $i++) {

   575     if ($link_map[$i] == '%') {

   576       $link_map[$i] = $path_map[$i];

   577     }

   578   }

   579   $router_item['href'] = implode('/', $link_map);

   580   $router_item['options'] = array();

   581   _menu_check_access($router_item, $map);

   582   

   583   // For performance, don't localize an item the user can't access.

   584   if ($router_item['access']) {

   585     _menu_item_localize($router_item, $map);

   586   }

   587 

   588   return $map;

   589 }

   590 

   591 /**

   592  * This function translates the path elements in the map using any to_arg

   593  * helper function. These functions take an argument and return an object.

   594  * See http://drupal.org/node/109153 for more information.

   595  *

   596  * @param map

   597  *   An array of path arguments (ex: array('node', '5'))

   598  * @param $to_arg_functions

   599  *   An array of helper function (ex: array(2 => 'menu_tail_to_arg'))

   600  */

   601 function _menu_link_map_translate(&$map, $to_arg_functions) {

   602   if ($to_arg_functions) {

   603     $to_arg_functions = unserialize($to_arg_functions);

   604     foreach ($to_arg_functions as $index => $function) {

   605       // Translate place-holders into real values.

   606       $arg = $function(!empty($map[$index]) ? $map[$index] : '', $map, $index);

   607       if (!empty($map[$index]) || isset($arg)) {

   608         $map[$index] = $arg;

   609       }

   610       else {

   611         unset($map[$index]);

   612       }

   613     }

   614   }

   615 }

   616 

   617 function menu_tail_to_arg($arg, $map, $index) {

   618   return implode('/', array_slice($map, $index));

   619 }

   620 

   621 /**

   622  * This function is similar to _menu_translate() but does link-specific

   623  * preparation such as always calling to_arg functions.

   624  *

   625  * @param $item

   626  *   A menu link

   627  * @return

   628  *   Returns the map of path arguments with objects loaded as defined in the

   629  *   $item['load_functions']:

   630  *   - $item['access'] becomes TRUE if the item is accessible, FALSE otherwise.

   631  *   - $item['href'] is generated from link_path, possibly by to_arg functions.

   632  *   - $item['title'] is generated from link_title, and may be localized.

   633  *   - $item['options'] is unserialized; it is also changed within the call

   634  *     here to $item['localized_options'] by _menu_item_localize().

   635  */

   636 function _menu_link_translate(&$item) {

   637   $item['options'] = unserialize($item['options']);

   638   if ($item['external']) {

   639     $item['access'] = 1;

   640     $map = array();

   641     $item['href'] = $item['link_path'];

   642     $item['title'] = $item['link_title'];

   643     $item['localized_options'] = $item['options'];

   644   }

   645   else {

   646     $map = explode('/', $item['link_path']);

   647     _menu_link_map_translate($map, $item['to_arg_functions']);

   648     $item['href'] = implode('/', $map);

   649 

   650     // Note - skip callbacks without real values for their arguments.

   651     if (strpos($item['href'], '%') !== FALSE) {

   652       $item['access'] = FALSE;

   653       return FALSE;

   654     }

   655     // menu_tree_check_access() may set this ahead of time for links to nodes.

   656     if (!isset($item['access'])) {

   657       if (!_menu_load_objects($item, $map)) {

   658         // An error occurred loading an object.

   659         $item['access'] = FALSE;

   660         return FALSE;

   661       }

   662       _menu_check_access($item, $map);

   663     }

   664     // For performance, don't localize a link the user can't access.

   665     if ($item['access']) {

   666       _menu_item_localize($item, $map, TRUE);

   667     }

   668   }

   669 

   670   // Allow other customizations - e.g. adding a page-specific query string to the

   671   // options array. For performance reasons we only invoke this hook if the link

   672   // has the 'alter' flag set in the options array.

   673   if (!empty($item['options']['alter'])) {

   674     drupal_alter('translated_menu_link', $item, $map);

   675   }

   676 

   677   return $map;

   678 }

   679 

   680 /**

   681  * Get a loaded object from a router item.

   682  *

   683  * menu_get_object() will provide you the current node on paths like node/5,

   684  * node/5/revisions/48 etc. menu_get_object('user') will give you the user

   685  * account on user/5 etc. Note - this function should never be called within a

   686  * _to_arg function (like user_current_to_arg()) since this may result in an

   687  * infinite recursion.

   688  *

   689  * @param $type

   690  *   Type of the object. These appear in hook_menu definitons as %type. Core

   691  *   provides aggregator_feed, aggregator_category, contact, filter_format,

   692  *   forum_term, menu, menu_link, node, taxonomy_vocabulary, user. See the

   693  *   relevant {$type}_load function for more on each. Defaults to node.

   694  * @param $position

   695  *   The expected position for $type object. For node/%node this is 1, for

   696  *   comment/reply/%node this is 2. Defaults to 1.

   697  * @param $path

   698  *   See menu_get_item() for more on this. Defaults to the current path.

   699  */

   700 function menu_get_object($type = 'node', $position = 1, $path = NULL) {

   701   $router_item = menu_get_item($path);

   702   if (isset($router_item['load_functions'][$position]) && !empty($router_item['map'][$position]) && $router_item['load_functions'][$position] == $type .'_load') {

   703     return $router_item['map'][$position];

   704   }

   705 }

   706 

   707 /**

   708  * Render a menu tree based on the current path.

   709  *

   710  * The tree is expanded based on the current path and dynamic paths are also

   711  * changed according to the defined to_arg functions (for example the 'My account'

   712  * link is changed from user/% to a link with the current user's uid).

   713  *

   714  * @param $menu_name

   715  *   The name of the menu.

   716  * @return

   717  *   The rendered HTML of that menu on the current page.

   718  */

   719 function menu_tree($menu_name = 'navigation') {

   720   static $menu_output = array();

   721 

   722   if (!isset($menu_output[$menu_name])) {

   723     $tree = menu_tree_page_data($menu_name);

   724     $menu_output[$menu_name] = menu_tree_output($tree);

   725   }

   726   return $menu_output[$menu_name];

   727 }

   728 

   729 /**

   730  * Returns a rendered menu tree.

   731  *

   732  * @param $tree

   733  *   A data structure representing the tree as returned from menu_tree_data.

   734  * @return

   735  *   The rendered HTML of that data structure.

   736  */

   737 function menu_tree_output($tree) {

   738   $output = '';

   739   $items = array();

   740 

   741   // Pull out just the menu items we are going to render so that we

   742   // get an accurate count for the first/last classes.

   743   foreach ($tree as $data) {

   744     if (!$data['link']['hidden']) {

   745       $items[] = $data;

   746     }

   747   }

   748 

   749   $num_items = count($items);

   750   foreach ($items as $i => $data) {

   751     $extra_class = NULL;

   752     if ($i == 0) {

   753       $extra_class = 'first';

   754     }

   755     if ($i == $num_items - 1) {

   756       $extra_class = 'last';

   757     }

   758     $link = theme('menu_item_link', $data['link']);

   759     if ($data['below']) {

   760       $output .= theme('menu_item', $link, $data['link']['has_children'], menu_tree_output($data['below']), $data['link']['in_active_trail'], $extra_class);

   761     }

   762     else {

   763       $output .= theme('menu_item', $link, $data['link']['has_children'], '', $data['link']['in_active_trail'], $extra_class);

   764     }

   765   }

   766   return $output ? theme('menu_tree', $output) : '';

   767 }

   768 

   769 /**

   770  * Get the data structure representing a named menu tree.

   771  *

   772  * Since this can be the full tree including hidden items, the data returned

   773  * may be used for generating an an admin interface or a select.

   774  *

   775  * @param $menu_name

   776  *   The named menu links to return

   777  * @param $item

   778  *   A fully loaded menu link, or NULL.  If a link is supplied, only the

   779  *   path to root will be included in the returned tree- as if this link

   780  *   represented the current page in a visible menu.

   781  * @return

   782  *   An tree of menu links in an array, in the order they should be rendered.

   783  */

   784 function menu_tree_all_data($menu_name = 'navigation', $item = NULL) {

   785   static $tree = array();

   786 

   787   // Use $mlid as a flag for whether the data being loaded is for the whole tree.

   788   $mlid = isset($item['mlid']) ? $item['mlid'] : 0;

   789   // Generate a cache ID (cid) specific for this $menu_name and $item.

   790   $cid = 'links:'. $menu_name .':all-cid:'. $mlid;

   791 

   792   if (!isset($tree[$cid])) {

   793     // If the static variable doesn't have the data, check {cache_menu}.

   794     $cache = cache_get($cid, 'cache_menu');

   795     if ($cache && isset($cache->data)) {

   796       // If the cache entry exists, it will just be the cid for the actual data.

   797       // This avoids duplication of large amounts of data.

   798       $cache = cache_get($cache->data, 'cache_menu');

   799       if ($cache && isset($cache->data)) {

   800         $data = $cache->data;

   801       }

   802     }

   803     // If the tree data was not in the cache, $data will be NULL.

   804     if (!isset($data)) {

   805       // Build and run the query, and build the tree.

   806       if ($mlid) {

   807         // The tree is for a single item, so we need to match the values in its

   808         // p columns and 0 (the top level) with the plid values of other links.

   809         $args = array(0);

   810         for ($i = 1; $i < MENU_MAX_DEPTH; $i++) {

   811           $args[] = $item["p$i"];

   812         }

   813         $args = array_unique($args);

   814         $placeholders = implode(', ', array_fill(0, count($args), '%d'));

   815         $where = ' AND ml.plid IN ('. $placeholders .')';

   816         $parents = $args;

   817         $parents[] = $item['mlid'];

   818       }

   819       else {

   820         // Get all links in this menu.

   821         $where = '';

   822         $args = array();

   823         $parents = array();

   824       }

   825       array_unshift($args, $menu_name);

   826       // Select the links from the table, and recursively build the tree.  We

   827       // LEFT JOIN since there is no match in {menu_router} for an external

   828       // link.

   829       $data['tree'] = menu_tree_data(db_query("

   830         SELECT m.load_functions, m.to_arg_functions, m.access_callback, m.access_arguments, m.page_callback, m.page_arguments, m.title, m.title_callback, m.title_arguments, m.type, m.description, ml.*

   831         FROM {menu_links} ml LEFT JOIN {menu_router} m ON m.path = ml.router_path

   832         WHERE ml.menu_name = '%s'". $where ."

   833         ORDER BY p1 ASC, p2 ASC, p3 ASC, p4 ASC, p5 ASC, p6 ASC, p7 ASC, p8 ASC, p9 ASC", $args), $parents);

   834       $data['node_links'] = array();

   835       menu_tree_collect_node_links($data['tree'], $data['node_links']);

   836       // Cache the data, if it is not already in the cache.

   837       $tree_cid = _menu_tree_cid($menu_name, $data);

   838       if (!cache_get($tree_cid, 'cache_menu')) {

   839         cache_set($tree_cid, $data, 'cache_menu');

   840       }

   841       // Cache the cid of the (shared) data using the menu and item-specific cid.

   842       cache_set($cid, $tree_cid, 'cache_menu');

   843     }

   844     // Check access for the current user to each item in the tree.

   845     menu_tree_check_access($data['tree'], $data['node_links']);

   846     $tree[$cid] = $data['tree'];

   847   }

   848 

   849   return $tree[$cid];

   850 }

   851 

   852 /**

   853  * Get the data structure representing a named menu tree, based on the current page.

   854  *

   855  * The tree order is maintained by storing each parent in an individual

   856  * field, see http://drupal.org/node/141866 for more.

   857  *

   858  * @param $menu_name

   859  *   The named menu links to return

   860  * @return

   861  *   An array of menu links, in the order they should be rendered. The array

   862  *   is a list of associative arrays -- these have two keys, link and below.

   863  *   link is a menu item, ready for theming as a link. Below represents the

   864  *   submenu below the link if there is one, and it is a subtree that has the

   865  *   same structure described for the top-level array.

   866  */

   867 function menu_tree_page_data($menu_name = 'navigation') {

   868   static $tree = array();

   869 

   870   // Load the menu item corresponding to the current page.

   871   if ($item = menu_get_item()) {

   872     // Generate a cache ID (cid) specific for this page.

   873     $cid = 'links:'. $menu_name .':page-cid:'. $item['href'] .':'. (int)$item['access'];

   874 

   875     if (!isset($tree[$cid])) {

   876       // If the static variable doesn't have the data, check {cache_menu}.

   877       $cache = cache_get($cid, 'cache_menu');

   878       if ($cache && isset($cache->data)) {

   879         // If the cache entry exists, it will just be the cid for the actual data.

   880         // This avoids duplication of large amounts of data.

   881         $cache = cache_get($cache->data, 'cache_menu');

   882         if ($cache && isset($cache->data)) {

   883           $data = $cache->data;

   884         }

   885       }

   886       // If the tree data was not in the cache, $data will be NULL.

   887       if (!isset($data)) {

   888         // Build and run the query, and build the tree.

   889         if ($item['access']) {

   890           // Check whether a menu link exists that corresponds to the current path.

   891           $args = array($menu_name, $item['href']);

   892           $placeholders = "'%s'";

   893           if (drupal_is_front_page()) {

   894             $args[] = '<front>';

   895             $placeholders .= ", '%s'";

   896           }

   897           $parents = db_fetch_array(db_query("SELECT p1, p2, p3, p4, p5, p6, p7, p8 FROM {menu_links} WHERE menu_name = '%s' AND link_path IN (". $placeholders .")", $args));

   898 

   899           if (empty($parents)) {

   900             // If no link exists, we may be on a local task that's not in the links.

   901             // TODO: Handle the case like a local task on a specific node in the menu.

   902             $parents = db_fetch_array(db_query("SELECT p1, p2, p3, p4, p5, p6, p7, p8 FROM {menu_links} WHERE menu_name = '%s' AND link_path = '%s'", $menu_name, $item['tab_root']));

   903           }

   904           // We always want all the top-level links with plid == 0.

   905           $parents[] = '0';

   906 

   907           // Use array_values() so that the indices are numeric for array_merge().

   908           $args = $parents = array_unique(array_values($parents));

   909           $placeholders = implode(', ', array_fill(0, count($args), '%d'));

   910           $expanded = variable_get('menu_expanded', array());

   911           // Check whether the current menu has any links set to be expanded.

   912           if (in_array($menu_name, $expanded)) {

   913             // Collect all the links set to be expanded, and then add all of

   914             // their children to the list as well.

   915             do {

   916               $result = db_query("SELECT mlid FROM {menu_links} WHERE menu_name = '%s' AND expanded = 1 AND has_children = 1 AND plid IN (". $placeholders .') AND mlid NOT IN ('. $placeholders .')', array_merge(array($menu_name), $args, $args));

   917               $num_rows = FALSE;

   918               while ($item = db_fetch_array($result)) {

   919                 $args[] = $item['mlid'];

   920                 $num_rows = TRUE;

   921               }

   922               $placeholders = implode(', ', array_fill(0, count($args), '%d'));

   923             } while ($num_rows);

   924           }

   925           array_unshift($args, $menu_name);

   926         }

   927         else {

   928           // Show only the top-level menu items when access is denied.

   929           $args = array($menu_name, '0');

   930           $placeholders = '%d';

   931           $parents = array();

   932         }

   933         // Select the links from the table, and recursively build the tree. We

   934         // LEFT JOIN since there is no match in {menu_router} for an external

   935         // link.

   936         $data['tree'] = menu_tree_data(db_query("

   937           SELECT m.load_functions, m.to_arg_functions, m.access_callback, m.access_arguments, m.page_callback, m.page_arguments, m.title, m.title_callback, m.title_arguments, m.type, m.description, ml.*

   938           FROM {menu_links} ml LEFT JOIN {menu_router} m ON m.path = ml.router_path

   939           WHERE ml.menu_name = '%s' AND ml.plid IN (". $placeholders .")

   940           ORDER BY p1 ASC, p2 ASC, p3 ASC, p4 ASC, p5 ASC, p6 ASC, p7 ASC, p8 ASC, p9 ASC", $args), $parents);

   941         $data['node_links'] = array();

   942         menu_tree_collect_node_links($data['tree'], $data['node_links']);

   943         // Cache the data, if it is not already in the cache.

   944         $tree_cid = _menu_tree_cid($menu_name, $data);

   945         if (!cache_get($tree_cid, 'cache_menu')) {

   946           cache_set($tree_cid, $data, 'cache_menu');

   947         }

   948         // Cache the cid of the (shared) data using the page-specific cid.

   949         cache_set($cid, $tree_cid, 'cache_menu');

   950       }

   951       // Check access for the current user to each item in the tree.

   952       menu_tree_check_access($data['tree'], $data['node_links']);

   953       $tree[$cid] = $data['tree'];

   954     }

   955     return $tree[$cid];

   956   }

   957 

   958   return array();

   959 }

   960 

   961 /**

   962  * Helper function - compute the real cache ID for menu tree data.

   963  */

   964 function _menu_tree_cid($menu_name, $data) {

   965   return 'links:'. $menu_name .':tree-data:'. md5(serialize($data));

   966 }

   967 

   968 /**

   969  * Recursive helper function - collect node links.

   970  *

   971  * @param $tree

   972  *   The menu tree you wish to collect node links from.

   973  * @param $node_links

   974  *   An array in which to store the collected node links.

   975  */

   976 function menu_tree_collect_node_links(&$tree, &$node_links) {

   977   foreach ($tree as $key => $v) {

   978     if ($tree[$key]['link']['router_path'] == 'node/%') {

   979       $nid = substr($tree[$key]['link']['link_path'], 5);

   980       if (is_numeric($nid)) {

   981         $node_links[$nid][$tree[$key]['link']['mlid']] = &$tree[$key]['link'];

   982         $tree[$key]['link']['access'] = FALSE;

   983       }

   984     }

   985     if ($tree[$key]['below']) {

   986       menu_tree_collect_node_links($tree[$key]['below'], $node_links);

   987     }

   988   }

   989 }

   990 

   991 /**

   992  * Check access and perform other dynamic operations for each link in the tree.

   993  *

   994  * @param $tree

   995  *   The menu tree you wish to operate on.

   996  * @param $node_links

   997  *   A collection of node link references generated from $tree by

   998  *   menu_tree_collect_node_links().

   999  */

  1000 function menu_tree_check_access(&$tree, $node_links = array()) {

  1001 

  1002   if ($node_links) {

  1003     // Use db_rewrite_sql to evaluate view access without loading each full node.

  1004     $nids = array_keys($node_links);

  1005     $placeholders = '%d'. str_repeat(', %d', count($nids) - 1);

  1006     $result = db_query(db_rewrite_sql("SELECT n.nid FROM {node} n WHERE n.status = 1 AND n.nid IN (". $placeholders .")"), $nids);

  1007     while ($node = db_fetch_array($result)) {

  1008       $nid = $node['nid'];

  1009       foreach ($node_links[$nid] as $mlid => $link) {

  1010         $node_links[$nid][$mlid]['access'] = TRUE;

  1011       }

  1012     }

  1013   }

  1014   _menu_tree_check_access($tree);

  1015   return;

  1016 }

  1017 

  1018 /**

  1019  * Recursive helper function for menu_tree_check_access()

  1020  */

  1021 function _menu_tree_check_access(&$tree) {

  1022   $new_tree = array();

  1023   foreach ($tree as $key => $v) {

  1024     $item = &$tree[$key]['link'];

  1025     _menu_link_translate($item);

  1026     if ($item['access']) {

  1027       if ($tree[$key]['below']) {

  1028         _menu_tree_check_access($tree[$key]['below']);

  1029       }

  1030       // The weights are made a uniform 5 digits by adding 50000 as an offset.

  1031       // After _menu_link_translate(), $item['title'] has the localized link title.

  1032       // Adding the mlid to the end of the index insures that it is unique.

  1033       $new_tree[(50000 + $item['weight']) .' '. $item['title'] .' '. $item['mlid']] = $tree[$key];

  1034     }

  1035   }

  1036   // Sort siblings in the tree based on the weights and localized titles.

  1037   ksort($new_tree);

  1038   $tree = $new_tree;

  1039 }

  1040 

  1041 /**

  1042  * Build the data representing a menu tree.

  1043  *

  1044  * @param $result

  1045  *   The database result.

  1046  * @param $parents

  1047  *   An array of the plid values that represent the path from the current page

  1048  *   to the root of the menu tree.

  1049  * @param $depth

  1050  *   The depth of the current menu tree.

  1051  * @return

  1052  *   See menu_tree_page_data for a description of the data structure.

  1053  */

  1054 function menu_tree_data($result = NULL, $parents = array(), $depth = 1) {

  1055   list(, $tree) = _menu_tree_data($result, $parents, $depth);

  1056   return $tree;

  1057 }

  1058 

  1059 /**

  1060  * Recursive helper function to build the data representing a menu tree.

  1061  *

  1062  * The function is a bit complex because the rendering of an item depends on

  1063  * the next menu item. So we are always rendering the element previously

  1064  * processed not the current one.

  1065  */

  1066 function _menu_tree_data($result, $parents, $depth, $previous_element = '') {

  1067   $remnant = NULL;

  1068   $tree = array();

  1069   while ($item = db_fetch_array($result)) {

  1070     // We need to determine if we're on the path to root so we can later build

  1071     // the correct active trail and breadcrumb.

  1072     $item['in_active_trail'] = in_array($item['mlid'], $parents);

  1073     // The current item is the first in a new submenu.

  1074     if ($item['depth'] > $depth) {

  1075       // _menu_tree returns an item and the menu tree structure.

  1076       list($item, $below) = _menu_tree_data($result, $parents, $item['depth'], $item);

  1077       if ($previous_element) {

  1078         $tree[$previous_element['mlid']] = array(

  1079           'link' => $previous_element,

  1080           'below' => $below,

  1081         );

  1082       }

  1083       else {

  1084         $tree = $below;

  1085       }

  1086       // We need to fall back one level.

  1087       if (!isset($item) || $item['depth'] < $depth) {

  1088         return array($item, $tree);

  1089       }

  1090       // This will be the link to be output in the next iteration.

  1091       $previous_element = $item;

  1092     }

  1093     // We are at the same depth, so we use the previous element.

  1094     elseif ($item['depth'] == $depth) {

  1095       if ($previous_element) {

  1096         // Only the first time.

  1097         $tree[$previous_element['mlid']] = array(

  1098           'link' => $previous_element,

  1099           'below' => FALSE,

  1100         );

  1101       }

  1102       // This will be the link to be output in the next iteration.

  1103       $previous_element = $item;

  1104     }

  1105     // The submenu ended with the previous item, so pass back the current item.

  1106     else {

  1107       $remnant = $item;

  1108       break;

  1109     }

  1110   }

  1111   if ($previous_element) {

  1112     // We have one more link dangling.

  1113     $tree[$previous_element['mlid']] = array(

  1114       'link' => $previous_element,

  1115       'below' => FALSE,

  1116     );

  1117   }

  1118   return array($remnant, $tree);

  1119 }

  1120 

  1121 /**

  1122  * Generate the HTML output for a single menu link.

  1123  *

  1124  * @ingroup themeable

  1125  */

  1126 function theme_menu_item_link($link) {

  1127   if (empty($link['localized_options'])) {

  1128     $link['localized_options'] = array();

  1129   }

  1130 

  1131   return l($link['title'], $link['href'], $link['localized_options']);

  1132 }

  1133 

  1134 /**

  1135  * Generate the HTML output for a menu tree