contextual.module

<?php

/**
 * @file
 * Adds contextual links to perform actions related to elements on a page.
 */

/**
 * Implements hook_menu().
 */
function contextual_menu() {

  // @todo Remove this menu item in http://drupal.org/node/1954892 when theme
  //   callbacks are replaced with something else.
  $items['contextual/render'] = array(
    'route_name' => 'contextual_render',
    'theme callback' => 'ajax_base_page_theme',
  );
  return $items;
}

/**
 * Implements hook_toolbar().
 */
function contextual_toolbar() {
  if (!user_access('access contextual links')) {
    return;
  }
  $tab['contextual'] = array(
    '#type' => 'toolbar_item',
    'tab' => array(
      '#type' => 'html_tag',
      '#tag' => 'button',
      '#value' => t('Edit'),
      '#attributes' => array(
        'class' => array(
          'icon',
          'icon-edit',
        ),
        'role' => 'button',
        'aria-pressed' => 'false',
      ),
    ),
    '#wrapper_attributes' => array(
      'class' => array(
        'element-hidden',
        'contextual-toolbar-tab',
      ),
    ),
    '#attached' => array(
      'library' => array(
        array(
          'contextual',
          'drupal.contextual-toolbar',
        ),
      ),
    ),
  );
  return $tab;
}

/**
 * Implements hook_page_build().
 *
 * Adds the drupal.contextual-links library to the page for any user who has the
 * 'access contextual links' permission.
 *
 * @see contextual_preprocess()
 */
function contextual_page_build(&$page) {
  if (!user_access('access contextual links')) {
    return;
  }
  $page['#attached']['library'][] = array(
    'contextual',
    'drupal.contextual-links',
  );
}

/**
 * Implements hook_help().
 */
function contextual_help($path, $arg) {
  switch ($path) {
    case 'admin/help#contextual':
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
      $output .= '<p>' . t('The Contextual Links module displays links related to regions of pages on your site to users with <em>access contextual links</em> permission. For more information, see the online handbook entry for <a href="@contextual">Contextual Links module</a>.', array(
        '@contextual' => 'http://drupal.org/documentation/modules/contextual',
      )) . '</p>';
      $output .= '<h3>' . t('Uses') . '</h3>';
      $output .= '<dl>';
      $output .= '<dt>' . t('Displaying contextual links') . '</dt>';
      $output .= '<dd>' . t('Contextual links are supplied by modules, to give you quick access to tasks associated with regions of pages on your site. For instance, if you have a custom menu block displayed in a sidebar of your site, the Blocks and Menus modules will supply links to configure the block and edit the menu. The Contextual Links module collects these links into a list for display by your theme, and also adds JavaScript code to the page to hide the links initially, and display them when your mouse hovers over the block.') . '</dd>';
      $output .= '</dl>';
      return $output;
  }
}

/**
 * Implements hook_permission().
 */
function contextual_permission() {
  return array(
    'access contextual links' => array(
      'title' => t('Use contextual links'),
      'description' => t('Use contextual links to perform actions related to elements on a page.'),
    ),
  );
}

/**
 * Implements hook_library_info().
 */
function contextual_library_info() {
  $path = drupal_get_path('module', 'contextual');
  $libraries['drupal.contextual-links'] = array(
    'title' => 'Contextual Links',
    'website' => 'http://drupal.org/node/473268',
    'version' => VERSION,
    'js' => array(
      // Add the JavaScript, with a group and weight such that it will run
      // before modules/contextual/contextual.toolbar.js.
      $path . '/contextual.js' => array(
        'group' => JS_LIBRARY,
        'weight' => -2,
      ),
    ),
    'css' => array(
      $path . '/css/contextual.module.css' => array(),
      $path . '/css/contextual.theme.css' => array(),
    ),
    'dependencies' => array(
      array(
        'system',
        'jquery',
      ),
      array(
        'system',
        'drupal',
      ),
      array(
        'system',
        'drupalSettings',
      ),
      array(
        'system',
        'backbone',
      ),
      array(
        'system',
        'modernizr',
      ),
      array(
        'system',
        'jquery.once',
      ),
    ),
  );
  $libraries['drupal.contextual-toolbar'] = array(
    'title' => 'Contextual Links Toolbar Tab',
    'version' => VERSION,
    'js' => array(
      // Add the JavaScript, with a group and weight such that it will run
      // before modules/overlay/overlay-parent.js.
      $path . '/contextual.toolbar.js' => array(
        'group' => JS_LIBRARY,
        'weight' => -1,
      ),
    ),
    'css' => array(
      $path . '/css/contextual.toolbar.css' => array(),
    ),
    'dependencies' => array(
      array(
        'system',
        'jquery',
      ),
      array(
        'system',
        'drupal',
      ),
      array(
        'system',
        'backbone',
      ),
      array(
        'system',
        'jquery.once',
      ),
      array(
        'system',
        'drupal.tabbingmanager',
      ),
      array(
        'system',
        'drupal.announce',
      ),
    ),
  );
  return $libraries;
}

/**
 * Implements hook_element_info().
 */
function contextual_element_info() {
  $types['contextual_links_placeholder'] = array(
    '#pre_render' => array(
      'contextual_pre_render_placeholder',
    ),
    '#id' => NULL,
  );
  $types['contextual_links'] = array(
    '#pre_render' => array(
      'contextual_pre_render_links',
    ),
    '#theme' => 'links__contextual',
    '#links' => array(),
    '#attributes' => array(
      'class' => array(
        'contextual-links',
      ),
    ),
    '#attached' => array(
      'library' => array(
        array(
          'contextual',
          'drupal.contextual-links',
        ),
      ),
    ),
  );
  return $types;
}

/**
 * Implements hook_preprocess().
 *
 * @see contextual_pre_render_placeholder()
 * @see contextual_page_build()
 * @see \Drupal\contextual\ContextualController::render()
 */
function contextual_preprocess(&$variables, $hook, $info) {

  // Determine the primary theme function argument.
  if (!empty($info['variables'])) {
    $keys = array_keys($info['variables']);
    $key = $keys[0];
  }
  elseif (!empty($info['render element'])) {
    $key = $info['render element'];
  }
  if (!empty($key) && isset($variables[$key])) {
    $element = $variables[$key];
  }
  if (isset($element) && is_array($element) && !empty($element['#contextual_links'])) {

    // Mark this element as potentially having contextual links attached to it.
    $variables['attributes']['class'][] = 'contextual-region';

    // Renders a contextual links placeholder unconditionally, thus not breaking
    // the render cache. Although the empty placeholder is rendered for all
    // users, contextual_page_build() only adds the drupal.contextual-links
    // library for users with the 'access contextual links' permission, thus
    // preventing unnecessary HTTP requests for users without that permission.
    $variables['title_suffix']['contextual_links'] = array(
      '#type' => 'contextual_links_placeholder',
      '#id' => _contextual_links_to_id($element['#contextual_links']),
    );
  }
}

/**
 * Pre-render callback: Renders a contextual links placeholder into #markup.
 *
 * Renders an empty (hence invisible) placeholder div with a data-attribute that
 * contains an identifier ("contextual id"), which allows the JavaScript of the
 * drupal.contextual-links library to dynamically render contextual links.
 *
 * @param $element
 *   A structured array with #id containing a "contextual id".
 *
 * @return
 *   The passed-in element with a contextual link placeholder in '#markup'.
 *
 * @see _contextual_links_to_id()
 * @see contextual_element_info()
 */
function contextual_pre_render_placeholder($element) {
  $element['#markup'] = '<div data-contextual-id="' . $element['#id'] . '"></div>';
  return $element;
}

/**
 * Pre-render callback: Builds a renderable array for contextual links.
 *
 * @param $element
 *   A renderable array containing a #contextual_links property, which is a
 *   keyed array. Each key is the name of the implementing module, and each
 *   value is an array that forms the function arguments for
 *   menu_contextual_links(). For example:
 *   @code
 *     array('#contextual_links' => array(
 *       'block' => array('admin/structure/block/manage', array('system', 'menu-tools')),
 *       'menu' => array('admin/structure/menu/manage', array('tools')),
 *     ))
 *   @endcode
 *
 * @return
 *   A renderable array representing contextual links.
 *
 * @see menu_contextual_links()
 * @see contextual_element_info()
 */
function contextual_pre_render_links($element) {

  // Retrieve contextual menu links.
  $items = array();
  foreach ($element['#contextual_links'] as $module => $args) {
    $items += menu_contextual_links($module, $args[0], $args[1]);
  }

  // Transform contextual links into parameters suitable for theme_link().
  $links = array();
  foreach ($items as $class => $item) {
    $class = drupal_html_class($class);
    $links[$class] = array(
      'title' => $item['title'],
      'href' => $item['href'],
    );

    // @todo theme_links() should *really* use the same parameters as l().
    $item['localized_options'] += array(
      'query' => array(),
    );
    $item['localized_options']['query'] += drupal_get_destination();
    $links[$class] += $item['localized_options'];
  }
  $element['#links'] = $links;

  // Allow modules to alter the renderable contextual links element.
  drupal_alter('contextual_links_view', $element, $items);

  // If there are no links, tell drupal_render() to abort rendering.
  if (empty($element['#links'])) {
    $element['#printed'] = TRUE;
  }
  return $element;
}

/**
 * Implements hook_contextual_links_view_alter().
 *
 * @see \Drupal\contextual\Plugin\views\field\ContextualLinks::render()
 */
function contextual_contextual_links_view_alter(&$element, $items) {
  if (isset($element['#contextual_links']['contextual'])) {
    $encoded_links = $element['#contextual_links']['contextual'][2]['contextual-views-field-links'];
    $element['#links'] = drupal_json_decode(rawurldecode($encoded_links));
  }
}

/**
 * Serializes #contextual_links property value array to a string.
 *
 * Examples:
 *  - node:node:1:
 *  - views_ui:admin/structure/views/view:frontpage:location=page&view_name=frontpage&view_display_id=page_1
 *  - menu:admin/structure/menu/manage:tools:|block:admin/structure/block/manage:bartik.tools:
 *
 * So, expressed in a pattern:
 *  <module name>:<parent path>:<path args>:<options>
 *
 * The (dynamic) path args are joined with slashes. The options are encoded as a
 * query string.
 *
 * @param array $contextual_links
 *   The $element['#contextual_links'] value for some render element.
 *
 * @return string
 *   A serialized representation of a #contextual_links property value array for
 *   use in a data- attribute.
 */
function _contextual_links_to_id($contextual_links) {
  $id = '';
  foreach ($contextual_links as $module => $args) {
    $parent_path = $args[0];
    $path_args = implode('/', $args[1]);
    $metadata = drupal_http_build_query(isset($args[2]) ? $args[2] : array());
    if (drupal_strlen($id) > 0) {
      $id .= '|';
    }
    $id .= $module . ':' . $parent_path . ':' . $path_args . ':' . $metadata;
  }
  return $id;
}

/**
 * Unserializes the result of _contextual_links_to_id().
 *
 * @see _contextual_links_to_id
 *
 * @param string $id
 *   A serialized representation of a #contextual_links property value array.
 *
 * @return array
 *   The value for a #contextual_links property.
 */
function _contextual_id_to_links($id) {
  $contextual_links = array();
  $contexts = explode('|', $id);
  foreach ($contexts as $context) {
    list($module, $parent_path, $path_args, $metadata_raw) = explode(':', $context);
    $path_args = explode('/', $path_args);
    $metadata = drupal_get_query_array($metadata_raw);
    $contextual_links[$module] = array(
      $parent_path,
      $path_args,
      $metadata,
    );
  }
  return $contextual_links;
}