contextual.module

Adds contextual links to perform actions related to elements on a page.

File

drupal/core/modules/contextual/contextual.module
View source
  1. <?php
  2. /**
  3. * @file
  4. * Adds contextual links to perform actions related to elements on a page.
  5. */
  6. /**
  7. * Implements hook_menu().
  8. */
  9. function contextual_menu() {
  10. // @todo Remove this menu item in http://drupal.org/node/1954892 when theme
  11. // callbacks are replaced with something else.
  12. $items['contextual/render'] = array(
  13. 'route_name' => 'contextual_render',
  14. 'theme callback' => 'ajax_base_page_theme',
  15. );
  16. return $items;
  17. }
  18. /**
  19. * Implements hook_toolbar().
  20. */
  21. function contextual_toolbar() {
  22. if (!user_access('access contextual links')) {
  23. return;
  24. }
  25. $tab['contextual'] = array(
  26. '#type' => 'toolbar_item',
  27. 'tab' => array(
  28. '#type' => 'html_tag',
  29. '#tag' => 'button',
  30. '#value' => t('Edit'),
  31. '#attributes' => array(
  32. 'class' => array('icon', 'icon-edit'),
  33. 'role' => 'button',
  34. 'aria-pressed' => 'false',
  35. ),
  36. ),
  37. '#wrapper_attributes' => array(
  38. 'class' => array('element-hidden', 'contextual-toolbar-tab'),
  39. ),
  40. '#attached' => array(
  41. 'library' => array(
  42. array('contextual', 'drupal.contextual-toolbar'),
  43. ),
  44. ),
  45. );
  46. return $tab;
  47. }
  48. /**
  49. * Implements hook_page_build().
  50. *
  51. * Adds the drupal.contextual-links library to the page for any user who has the
  52. * 'access contextual links' permission.
  53. *
  54. * @see contextual_preprocess()
  55. */
  56. function contextual_page_build(&$page) {
  57. if (!user_access('access contextual links')) {
  58. return;
  59. }
  60. $page['#attached']['library'][] = array('contextual', 'drupal.contextual-links');
  61. }
  62. /**
  63. * Implements hook_help().
  64. */
  65. function contextual_help($path, $arg) {
  66. switch ($path) {
  67. case 'admin/help#contextual':
  68. $output = '';
  69. $output .= '<h3>' . t('About') . '</h3>';
  70. $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>';
  71. $output .= '<h3>' . t('Uses') . '</h3>';
  72. $output .= '<dl>';
  73. $output .= '<dt>' . t('Displaying contextual links') . '</dt>';
  74. $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>';
  75. $output .= '</dl>';
  76. return $output;
  77. }
  78. }
  79. /**
  80. * Implements hook_permission().
  81. */
  82. function contextual_permission() {
  83. return array(
  84. 'access contextual links' => array(
  85. 'title' => t('Use contextual links'),
  86. 'description' => t('Use contextual links to perform actions related to elements on a page.'),
  87. ),
  88. );
  89. }
  90. /**
  91. * Implements hook_library_info().
  92. */
  93. function contextual_library_info() {
  94. $path = drupal_get_path('module', 'contextual');
  95. $libraries['drupal.contextual-links'] = array(
  96. 'title' => 'Contextual Links',
  97. 'website' => 'http://drupal.org/node/473268',
  98. 'version' => VERSION,
  99. 'js' => array(
  100. // Add the JavaScript, with a group and weight such that it will run
  101. // before modules/contextual/contextual.toolbar.js.
  102. $path . '/contextual.js' => array('group' => JS_LIBRARY, 'weight' => -2),
  103. ),
  104. 'css' => array(
  105. $path . '/css/contextual.module.css' => array(),
  106. $path . '/css/contextual.theme.css' => array(),
  107. ),
  108. 'dependencies' => array(
  109. array('system', 'jquery'),
  110. array('system', 'drupal'),
  111. array('system', 'drupalSettings'),
  112. array('system', 'backbone'),
  113. array('system', 'modernizr'),
  114. array('system', 'jquery.once'),
  115. ),
  116. );
  117. $libraries['drupal.contextual-toolbar'] = array(
  118. 'title' => 'Contextual Links Toolbar Tab',
  119. 'version' => VERSION,
  120. 'js' => array(
  121. // Add the JavaScript, with a group and weight such that it will run
  122. // before modules/overlay/overlay-parent.js.
  123. $path . '/contextual.toolbar.js' => array('group' => JS_LIBRARY, 'weight' => -1),
  124. ),
  125. 'css' => array(
  126. $path . '/css/contextual.toolbar.css' => array(),
  127. ),
  128. 'dependencies' => array(
  129. array('system', 'jquery'),
  130. array('system', 'drupal'),
  131. array('system', 'backbone'),
  132. array('system', 'jquery.once'),
  133. array('system', 'drupal.tabbingmanager'),
  134. array('system', 'drupal.announce'),
  135. ),
  136. );
  137. return $libraries;
  138. }
  139. /**
  140. * Implements hook_element_info().
  141. */
  142. function contextual_element_info() {
  143. $types['contextual_links_placeholder'] = array(
  144. '#pre_render' => array('contextual_pre_render_placeholder'),
  145. '#id' => NULL,
  146. );
  147. $types['contextual_links'] = array(
  148. '#pre_render' => array('contextual_pre_render_links'),
  149. '#theme' => 'links__contextual',
  150. '#links' => array(),
  151. '#attributes' => array('class' => array('contextual-links')),
  152. '#attached' => array(
  153. 'library' => array(
  154. array('contextual', 'drupal.contextual-links'),
  155. ),
  156. ),
  157. );
  158. return $types;
  159. }
  160. /**
  161. * Implements hook_preprocess().
  162. *
  163. * @see contextual_pre_render_placeholder()
  164. * @see contextual_page_build()
  165. * @see \Drupal\contextual\ContextualController::render()
  166. */
  167. function contextual_preprocess(&$variables, $hook, $info) {
  168. // Determine the primary theme function argument.
  169. if (!empty($info['variables'])) {
  170. $keys = array_keys($info['variables']);
  171. $key = $keys[0];
  172. }
  173. elseif (!empty($info['render element'])) {
  174. $key = $info['render element'];
  175. }
  176. if (!empty($key) && isset($variables[$key])) {
  177. $element = $variables[$key];
  178. }
  179. if (isset($element) && is_array($element) && !empty($element['#contextual_links'])) {
  180. // Mark this element as potentially having contextual links attached to it.
  181. $variables['attributes']['class'][] = 'contextual-region';
  182. // Renders a contextual links placeholder unconditionally, thus not breaking
  183. // the render cache. Although the empty placeholder is rendered for all
  184. // users, contextual_page_build() only adds the drupal.contextual-links
  185. // library for users with the 'access contextual links' permission, thus
  186. // preventing unnecessary HTTP requests for users without that permission.
  187. $variables['title_suffix']['contextual_links'] = array(
  188. '#type' => 'contextual_links_placeholder',
  189. '#id' => _contextual_links_to_id($element['#contextual_links']),
  190. );
  191. }
  192. }
  193. /**
  194. * Pre-render callback: Renders a contextual links placeholder into #markup.
  195. *
  196. * Renders an empty (hence invisible) placeholder div with a data-attribute that
  197. * contains an identifier ("contextual id"), which allows the JavaScript of the
  198. * drupal.contextual-links library to dynamically render contextual links.
  199. *
  200. * @param $element
  201. * A structured array with #id containing a "contextual id".
  202. *
  203. * @return
  204. * The passed-in element with a contextual link placeholder in '#markup'.
  205. *
  206. * @see _contextual_links_to_id()
  207. * @see contextual_element_info()
  208. */
  209. function contextual_pre_render_placeholder($element) {
  210. $element['#markup'] = '<div data-contextual-id="' . $element['#id'] . '"></div>';
  211. return $element;
  212. }
  213. /**
  214. * Pre-render callback: Builds a renderable array for contextual links.
  215. *
  216. * @param $element
  217. * A renderable array containing a #contextual_links property, which is a
  218. * keyed array. Each key is the name of the implementing module, and each
  219. * value is an array that forms the function arguments for
  220. * menu_contextual_links(). For example:
  221. * @code
  222. * array('#contextual_links' => array(
  223. * 'block' => array('admin/structure/block/manage', array('system', 'menu-tools')),
  224. * 'menu' => array('admin/structure/menu/manage', array('tools')),
  225. * ))
  226. * @endcode
  227. *
  228. * @return
  229. * A renderable array representing contextual links.
  230. *
  231. * @see menu_contextual_links()
  232. * @see contextual_element_info()
  233. */
  234. function contextual_pre_render_links($element) {
  235. // Retrieve contextual menu links.
  236. $items = array();
  237. foreach ($element['#contextual_links'] as $module => $args) {
  238. $items += menu_contextual_links($module, $args[0], $args[1]);
  239. }
  240. // Transform contextual links into parameters suitable for theme_link().
  241. $links = array();
  242. foreach ($items as $class => $item) {
  243. $class = drupal_html_class($class);
  244. $links[$class] = array(
  245. 'title' => $item['title'],
  246. 'href' => $item['href'],
  247. );
  248. // @todo theme_links() should *really* use the same parameters as l().
  249. $item['localized_options'] += array('query' => array());
  250. $item['localized_options']['query'] += drupal_get_destination();
  251. $links[$class] += $item['localized_options'];
  252. }
  253. $element['#links'] = $links;
  254. // Allow modules to alter the renderable contextual links element.
  255. drupal_alter('contextual_links_view', $element, $items);
  256. // If there are no links, tell drupal_render() to abort rendering.
  257. if (empty($element['#links'])) {
  258. $element['#printed'] = TRUE;
  259. }
  260. return $element;
  261. }
  262. /**
  263. * Implements hook_contextual_links_view_alter().
  264. *
  265. * @see \Drupal\contextual\Plugin\views\field\ContextualLinks::render()
  266. */
  267. function contextual_contextual_links_view_alter(&$element, $items) {
  268. if (isset($element['#contextual_links']['contextual'])) {
  269. $encoded_links = $element['#contextual_links']['contextual'][2]['contextual-views-field-links'];
  270. $element['#links'] = drupal_json_decode(rawurldecode($encoded_links));
  271. }
  272. }
  273. /**
  274. * Serializes #contextual_links property value array to a string.
  275. *
  276. * Examples:
  277. * - node:node:1:
  278. * - views_ui:admin/structure/views/view:frontpage:location=page&view_name=frontpage&view_display_id=page_1
  279. * - menu:admin/structure/menu/manage:tools:|block:admin/structure/block/manage:bartik.tools:
  280. *
  281. * So, expressed in a pattern:
  282. * <module name>:<parent path>:<path args>:<options>
  283. *
  284. * The (dynamic) path args are joined with slashes. The options are encoded as a
  285. * query string.
  286. *
  287. * @param array $contextual_links
  288. * The $element['#contextual_links'] value for some render element.
  289. *
  290. * @return string
  291. * A serialized representation of a #contextual_links property value array for
  292. * use in a data- attribute.
  293. */
  294. function _contextual_links_to_id($contextual_links) {
  295. $id = '';
  296. foreach ($contextual_links as $module => $args) {
  297. $parent_path = $args[0];
  298. $path_args = implode('/', $args[1]);
  299. $metadata = drupal_http_build_query((isset($args[2])) ? $args[2] : array());
  300. if (drupal_strlen($id) > 0) {
  301. $id .= '|';
  302. }
  303. $id .= $module . ':' . $parent_path . ':' . $path_args . ':' . $metadata;
  304. }
  305. return $id;
  306. }
  307. /**
  308. * Unserializes the result of _contextual_links_to_id().
  309. *
  310. * @see _contextual_links_to_id
  311. *
  312. * @param string $id
  313. * A serialized representation of a #contextual_links property value array.
  314. *
  315. * @return array
  316. * The value for a #contextual_links property.
  317. */
  318. function _contextual_id_to_links($id) {
  319. $contextual_links = array();
  320. $contexts = explode('|', $id);
  321. foreach ($contexts as $context) {
  322. list($module, $parent_path, $path_args, $metadata_raw) = explode(':', $context);
  323. $path_args = explode('/', $path_args);
  324. $metadata = drupal_get_query_array($metadata_raw);
  325. $contextual_links[$module] = array($parent_path, $path_args, $metadata);
  326. }
  327. return $contextual_links;
  328. }

Functions

Namesort descending Description
contextual_contextual_links_view_alter Implements hook_contextual_links_view_alter().
contextual_element_info Implements hook_element_info().
contextual_help Implements hook_help().
contextual_library_info Implements hook_library_info().
contextual_menu Implements hook_menu().
contextual_page_build Implements hook_page_build().
contextual_permission Implements hook_permission().
contextual_preprocess Implements hook_preprocess().
contextual_pre_render_links Pre-render callback: Builds a renderable array for contextual links.
contextual_pre_render_placeholder Pre-render callback: Renders a contextual links placeholder into #markup.
contextual_toolbar Implements hook_toolbar().
_contextual_id_to_links Unserializes the result of _contextual_links_to_id().
_contextual_links_to_id Serializes #contextual_links property value array to a string.