function hook_menu_local_tasks_alter

You are here

7 system.api.php hook_menu_local_tasks_alter(&$data, $router_item, $root_path)
8 system.api.php hook_menu_local_tasks_alter(&$data, $route_name)

Alter tabs and actions displayed on the page before they are rendered.

This hook is invoked by menu_local_tasks(). The system-determined tabs and actions are passed in by reference. Additional tabs or actions may be added, or existing items altered.

Each tab or action is an associative array containing:

  • #theme: The theme function to use to render.
  • #link: An associative array containing:
    • title: The localized title of the link.
    • href: The system path to link to.
    • localized_options: An array of options to pass to l().
  • #active: Whether the link should be marked as 'active'.

Parameters

$data: An associative array containing:

  • actions: An associative array containing:

    • count: The amount of actions determined by the menu system, which can be ignored.
    • output: A list of of actions, each one being an associative array as described above.
  • tabs: An indexed array (list) of tab levels (up to 2 levels), each containing an associative array:

    • count: The amount of tabs determined by the menu system. This value does not need to be altered if there is more than one tab.
    • output: A list of of tabs, each one being an associative array as described above.

$router_item: The menu system router item of the page.

$root_path: The path to the root item for this set of tabs.

Related topics

3 functions implement hook_menu_local_tasks_alter()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

blog_menu_local_tasks_alter in modules/blog/blog.module
Implements hook_menu_local_tasks_alter().
forum_menu_local_tasks_alter in modules/forum/forum.module
Implements hook_menu_local_tasks_alter().
node_menu_local_tasks_alter in modules/node/node.module
Implements hook_menu_local_tasks_alter().
1 invocation of hook_menu_local_tasks_alter()
menu_local_tasks in includes/menu.inc
Collects the local tasks (tabs), action links, and the root path.

File

modules/system/system.api.php, line 1451
Hooks provided by Drupal core and the System module.

Code

function hook_menu_local_tasks_alter(&$data, $router_item, $root_path) {
  // Add an action linking to node/add to all pages.
  $data['actions']['output'][] = array(
    '#theme' => 'menu_local_task',
    '#link' => array(
      'title' => t('Add new content'),
      'href' => 'node/add',
      'localized_options' => array(
        'attributes' => array(
          'title' => t('Add new content'),
        ),
      ),
    ),
  );

  // Add a tab linking to node/add to all pages.
  $data['tabs'][0]['output'][] = array(
    '#theme' => 'menu_local_task',
    '#link' => array(
      'title' => t('Example tab'),
      'href' => 'node/add',
      'localized_options' => array(
        'attributes' => array(
          'title' => t('Add new content'),
        ),
      ),
    ),
    
    // Define whether this link is active. This can be omitted for
    // implementations that add links to pages outside of the current page
    // context.
    '#active' => ($router_item['path'] == $root_path),
  );
}

Comments

This function appears only to add tabs visible to administrators, even if the URL is otherwise accessible - see this ticket. I'm still trying to determine if this is by design, but perhaps this note will save others the frustration of trying to create tabs for anonymous users using this function, at least for the time being.

Make sure there's at least 2 tabs or else none will display

If you add a tab using this, it is best to update the 'count' array element. This will generally cause tabs to be displayed if only one tab was defined by other code.

E.g.

  $data['tabs']['0']['count'] = $data['tabs']['0']['count'] + 1;

If you just need to have one tab and you want it displayed, just set count to 2 (more than 1; even if you actually just have 1 tab) and it will be displayed.