page_example_menu

• Drupal 4.6
• Drupal 4.7
• Drupal 5
• Drupal 6
• Drupal 7

• View documentation
• List references

Definition

page_example_menu($may_cache)
developer/examples/page_example.module, line 68

Description

Implementation of hook_menu().

You must implement hook_menu() to emit items to place in the main menu. This is a required step for modules wishing to display their own pages, because the process of creating the links also tells Drupal what callback function to use for a given URL. The menu items returned here provide this information to the menu system.

With the below menu definitions, URLs will be interpreted as follows:

If the user accesses http://example.com/?q=foo, then the menu system will first look for a menu item with that path. In this case it will find a match, and execute page_example_foo().

If the user accesses http://example.com/?q=bar, no match will be found, and a 404 page will be displayed.

If the user accesses http://example.com/?q=bar/baz, the menu system will find a match and execute page_example_baz().

If the user accesses http://example.com/?q=bar/baz/1/2, the menu system will first look for bar/baz/1/2. Not finding a match, it will look for bar/baz/1. Again not finding a match, it will look for bar/baz. This time it finds a match, and so will execute page_example_baz(1,2). Note the parameters being passed; this is a very useful technique.

If the user accesses http://example.com/?q=bar/baz/52/97, the menu system finds a match, but since its callback is absent, it proceeds as above and ends up calling page_example_baz(52,97) nonetheless.

Code

<?php
function page_example_menu($may_cache) {
  $items = array();

  // The $may_cache parameter is used to divide menu items into two parts. Those
  // returned when $may_cache is true must be consistently applicable for the
  // current user at all times; the others may change or be defined at only
  // certain paths. Most modules will have excusively cacheable menu items.
  if ($may_cache) {
    // This is the minimum information you can provide for a menu item.
    $items[] = array('path' => 'foo', 'title' => t('foo'),
      'callback' => 'page_example_foo',
      'access' => user_access('access foo'));

    // By using the MENU_CALLBACK type, we can register the callback for this
    // path but not have the item show up in the menu; the admin is not allowed
    // to enable the item in the menu, either.
    $items[] = array('path' => 'bar/baz', 'title' => t('baz'),
      'callback' => 'page_example_baz',
      'access' => user_access('access baz'),
      'type' => MENU_CALLBACK);

    // Here is a menu item that doesn't register a callback. By default, the
    // attributes are inherited from the parent menu item. In this case, the
    // permissions of the parent suffice but we to override the title if
    // they enter some "magic" parameters. Note: if you remove the 'type'
    // attribute, the item will appear in the menu.
    $items[] = array('path' => 'bar/baz/52/97',
      'title' => t('the magic numbers'),
      'type' => MENU_CALLBACK);
  }

  return $items;
}
?>