|
|
|
|
@@ -0,0 +1,388 @@
|
|
|
|
|
<?php
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* @file
|
|
|
|
|
* Shows how to use Drupal's contextual links functionality.
|
|
|
|
|
*
|
|
|
|
|
* @see http://drupal.org/node/1089922
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* @defgroup contextual_links_example Example: Contextual Links
|
|
|
|
|
* @ingroup examples
|
|
|
|
|
* @{
|
|
|
|
|
* Example of implementing contextual links.
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Implements hook_menu().
|
|
|
|
|
*
|
|
|
|
|
* Drupal'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 Drupal 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 Drupal 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 Drupal 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 contextual_links_example_block_info()
|
|
|
|
|
* @see contextual_links_example_block_view()
|
|
|
|
|
* @see contextual_links_overview_page()
|
|
|
|
|
*/
|
|
|
|
|
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 Drupal'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' => 'drupal_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' => 'drupal_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;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Menu loader callback for the object defined by this module.
|
|
|
|
|
*
|
|
|
|
|
* @param int $id
|
|
|
|
|
* The ID of the object to load.
|
|
|
|
|
*
|
|
|
|
|
* @return object|FALSE
|
|
|
|
|
* A fully loaded object, or FALSE if the object does not exist.
|
|
|
|
|
*/
|
|
|
|
|
function contextual_links_example_object_load($id) {
|
|
|
|
|
// In a real use case, this function might load an object from the database.
|
|
|
|
|
// For the sake of this example, we just define a stub object with a basic
|
|
|
|
|
// title and content for any numeric ID that is passed in.
|
|
|
|
|
if (is_numeric($id)) {
|
|
|
|
|
$object = new stdClass();
|
|
|
|
|
$object->id = $id;
|
|
|
|
|
$object->title = t('Title for example object @id', array('@id' => $id));
|
|
|
|
|
$object->content = t('This is the content of example object @id.', array('@id' => $id));
|
|
|
|
|
return $object;
|
|
|
|
|
}
|
|
|
|
|
else {
|
|
|
|
|
return FALSE;
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Implements hook_block_info().
|
|
|
|
|
*/
|
|
|
|
|
function contextual_links_example_block_info() {
|
|
|
|
|
// Define the block that will display our module's content.
|
|
|
|
|
$blocks['example']['info'] = t('Contextual links example block');
|
|
|
|
|
return $blocks;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Implements hook_block_view().
|
|
|
|
|
*/
|
|
|
|
|
function contextual_links_example_block_view($delta = '') {
|
|
|
|
|
if ($delta == 'example') {
|
|
|
|
|
// Display our module's content inside a block. In a real use case, we
|
|
|
|
|
// might define a new block for each object that exists. For the sake of
|
|
|
|
|
// this example, though, we only define one block and hardcode it to always
|
|
|
|
|
// display object #1.
|
|
|
|
|
$id = 1;
|
|
|
|
|
$object = contextual_links_example_object_load($id);
|
|
|
|
|
$block['subject'] = t('Contextual links example block for object @id', array('@id' => $id));
|
|
|
|
|
$block['content'] = array(
|
|
|
|
|
// In order to attach contextual links, the block's content must be a
|
|
|
|
|
// renderable array. (Normally this would involve themed output using
|
|
|
|
|
// #theme, but for simplicity we just use HTML markup directly here.)
|
|
|
|
|
'#type' => 'markup',
|
|
|
|
|
'#markup' => filter_xss($object->content),
|
|
|
|
|
// Contextual links are attached to the block array using the special
|
|
|
|
|
// #contextual_links property. The #contextual_links property contains an
|
|
|
|
|
// array, keyed by the name of each module that is attaching contextual
|
|
|
|
|
// links to it.
|
|
|
|
|
'#contextual_links' => array(
|
|
|
|
|
'contextual_links_example' => array(
|
|
|
|
|
// Each element is itself an array, containing two elements which are
|
|
|
|
|
// combined together to form the base path whose contextual links
|
|
|
|
|
// should be attached. The two elements are split such that the first
|
|
|
|
|
// is the static part of the path and the second is the dynamic part.
|
|
|
|
|
// (This split is for performance reasons.) For example, the code
|
|
|
|
|
// below tells Drupal to load the menu item corresponding to the path
|
|
|
|
|
// "examples/contextual-links/$id" and attach all this item's
|
|
|
|
|
// contextual links (which were defined in hook_menu()) to the object
|
|
|
|
|
// when it is rendered. If the contextual links you are attaching
|
|
|
|
|
// don't have any dynamic elements in their path, you can pass an
|
|
|
|
|
// empty array as the second element.
|
|
|
|
|
'examples/contextual-links',
|
|
|
|
|
array($id),
|
|
|
|
|
),
|
|
|
|
|
),
|
|
|
|
|
);
|
|
|
|
|
// Since we are attaching our contextual links to a block, and the Block
|
|
|
|
|
// module takes care of rendering the block in such a way that contextual
|
|
|
|
|
// links are supported, we do not need to do anything else here. When the
|
|
|
|
|
// appropriate conditions are met, the contextual links we have defined
|
|
|
|
|
// will automatically appear attached to the block, next to the "Configure
|
|
|
|
|
// block" link that the Block module itself provides.
|
|
|
|
|
return $block;
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Menu callback; displays a listing of objects defined by this module.
|
|
|
|
|
*
|
|
|
|
|
* @see contextual_links_example_theme()
|
|
|
|
|
* @see contextual-links-example-object.tpl.php
|
|
|
|
|
* @see contextual_links_example_block_view()
|
|
|
|
|
*/
|
|
|
|
|
function contextual_links_overview_page() {
|
|
|
|
|
$build = array();
|
|
|
|
|
|
|
|
|
|
// For simplicity, we will hardcode this example page to list five of our
|
|
|
|
|
// module's objects.
|
|
|
|
|
for ($id = 1; $id <= 5; $id++) {
|
|
|
|
|
$object = contextual_links_example_object_load($id);
|
|
|
|
|
$build[$id] = array(
|
|
|
|
|
// To support attaching contextual links to an object that we are
|
|
|
|
|
// displaying on our own, the object must be themed in a particular way.
|
|
|
|
|
// See contextual_links_example_theme() and
|
|
|
|
|
// contextual-links-example-object.tpl.php for more discussion.
|
|
|
|
|
'#theme' => 'contextual_links_example_object',
|
|
|
|
|
'#object' => $object,
|
|
|
|
|
// Contextual links are attached to the block using the special
|
|
|
|
|
// #contextual_links property. See contextual_links_example_block_view()
|
|
|
|
|
// for discussion of the syntax used here.
|
|
|
|
|
'#contextual_links' => array(
|
|
|
|
|
'contextual_links_example' => array(
|
|
|
|
|
'examples/contextual-links',
|
|
|
|
|
array($id),
|
|
|
|
|
),
|
|
|
|
|
),
|
|
|
|
|
);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
return $build;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Implements hook_theme().
|
|
|
|
|
*
|
|
|
|
|
* @see template_preprocess_contextual_links_example_object()
|
|
|
|
|
*/
|
|
|
|
|
function contextual_links_example_theme() {
|
|
|
|
|
// The core Contextual Links module imposes two restrictions on how an object
|
|
|
|
|
// must be themed in order for it to display the object's contextual links in
|
|
|
|
|
// the user interface:
|
|
|
|
|
// - The object must use a template file rather than a theme function. See
|
|
|
|
|
// contextual-links-example-object.tpl.php for more information on how the
|
|
|
|
|
// template file should be structured.
|
|
|
|
|
// - The first variable passed to the template must be a renderable array. In
|
|
|
|
|
// this case, we accomplish that via the most common method, by passing a
|
|
|
|
|
// single renderable element.
|
|
|
|
|
return array(
|
|
|
|
|
'contextual_links_example_object' => array(
|
|
|
|
|
'template' => 'contextual-links-example-object',
|
|
|
|
|
'render element' => 'element',
|
|
|
|
|
),
|
|
|
|
|
);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Process variables for contextual-links-example-object.tpl.php.
|
|
|
|
|
*
|
|
|
|
|
* @see contextual_links_overview_page()
|
|
|
|
|
*/
|
|
|
|
|
function template_preprocess_contextual_links_example_object(&$variables) {
|
|
|
|
|
// Here we take the object that is being themed and define some useful
|
|
|
|
|
// variables that we will print in the template file.
|
|
|
|
|
$variables['title'] = filter_xss($variables['element']['#object']->title);
|
|
|
|
|
$variables['content'] = filter_xss($variables['element']['#object']->content);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Menu callback; displays an object defined by this module on its own page.
|
|
|
|
|
*
|
|
|
|
|
* @see contextual_links_overview_page()
|
|
|
|
|
*/
|
|
|
|
|
function contextual_links_example_object_page($object) {
|
|
|
|
|
// Here we render the object but without the #contextual_links property,
|
|
|
|
|
// since we don't want contextual links to appear when the object is already
|
|
|
|
|
// being displayed on its own page.
|
|
|
|
|
$build = array(
|
|
|
|
|
'#theme' => 'contextual_links_example_object',
|
|
|
|
|
'#object' => $object,
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
return $build;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Form callback; display the form for editing our module's content.
|
|
|
|
|
*
|
|
|
|
|
* @ingroup forms
|
|
|
|
|
* @see contextual_links_example_object_edit_form_submit()
|
|
|
|
|
*/
|
|
|
|
|
function contextual_links_example_object_edit_form($form, &$form_state, $object) {
|
|
|
|
|
$form['text'] = array(
|
|
|
|
|
'#markup' => t('This is the page that would allow you to edit object @id.', array('@id' => $object->id)),
|
|
|
|
|
'#prefix' => '<p>',
|
|
|
|
|
'#suffix' => '</p>',
|
|
|
|
|
);
|
|
|
|
|
$form['object_id'] = array(
|
|
|
|
|
'#type' => 'value',
|
|
|
|
|
'#value' => $object->id,
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
$form['actions'] = array('#type' => 'actions');
|
|
|
|
|
$form['actions']['submit'] = array(
|
|
|
|
|
'#type' => 'submit',
|
|
|
|
|
'#value' => t('Submit'),
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
return $form;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Submit handler for contextual_links_example_object_edit_form().
|
|
|
|
|
*/
|
|
|
|
|
function contextual_links_example_object_edit_form_submit($form, &$form_state) {
|
|
|
|
|
drupal_set_message(t('Object @id was edited.', array('@id' => $form_state['values']['object_id'])));
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Form callback; display the form for performing an example action on a node.
|
|
|
|
|
*
|
|
|
|
|
* @ingroup forms
|
|
|
|
|
* @see contextual_links_example_node_action_form_submit()
|
|
|
|
|
*/
|
|
|
|
|
function contextual_links_example_node_action_form($form, &$form_state, $node) {
|
|
|
|
|
$form['text'] = array(
|
|
|
|
|
'#markup' => t('This is the page that would allow you to perform an example action on node @nid.', array('@nid' => $node->nid)),
|
|
|
|
|
'#prefix' => '<p>',
|
|
|
|
|
'#suffix' => '</p>',
|
|
|
|
|
);
|
|
|
|
|
$form['nid'] = array(
|
|
|
|
|
'#type' => 'value',
|
|
|
|
|
'#value' => $node->nid,
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
$form['actions'] = array('#type' => 'actions');
|
|
|
|
|
$form['actions']['submit'] = array(
|
|
|
|
|
'#type' => 'submit',
|
|
|
|
|
'#value' => t('Submit'),
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
return $form;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Submit handler for contextual_links_example_node_action_form().
|
|
|
|
|
*/
|
|
|
|
|
function contextual_links_example_node_action_form_submit($form, &$form_state) {
|
|
|
|
|
drupal_set_message(t('The example action was performed on node @nid.', array('@nid' => $form_state['values']['nid'])));
|
|
|
|
|
}
|
|
|
|
|
/**
|
|
|
|
|
* @} End of "defgroup contextual_links_example".
|
|
|
|
|
*/
|
