contextual.module 7.66 KB
Newer Older
1 2 3 4 5 6 7
<?php

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

8
use Drupal\Component\Serialization\Json;
9
use Drupal\Component\Utility\UrlHelper;
10
use Drupal\Core\Language\LanguageInterface;
11
use Drupal\Core\Routing\RouteMatchInterface;
12

13 14 15 16
/**
 * Implements hook_toolbar().
 */
function contextual_toolbar() {
17 18 19 20 21 22 23 24
  $items = [];
  $items['contextual'] = [
    '#cache' => [
      'contexts' => [
        'user.permissions',
      ],
    ],
  ];
25

26
  if (!\Drupal::currentUser()->hasPermission('access contextual links')) {
27
    return $items;
28 29
  }

30
  $items['contextual'] += array(
31
    '#type' => 'toolbar_item',
32 33 34 35 36
    'tab' => array(
      '#type' => 'html_tag',
      '#tag' => 'button',
      '#value' => t('Edit'),
      '#attributes' => array(
37
        'class' => array('toolbar-icon', 'toolbar-icon-edit'),
38 39 40 41 42
        'role' => 'button',
        'aria-pressed' => 'false',
      ),
    ),
    '#wrapper_attributes' => array(
43
      'class' => array('hidden', 'contextual-toolbar-tab'),
44 45 46
    ),
    '#attached' => array(
      'library' => array(
47
        'contextual/drupal.contextual-toolbar',
48 49 50 51
      ),
    ),
  );

52
  return $items;
53 54
}

55
/**
56
 * Implements hook_page_attachments().
57 58 59 60 61 62
 *
 * Adds the drupal.contextual-links library to the page for any user who has the
 * 'access contextual links' permission.
 *
 * @see contextual_preprocess()
 */
63
function contextual_page_attachments(array &$page) {
64
  if (!\Drupal::currentUser()->hasPermission('access contextual links')) {
65 66 67
    return;
  }

68
  $page['#attached']['library'][] = 'contextual/drupal.contextual-links';
69 70
}

71 72 73
/**
 * Implements hook_help().
 */
74
function contextual_help($route_name, RouteMatchInterface $route_match) {
75 76
  switch ($route_name) {
    case 'help.page.contextual':
77 78
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
79
      $output .= '<p>' . t('The Contextual links module gives users with the <em>Use contextual links</em> permission quick access to tasks associated with certain areas of pages on your site. For example, a menu displayed as a block has links to edit the menu and configure the block. For more information, see <a href="!contextual">the online documentation for the Contextual Links module</a>.', array('!contextual' => 'https://www.drupal.org/documentation/modules/contextual')) . '</p>';
80 81 82
      $output .= '<h3>' . t('Uses') . '</h3>';
      $output .= '<dl>';
      $output .= '<dt>' . t('Displaying contextual links') . '</dt>';
83 84 85
      $output .= '<dd>';
      $output .= t('Contextual links for an area on a page are displayed using a contextual links button. There are two ways to make the contextual links button visible:');
      $output .= '<ol>';
86 87
      $sample_picture = '<img src="' . file_create_url('core/misc/icons/bebebe/pencil.svg') . '" alt="' . t('contextual links button') . '" />';
      $output .= '<li>' . t('Hovering over the area of interest will temporarily make the contextual links button visible (which looks like a pencil in most themes, and is normally displayed in the upper right corner of the area). The icon typically looks like this: !picture', array('!picture' => $sample_picture)) . '</li>';
88
      $output .= '<li>' . t('If you have the <a href="!toolbar">Toolbar module</a> enabled, clicking the contextual links button in the toolbar (which looks like a pencil) will make all contextual links buttons on the page visible. Clicking this button again will toggle them to invisible.', array('!toolbar' => (\Drupal::moduleHandler()->moduleExists('toolbar')) ? \Drupal::url('help.page', array('name' => 'toolbar')) : '#')) . '</li>';
89 90 91
      $output .= '</ol>';
      $output .= t('Once the contextual links button for the area of interest is visible, click the button to display the links.');
      $output .= '</dd>';
92 93 94 95 96
      $output .= '</dl>';
      return $output;
  }
}

97
/**
98
 * Implements hook_preprocess().
99
 *
100
 * @see contextual_pre_render_placeholder()
101
 * @see contextual_page_attachments()
102
 * @see \Drupal\contextual\ContextualController::render()
103
 */
104
function contextual_preprocess(&$variables, $hook, $info) {
105
  // Determine the primary theme function argument.
106 107
  if (!empty($info['variables'])) {
    $keys = array_keys($info['variables']);
108 109
    $key = $keys[0];
  }
110 111
  elseif (!empty($info['render element'])) {
    $key = $info['render element'];
112
  }
113
  if (!empty($key) && isset($variables[$key])) {
114 115 116 117
    $element = $variables[$key];
  }

  if (isset($element) && is_array($element) && !empty($element['#contextual_links'])) {
118
    // Mark this element as potentially having contextual links attached to it.
119
    $variables['attributes']['class'][] = 'contextual-region';
120 121 122

    // Renders a contextual links placeholder unconditionally, thus not breaking
    // the render cache. Although the empty placeholder is rendered for all
123 124 125
    // users, contextual_page_attachments() only adds the asset library for
    // users with the 'access contextual links' permission, thus preventing
    // unnecessary HTTP requests for users without that permission.
126 127 128 129
    $variables['title_suffix']['contextual_links'] = array(
      '#type' => 'contextual_links_placeholder',
      '#id' => _contextual_links_to_id($element['#contextual_links']),
    );
130 131 132
  }
}

133 134 135 136 137 138 139
/**
 * 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'])) {
140
    $encoded_links = $element['#contextual_links']['contextual']['metadata']['contextual-views-field-links'];
141
    $element['#links'] = Json::decode(rawurldecode($encoded_links));
142 143 144 145 146 147 148
  }
}

/**
 * Serializes #contextual_links property value array to a string.
 *
 * Examples:
149 150 151
 *  - node:node=1:langcode=en
 *  - views_ui_edit:view=frontpage:location=page&view_name=frontpage&view_display_id=page_1&langcode=en
 *  - menu:menu=tools:langcode=en|block:block=bartik.tools:langcode=en
152 153
 *
 * So, expressed in a pattern:
154
 *  <group>:<route parameters>:<metadata>
155
 *
156
 * The route parameters and options are encoded as query strings.
157 158 159 160 161 162 163 164 165
 *
 * @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) {
166
  $ids = array();
167
  $langcode = \Drupal::languageManager()->getCurrentLanguage(LanguageInterface::TYPE_URL)->getId();
168
  foreach ($contextual_links as $group => $args) {
169
    $route_parameters = UrlHelper::buildQuery($args['route_parameters']);
170 171 172 173 174 175
    $args += ['metadata' => []];
    // Add the current URL language to metadata so a different ID will be
    // computed when URLs vary by language. This allows to store different
    // language-aware contextual links on the client side.
    $args['metadata'] += ['langcode' => $langcode];
    $metadata = UrlHelper::buildQuery($args['metadata']);
176
    $ids[] = "{$group}:{$route_parameters}:{$metadata}";
177
  }
178
  return implode('|', $ids);
179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195
}

/**
 * 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) {
196 197
    list($group, $route_parameters_raw, $metadata_raw) = explode(':', $context);
    parse_str($route_parameters_raw, $route_parameters);
198 199
    $metadata = array();
    parse_str($metadata_raw, $metadata);
200 201 202 203
    $contextual_links[$group] = array(
      'route_parameters' => $route_parameters,
      'metadata' => $metadata,
    );
204 205 206
  }
  return $contextual_links;
}