Anatomy of hook_menu

Last modified: September 17, 2009 - 19:13

hook_menu() is called rarely, such as when modules are enabled. If you edit a module’s hook_menu(), you must visit admin/build/modules for the changes to take effect.

<?php
  $items
['mypath/%object'] = array(
   
'title' => 'Page title',
   
'title arguments' => array(),
   
'title callback' => 't',
   
'description' => 'Your description goes here.',
   
'access callback' => 'object_check_access',
   
'access arguments' => array(1),
   
'page arguments' => array(1),
   
'page callback' => 'object_display',
   
'block callback' => '',
   
'menu_name' => NULL,
   
'tab_parent' => NULL,
   
'tab_root' => NULL,
   
'file' => 'name_of_file.inc',
   
'file path' => drupal_get_path('module', 'name_of_module_goes_here'),
   
'weight' => 0,
   
'type' => MENU_NORMAL_ITEM,
  );

function
object_load() {}
function
object_to_arg() {}
?>

Example:

<?php
  $items
['admin/settings/admin'] = array(
   
'title' => 'Administration theme',
   
'description' => 'Settings for how your administrative pages should look.',
   
'position' => 'left',
   
'page callback' => 'drupal_get_form',
   
'page arguments' => array('system_admin_theme_settings'),
   
'access arguments' => array('administer site configuration'),
   
'block callback' => 'system_admin_theme_settings',
   
'file' => 'system.admin.inc',
  );
?>

The keys are explained here: http://api.drupal.org/api/function/hook_menu

Please explain these keys:

mattyoung - January 12, 2009 - 23:44

    'block callback'
    'tab_parent'
    'tab_root'

What do these keys do?

I did a little digging and found...

mattyoung - January 23, 2009 - 01:15

'block callback' is not used in any meaningful way anywhere. The only place that sets it is in system.module line 270. But no where else make use of this field. This must be some detritus from the pass we can safely ignore?

As to 'tab_parent' and 'tab_root', it's described in system.install:

'tab_parent' => array(
        'description' => 'Only for local tasks (tabs) - the router path of the parent page (which may also be a local task).',

'tab_root' => array(
        'description' => 'Router path of the closest non-tab parent page. For pages that are not local tasks, this will be the same as the path.',

These are probably used internally to make two level local task tabs? I can't tell how these are supposed to be used. Looks to me like these are used internally and need not be explicitly set. Just a guess.

And 'position' is mentioned

varr - January 21, 2009 - 22:12

And 'position' is mentioned in the Example but not in the anatomy.

Here is the full hook_menu() api page: http://api.drupal.org/api/function/hook_menu/6

'position' is used by theme_admin_page()

mattyoung - January 23, 2009 - 00:21

'position' which will control which container it will be in. This is usually 'left' or 'right'.

This is for when you define your own administration section. It controls on the left or right column to show your section on the 'admin' page, 'weight' control up or down position.

Block in right side bar

Keyser - July 9, 2009 - 16:22

If we need to put block in rightside bar between other blocks then what $item[????] we need to specify ?

Mess with the best - die like the rest

I'm interested in

pobster - August 22, 2009 - 14:28

I'm interested in this;

$items['node/%node/panel_layout'] = array(
    'path' => $base . 'layout',
    'title' => 'Panel layout',
    'page callback' => 'panels_node_edit_layout',
    'weight' => 2,
  ) + $base;

Obviously from the Panels (panels_node) module, what's this 'path' being defined? I can find no record of it anywhere?

Pobster

Those tricky args

doven1 - September 14, 2009 - 18:34

The 'path' appears to be a dynamically built path to a particular panel page. It is aliased for the sake of a clean URL, but it looks to essentially be a URL constructed of the necessary arguments to notify Drupal of which panel it is you would like to view at that particular moment.

I dug around and could not find direct record, but did find some other places where it appears and is used in a similar fashion for this purpose.

admin pages

liquidcms - November 19, 2009 - 20:46

Haven't been able to find anything here about _menu hook handling for Admin pages - and it doesn't work as i would have expected

In most cases you just need something like this:

  $items['admin/settings/capsa/freelancer'] = array(
    'title'               => 'My Title',
    'description'         =>'Handles the application process for users to become freelance writers, copy editors, and editors.',
    'page callback'       => 'drupal_get_form',
    'page arguments'      => array('freelancer_admin_settings'),
    'access callback'     => '_freelancer_access',
    'access arguments'    => array('admin'),
  );

and this:

function freelancer_admin_settings() {
 
  [your form code here] 

  return system_settings_form($form);
}

... but, if you wanted to pass added args to your admin form:

  $items['admin/settings/capsa/freelancer'] = array(
    'title'               => 'My Title',
    'description'         =>'Handles the application process for users to become freelance writers, copy editors, and editors.',
    'page callback'       => 'drupal_get_form',
    'page arguments'      => array('freelancer_admin_settings', 'some additional arg value'),
    'access callback'     => '_freelancer_access',
    'access arguments'    => array('admin'),
  );

then this DOESN"T become the first argument to your page callback function (as i would have thought), you would then have this:

function freelancer_admin_settings($form_state, $myaddedarg) {
 
  [your form code here] 

  return system_settings_form($form);
}

That's absolutely nothing to

pobster - November 19, 2009 - 21:38

That's absolutely nothing to do with being an admin page, that's because your 'page callback' is 'drupal_get_form' - you can do the same thing with any menu item you define which is a simple form.

Pobster

 
 

Drupal is a registered trademark of Dries Buytaert.