Drupal’s hook_menu is one of the most important drupal hook. It defines paths in the drupal system and what they do. You can not write a custom module without understanding hook_menu.
The functionality could be listing of content on the site or an administrative page or it could just be a special page that needs to be generated and maintained as a custom module, all these can be met by writing a menu callback. hook_menu is normally used in a custom module when using drupal’s page, views generated pages do not meet our custom requirements.
Often we may not want to create new menu callbacks but may use functionalities provided by other custom modules menu callbacks. There may be a need to customize the menucall backs of core or custom modules to meet the requirements.
The below note gives an overview of the different usecases of hook_menu and also a peek in to how to alter a core/contributed menu callbacks in our own custom module.
The different usecases of a hook_menu
1) Custom page or functionality on the site. e.g: Blog module’s callback blog_page that is Listing of all blogs on the site.
$items['blog'] = array(
'title' => 'blogs',
'description' => 'Listing of blogs.',
'page callback' => 'blog_page',
'access arguments' => array('access content'),
'type' => MENU_SUGGESTED_ITEM,
);
User modules’s callback admin/user/user. This menucallback lists users, provides for links to edit and add new users
$items['admin/user/user'] = array(
'title' => 'Users',
'description' => 'List, add, and edit users.',
'page callback' => 'user_admin',
'page arguments' => array('list'),
'access arguments' => array('administer users'),
'file' => 'user.admin.inc',
2) Generate Forms: All forms that are built in Drupal will have an associated menu callback. Forms that need beyond the node create and edit forms that are available with Drupal need to be built using page callback drupal_get_form. These could range from admin forms to user forms. Refer Form API for more information on building forms.
e.g: Node modules: create and edit content forms.
Contact module: Site wide contact form, user contact forms and Contact admin settings forms.
$items['admin/build/contact'] = array(
'title' => 'Contact form',
'description' => 'Create a system contact form and set up categories for the form to use.',
'page callback' => 'contact_admin_categories',
'access arguments' => array('administer site-wide contact form'),
'file' => 'contact.admin.inc',
);
3) AJAX callbacks: Any AJAX functionality on the site will have an associated callback that defines the action that happens or the value that needs to be retrieved on AJAX .
e.g: user/autocomplete AJAX callback that is called in used in the author field of the create and edit node form.
$items['user/autocomplete'] = array(
'title' => 'User autocomplete',
'page callback' => 'user_autocomplete',
'access callback' => 'user_access',
'access arguments' => array('access user profiles'),
'type' => MENU_CALLBACK,
'file' => 'user.pages.inc',
);
4) Create RSS feeds
The hook_menu not only allows us to define other content formats that can be generated in response to a http request.
e.g: Node/blog modules provides for rss.xml callback that provides rss feeds.
$items['rss.xml'] = array(
'title' => 'RSS feed',
'page callback' => 'node_feed',
'access arguments' => array('access content'),
'type' => MENU_CALLBACK,
For a full list of parameters that can be associated with a menucallback, visit hook_menu drupal 6 api page. Most importantly, in all the above the menu callback created can be associated with specific permissions. The access arguments help in defining the access rules and also in providing security to the menu callbacks.
Proper use of these parameters is important in implementing the functionality and also in organising the associated code.
Customizing core/contributed module’s menucallbacks
Some usecases include:
1. Rename the path of a core or contributed module. This can be achieved using: path_set_alias.
path_set_alias('og/xxx/'. $node->nid, $alias_path);
This is particularly useful for modules that are not supported by pathauto. Path auto module provides for an admin interface to path alias various content in Drupal.
Removing user profile tabs using menu_alter
function my_module_menu_alter(&$items) {
$items['user/...']['type'] = MENU_CALLBACK;
} In the above example we are changing the type of Menu callback user/... from MENU_LOCAL_TASK to a regular MENU_CALLBACK. This callback will no longer be displayed in a tab.
menu_alter could be extended to change the access callback, redirect to another custom callback, etc.
function my_module_menu_alter(&$items) {
$items['cart']['access arguments'] = array('access my module'); $items['cart']['page callback'] = 'drupal_goto'; $items['cart']['page arguments'] = array('my_module_menu');
} In the above example we reset the access arguments of the ‘cart’ callback in ubercart module to my modules permission 'access my module', redirect the cart callback to my modules callback my_module_menu.
The functionality could be listing of content on the site or an administrative page or it could just be a special page that needs to be generated and maintained as a custom module, all these can be met by writing a menu callback. hook_menu is normally used in a custom module when using drupal’s page, views generated pages do not meet our custom requirements.
Often we may not want to create new menu callbacks but may use functionalities provided by other custom modules menu callbacks. There may be a need to customize the menucall backs of core or custom modules to meet the requirements.
The below note gives an overview of the different usecases of hook_menu and also a peek in to how to alter a core/contributed menu callbacks in our own custom module.
The different usecases of a hook_menu
1) Custom page or functionality on the site. e.g: Blog module’s callback blog_page that is Listing of all blogs on the site.
$items['blog'] = array(
'title' => 'blogs',
'description' => 'Listing of blogs.',
'page callback' => 'blog_page',
'access arguments' => array('access content'),
'type' => MENU_SUGGESTED_ITEM,
);
User modules’s callback admin/user/user. This menucallback lists users, provides for links to edit and add new users
$items['admin/user/user'] = array(
'title' => 'Users',
'description' => 'List, add, and edit users.',
'page callback' => 'user_admin',
'page arguments' => array('list'),
'access arguments' => array('administer users'),
'file' => 'user.admin.inc',
2) Generate Forms: All forms that are built in Drupal will have an associated menu callback. Forms that need beyond the node create and edit forms that are available with Drupal need to be built using page callback drupal_get_form. These could range from admin forms to user forms. Refer Form API for more information on building forms.
e.g: Node modules: create and edit content forms.
Contact module: Site wide contact form, user contact forms and Contact admin settings forms.
$items['admin/build/contact'] = array(
'title' => 'Contact form',
'description' => 'Create a system contact form and set up categories for the form to use.',
'page callback' => 'contact_admin_categories',
'access arguments' => array('administer site-wide contact form'),
'file' => 'contact.admin.inc',
);
3) AJAX callbacks: Any AJAX functionality on the site will have an associated callback that defines the action that happens or the value that needs to be retrieved on AJAX .
e.g: user/autocomplete AJAX callback that is called in used in the author field of the create and edit node form.
$items['user/autocomplete'] = array(
'title' => 'User autocomplete',
'page callback' => 'user_autocomplete',
'access callback' => 'user_access',
'access arguments' => array('access user profiles'),
'type' => MENU_CALLBACK,
'file' => 'user.pages.inc',
);
4) Create RSS feeds
The hook_menu not only allows us to define other content formats that can be generated in response to a http request.
e.g: Node/blog modules provides for rss.xml callback that provides rss feeds.
$items['rss.xml'] = array(
'title' => 'RSS feed',
'page callback' => 'node_feed',
'access arguments' => array('access content'),
'type' => MENU_CALLBACK,
For a full list of parameters that can be associated with a menucallback, visit hook_menu drupal 6 api page. Most importantly, in all the above the menu callback created can be associated with specific permissions. The access arguments help in defining the access rules and also in providing security to the menu callbacks.
Proper use of these parameters is important in implementing the functionality and also in organising the associated code.
Customizing core/contributed module’s menucallbacks
Some usecases include:
1. Rename the path of a core or contributed module. This can be achieved using: path_set_alias.
path_set_alias('og/xxx/'. $node->nid, $alias_path);
This is particularly useful for modules that are not supported by pathauto. Path auto module provides for an admin interface to path alias various content in Drupal.
2. Reset some of the menucallback's properties by using Hook Menu Alter.
Removing user profile tabs using menu_alter
function my_module_menu_alter(&$items) {
$items['user/...']['type'] = MENU_CALLBACK;
} In the above example we are changing the type of Menu callback user/... from MENU_LOCAL_TASK to a regular MENU_CALLBACK. This callback will no longer be displayed in a tab.
menu_alter could be extended to change the access callback, redirect to another custom callback, etc.
function my_module_menu_alter(&$items) {
$items['cart']['access arguments'] = array('access my module'); $items['cart']['page callback'] = 'drupal_goto'; $items['cart']['page arguments'] = array('my_module_menu');
} In the above example we reset the access arguments of the ‘cart’ callback in ubercart module to my modules permission 'access my module', redirect the cart callback to my modules callback my_module_menu.
References:
hook_menu api reference:
hook_menu_alter:
Drupal's Menu System:
in hook menu, if i created menu and its displaying fine, assume if i changed the menu label name, why should i reinstall, if i am reinstall changes not reflecting. why this happening? what is the process behind in this ?
ReplyDelete