1 contextual_links_example.module contextual_links_example_menu()

Implements hook_menu().

Backdrop's menu system allows you to indicate that particular menu items should be displayed as contextual links. If you hover over a block or node while logged in as an administrator (and with the Contextual Links module enabled) you'll see a small gear icon appear. Click on this icon, and the list of items that appears in the exposed menu are what Backdrop calls "contextual links".

Contextual links allow site administrators to quickly perform actions related to elements on a page, without having to hunt through the administrative interface. As such, you should usually attach them to objects that appear on the main part of a Backdrop site and limit them to a few common tasks that are frequently performed (for example, "edit" or "configure"). Do not rely on contextual links being present for your module to work correctly, since they are a convenience feature only. Within Backdrop core, the Contextual Links module must be enabled (and the user viewing the page must have the "access contextual links" permission) in order for the contextual links corresponding to actions that the user can perform to actually be injected into the page's HTML.

Three examples of contextual links are provided here. Although none are difficult to implement, they are presented in order of increasing complexity:

  • Attaching contextual links to a node.
  • Attaching contextual links to a block.
  • Attaching contextual links to an arbitrary piece of content defined by your module.

See also

contextual_links_example_block_info()

contextual_links_example_block_view()

contextual_links_overview_page()

Related topics

Example: Contextual Links This example demonstrates how to implement contextual links.

File

modules/examples/contextual_links_example/contextual_links_example.module, line 48
Hooks implementations for the Contextual Links Example module.

Code

function contextual_links_example_menu() {
  // First example (attaching contextual links to a node):
  //
  // Many modules add tabs to nodes underneath the node/<nid> path. If the path
  // you are adding corresponds to a commonly performed action on the node, you
  // can choose to expose it as a contextual link. Since the Node module
  // already has code to display all contextual links underneath the node/<nid>
  // path (such as "Edit" and "Delete") when a node is being rendered outside
  // of its own page (for example, when a teaser of the node is being displayed
  // on the front page of the site), you only need to inform Backdrop's menu
  // system that your path is a contextual link also, and it will automatically
  // appear with the others. In the example below, we add a contextual link
  // named "Example action" to the list.
  $items['node/%node/example-action'] = array(
    'title' => 'Example action',
    'page callback' => 'backdrop_get_form',
    'page arguments' => array('contextual_links_example_node_action_form', 1),
    'access callback' => TRUE,
    // To be displayed as a contextual link, a menu item should be defined as
    // one of the node's local tasks.
    'type' => MENU_LOCAL_TASK,
    // To make the local task display as a contextual link, specify the
    // optional 'context' argument. The most common method is to set both
    // MENU_CONTEXT_PAGE and MENU_CONTEXT_INLINE (shown below), which causes
    // the link to display as both a tab on the node page and as an entry in
    // the contextual links dropdown. This is recommended for most cases
    // because not all users who have permission to visit the "Example action"
    // page will necessarily have access to contextual links, and they still
    // need a way to get to the page via the user interface.
    'context' => MENU_CONTEXT_PAGE | MENU_CONTEXT_INLINE,
    // If we give the item a large weight, we can make it display as the last
    // tab on the page, as well as the last item inside the contextual links
    // dropdown.
    'weight' => 80,
  );

  // Second example (attaching contextual links to a block):
  //
  // If your module provides content that is displayed in a block, you can
  // attach contextual links to the block that allow actions to be performed on
  // it. This is useful for administrative pages that affect the content
  // wherever it is displayed or used on the site. For configuration options
  // that only affect the appearance of the content in the block itself, it is
  // better to implement hook_block_configure() rather than creating a separate
  // administrative page (this allows your options to appear when an
  // administrator clicks the existing "Configure block" contextual link
  // already provided by the Block module).
  //
  // In the code below, we assume that your module has a type of object
  // ("contextual links example object") that will be displayed in a block. The
  // code below defines menu items for this object using a standard pattern,
  // with "View" and "Edit object" as the object's local tasks, and makes the
  // "Edit object" item display as a contextual link in addition to a tab. Once
  // the contextual links are defined here, additional steps are required to
  // actually display the content in a block and attach the contextual links to
  // the block itself. This occurs in contextual_links_example_block_info() and
  // contextual_links_example_block_view().
  $items['examples/contextual-links/%contextual_links_example_object'] = array(
    'title' => 'Contextual links example object',
    'page callback' => 'contextual_links_example_object_page',
    'page arguments' => array(2),
    'access callback' => TRUE,
  );
  $items['examples/contextual-links/%contextual_links_example_object/view'] = array(
    'title' => 'View',
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'weight' => -10,
  );
  $items['examples/contextual-links/%contextual_links_example_object/edit'] = array(
    'title' => 'Edit object',
    'page callback' => 'backdrop_get_form',
    'page arguments' => array('contextual_links_example_object_edit_form', 2),
    'access callback' => TRUE,
    'type' => MENU_LOCAL_TASK,
    // As in our first example, this is the line of code that makes "Edit
    // "object" display as a contextual link in addition to as a tab.
    'context' => MENU_CONTEXT_PAGE | MENU_CONTEXT_INLINE,
  );

  // Third example (attaching contextual links directly to your module's
  // content):
  //
  // Sometimes your module may want to display its content in an arbitrary
  // location and attach contextual links there. For example, you might
  // display your content in a listing on its own page and then attach the
  // contextual links directly to each piece of content in the listing. Here,
  // we will reuse the menu items and contextual links that were defined for
  // our example object above, and display them in a listing in
  // contextual_links_overview_page().
  $items['examples/contextual-links'] = array(
    'title' => 'Contextual Links Example',
    'page callback' => 'contextual_links_overview_page',
    'access callback' => TRUE,
  );

  return $items;
}