The Drupal 6 menu system: architecture, do, don't and tricks

(part 1)Peter Wolanin

August 27, 2008Drupalcon, Szeged

Goals of the 6.x Menu System

• Separation of page serving and link rendering.

• Reduced footprint: – interpret dynamic paths without calling hook_menu.

– Don’t have all the available callbacks in memory.

• Scalability of link storage and rendering - how can we handle a site with 10,000 links.

Two independent data tables

• {menu_router}– Define page callbacks (including local tasks)

– May have a fully defined path, or one or more wildcards (%).

• {menu_links}– Every link has a corresponding router entry (except external links).

– The router entry’s access callback determines whether the link is visible.

{menu_router} == hook_menu

• Each item returned by a hook_menu implementation become a row in the table.

• It defines the valid paths.• Defines how access is permitted to paths.

• Defines which function is used to render a page at a path.

• Defines the default title for the page.

{menu_links}: module-created

• Deleting everything in {menu_links} would not affect page serving.

• For convenience and to provide a navigation menu, most {menu_router} entries have a system-module-created link.

• You should not add an item to your hook_menu() just to get a link.

• Modules that want to add links should do so using menu_link_save() (or use menu_link_maintain() to create/update).

Creating a link is easy

• Drupal will generate most of the elements of a menu link for you.

• The only mandatory keys are link_path and link_title.

• If you want to be able to configure it later in the menu module UI, don’t define ‘module’ and use a menu name from {menu_custom}

• No access checks for “external” links (e.g. the link path starts with http://).

{menu_links}: encodes hierarchy

• For Druapl 6, there is a hard-coded limit of 9 levels of depth.

• We store the materialized path for each link as a series of columns, as well as the depth.

9

2

7

13

21 14 65

11

Brief anatomy of hook_menu

Little used elements:• ‘block callback’, ‘position’ - see

function system_main_admin_page()• ‘tab_parent’ and ‘tab_root’ can allow you to let a local task appear on a page regardless of path (use with caution).

• ‘menu_name’ is not used in the router, but is used by system module when saving a link for this router item (caution: core bug).

The new (“secret”) hooks

• hook_menu_alter() - this lets you alter any property of a router item declared by a module’s hook_menu().

• hook_translated_menu_link_alter() - in this case “translated” is distinct from “localized”. This hook is double secret (find out why later).

• hook_menu_link_alter() - lets you alter a link as it is saved.

Example: hook_menu_alter()

• CCK is using this hook to changing the page callback for the node-type overview page.

• Note: filepath - the default filepath is that of the node module (which declared this router item).

Continued: hook_menu_alter()

• Views uses this to add router items that may replace ones declared by other modules, depending on the specified View path.

• In general, it may be easier to alter individual elements, rather than replacing an item, since you need to be sure to fill in all the keys, including the ‘module’ key the specifies which module created the item (used for finding an include file).

hook_translated_menu_link_alter()

• This hook is called after a link has been processed to check whether the user has access, including possibly loading objects based on the path before the link in rendered.

• However, since few links are altered, for performance this hook is only called on a link if the “alter” element of the link’s options is not empty (e.g. TRUE).

hook_menu_link_alter()• This hook can be used in combination with hook_translated_menu_link_alter().

Two more possible gotchas:

• The ‘localized_options’ are used for rendering a menu link.

• If the link’s ‘access’ is not TRUE, the link will not have been localized.

See the Drupal handbooks:

• Drupal menu system (Drupal 6.x) http://drupal.org/node/102338

• New hooks: hook_menu_alter() and hook_menu_link_alter() http://drupal.org/node/174891

• When and how to use menu_links http://drupal.org/node/217393