contextual_links_example.module

<?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".
 */