Menu system

The Drupal menu system has been extended to drive all pages, not just administrative pages. This is continuing the work done for Drupal 4.3, which integrated the administrative menu with the user menu. We now have consistency between administrative and "normal" pages; when you learn to create one, you know how to create the other.

The flow of page generation now proceeds as follows:

1. The _link hook in all modules is called, so that modules can use menu() to add items to the menu. For example, a module could define:
   
   <?php
function example_link($type) {
  if ($type == "system") {
    menu("example", t("example"), "example_page");
    menu("example/foo", t("foo"), "example_foo");
  }
}
?>
2. The menu system examines the current URL, and finds the "best fit" for the URL in the menu. For example, if the current URL is example/foo/bar/12, the above menu() calls would cause example_foo("bar", 12) to get invoked.
3. The callback may set the title or breadcrumb trail if the defaults are not satisfactory (more on this later).
4. The callback is responsible for printing the requested page. This will usually involve preparing the content, and then printing the return value of theme("page"). For example:
   
   <?php
function example_foo($theString, $theNumber) {
  $output = $theString. " - " .$theNumber;
  print theme("page", $output);
}
?>

The following points should be considered when upgrading modules to use the new menu system:

• The _page hook is obsolete. Pages will not be shown unless they are declared with a menu() call as discussed above. To convert former _page hooks to the new system as simply as possible, just declare that function as a "catchall" callback:
  
  <?php
  menu("example", t("example"), "example_page", 0, MENU_HIDE);
?>
  
  The trailing MENU_HIDE argument in this call makes the menu item hidden, so the callback functions but the module does not clutter the user menu.
• Old administrative callbacks returned their content. In the new system, administrative and normal callbacks alike are responsible for printing the entire page.
• The title of the page is printed by the theme system, so page content does not need to be wrapped in a theme("box") to get a title printed. If the default title is not satisfactory, it can be changed by calling drupal_set_title($title) before theme("page") gets called, or by passing the title to theme("page") as a parameter.
• The breadcrumb trail is also printed by the theme. If the default one needs to be overridden (to present things like forum hierarchies), this can be done by calling drupal_set_breadcrumb($breadcrumb) before theme("page") gets called, or by passing the breadcrumb to theme("page") as a parameter. $breadcrumb should be a list of links beginning with "Home" and proceeding up to, but not including, the current page.