block.api.php

  1. 7.x drupal/modules/block/block.api.php
  2. 8.x drupal/core/modules/block/block.api.php

Hooks provided by the Block module.

Functions

Namesort descending Description
hook_block_cid_parts_alter Act on block cache ID (cid) parts before the cid is generated.
hook_block_configure Define a configuration form for a block.
hook_block_info Define all blocks provided by the module.
hook_block_info_alter Change block definition before saving to the database.
hook_block_list_alter Act on blocks prior to rendering.
hook_block_save Save the configuration options from hook_block_configure().
hook_block_view Return a rendered or renderable view of a block.
hook_block_view_alter Perform alterations to the content of a block.
hook_block_view_MODULE_DELTA_alter Perform alterations to a specific block.

File

drupal/modules/block/block.api.php
View source
  1. <?php
  2. /**
  3. * @file
  4. * Hooks provided by the Block module.
  5. */
  6. /**
  7. * @addtogroup hooks
  8. * @{
  9. */
  10. /**
  11. * Define all blocks provided by the module.
  12. *
  13. * This hook declares to Drupal what blocks are provided by your module and can
  14. * optionally specify initial block configuration settings.
  15. *
  16. * In hook_block_info(), each block your module provides is given a unique
  17. * identifier referred to as "delta" (the array key in the return value). Delta
  18. * values only need to be unique within your module, and they are used in the
  19. * following ways:
  20. * - Passed into the other block hooks in your module as an argument to identify
  21. * the block being configured or viewed.
  22. * - Used to construct the default HTML ID of "block-MODULE-DELTA" applied to
  23. * each block when it is rendered. This ID may then be used for CSS styling or
  24. * JavaScript programming.
  25. * - Used to define a theming template suggestion of block__MODULE__DELTA, for
  26. * advanced theming possibilities.
  27. * - Used by other modules to identify your block in hook_block_info_alter() and
  28. * other alter hooks.
  29. * The values of delta can be strings or numbers, but because of the uses above
  30. * it is preferable to use descriptive strings whenever possible, and only use a
  31. * numeric identifier if you have to (for instance if your module allows users
  32. * to create several similar blocks that you identify within your module code
  33. * with numeric IDs). The maximum length for delta values is 32 bytes.
  34. *
  35. * @return
  36. * An associative array whose keys define the delta for each block and whose
  37. * values contain the block descriptions. Each block description is itself an
  38. * associative array, with the following key-value pairs:
  39. * - info: (required) The human-readable administrative name of the block.
  40. * This is used to identify the block on administration screens, and is not
  41. * displayed to non-administrative users.
  42. * - cache: (optional) A bitmask describing what kind of caching is
  43. * appropriate for the block. Drupal provides the following bitmask
  44. * constants for defining cache granularity:
  45. * - DRUPAL_CACHE_PER_ROLE (default): The block can change depending on the
  46. * roles the user viewing the page belongs to.
  47. * - DRUPAL_CACHE_PER_USER: The block can change depending on the user
  48. * viewing the page. This setting can be resource-consuming for sites with
  49. * large number of users, and should only be used when
  50. * DRUPAL_CACHE_PER_ROLE is not sufficient.
  51. * - DRUPAL_CACHE_PER_PAGE: The block can change depending on the page being
  52. * viewed.
  53. * - DRUPAL_CACHE_GLOBAL: The block is the same for every user on every page
  54. * where it is visible.
  55. * - DRUPAL_CACHE_CUSTOM: The module implements its own caching system.
  56. * - DRUPAL_NO_CACHE: The block should not get cached.
  57. * - properties: (optional) Array of additional metadata to add to the block.
  58. * Common properties include:
  59. * - administrative: Boolean that categorizes this block as usable in an
  60. * administrative context. This might include blocks that help an
  61. * administrator approve/deny comments, or view recently created user
  62. * accounts.
  63. * - weight: (optional) Initial value for the ordering weight of this block.
  64. * Most modules do not provide an initial value, and any value provided can
  65. * be modified by a user on the block configuration screen.
  66. * - status: (optional) Initial value for block enabled status. (1 = enabled,
  67. * 0 = disabled). Most modules do not provide an initial value, and any
  68. * value provided can be modified by a user on the block configuration
  69. * screen.
  70. * - region: (optional) Initial value for theme region within which this
  71. * block is set. Most modules do not provide an initial value, and any value
  72. * provided can be modified by a user on the block configuration screen.
  73. * Note: If you set a region that isn't available in the currently enabled
  74. * theme, the block will be disabled.
  75. * - visibility: (optional) Initial value for the visibility flag, which tells
  76. * how to interpret the 'pages' value. Possible values are:
  77. * - BLOCK_VISIBILITY_NOTLISTED: Show on all pages except listed pages.
  78. * 'pages' lists the paths where the block should not be shown.
  79. * - BLOCK_VISIBILITY_LISTED: Show only on listed pages. 'pages' lists the
  80. * paths where the block should be shown.
  81. * - BLOCK_VISIBILITY_PHP: Use custom PHP code to determine visibility.
  82. * 'pages' gives the PHP code to use.
  83. * Most modules do not provide an initial value for 'visibility' or 'pages',
  84. * and any value provided can be modified by a user on the block
  85. * configuration screen.
  86. * - pages: (optional) See 'visibility' above. A string that contains one or
  87. * more page paths separated by "\n", "\r", or "\r\n" when 'visibility' is
  88. * set to BLOCK_VISIBILITY_NOTLISTED or BLOCK_VISIBILITY_LISTED (example:
  89. * "<front>\nnode/1"), or custom PHP code when 'visibility' is set to
  90. * BLOCK_VISIBILITY_PHP. Paths may use '*' as a wildcard (matching any
  91. * number of characters); '<front>' designates the site's front page. For
  92. * BLOCK_VISIBILITY_PHP, the PHP code's return value should be TRUE if the
  93. * block is to be made visible or FALSE if the block should not be visible.
  94. *
  95. * For a detailed usage example, see block_example.module.
  96. *
  97. * @see hook_block_configure()
  98. * @see hook_block_save()
  99. * @see hook_block_view()
  100. * @see hook_block_info_alter()
  101. */
  102. function hook_block_info() {
  103. // This example comes from node.module.
  104. $blocks['syndicate'] = array(
  105. 'info' => t('Syndicate'),
  106. 'cache' => DRUPAL_NO_CACHE
  107. );
  108. $blocks['recent'] = array(
  109. 'info' => t('Recent content'),
  110. // DRUPAL_CACHE_PER_ROLE will be assumed.
  111. );
  112. return $blocks;
  113. }
  114. /**
  115. * Change block definition before saving to the database.
  116. *
  117. * @param $blocks
  118. * A multidimensional array of blocks keyed by the defining module and delta;
  119. * the values are blocks returned by hook_block_info(). This hook is fired
  120. * after the blocks are collected from hook_block_info() and the database,
  121. * right before saving back to the database.
  122. * @param $theme
  123. * The theme these blocks belong to.
  124. * @param $code_blocks
  125. * The blocks as defined in hook_block_info() before being overwritten by the
  126. * database data.
  127. *
  128. * @see hook_block_info()
  129. */
  130. function hook_block_info_alter(&$blocks, $theme, $code_blocks) {
  131. // Disable the login block.
  132. $blocks['user']['login']['status'] = 0;
  133. }
  134. /**
  135. * Define a configuration form for a block.
  136. *
  137. * @param $delta
  138. * Which block is being configured. This is a unique identifier for the block
  139. * within the module, defined in hook_block_info().
  140. *
  141. * @return
  142. * A configuration form, if one is needed for your block beyond the standard
  143. * elements that the block module provides (block title, visibility, etc.).
  144. *
  145. * For a detailed usage example, see block_example.module.
  146. *
  147. * @see hook_block_info()
  148. * @see hook_block_save()
  149. */
  150. function hook_block_configure($delta = '') {
  151. // This example comes from node.module.
  152. $form = array();
  153. if ($delta == 'recent') {
  154. $form['node_recent_block_count'] = array(
  155. '#type' => 'select',
  156. '#title' => t('Number of recent content items to display'),
  157. '#default_value' => variable_get('node_recent_block_count', 10),
  158. '#options' => drupal_map_assoc(array(2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 25, 30)),
  159. );
  160. }
  161. return $form;
  162. }
  163. /**
  164. * Save the configuration options from hook_block_configure().
  165. *
  166. * This hook allows you to save the block-specific configuration settings
  167. * defined within your hook_block_configure().
  168. *
  169. * @param $delta
  170. * Which block is being configured. This is a unique identifier for the block
  171. * within the module, defined in hook_block_info().
  172. * @param $edit
  173. * The submitted form data from the configuration form.
  174. *
  175. * For a detailed usage example, see block_example.module.
  176. *
  177. * @see hook_block_configure()
  178. * @see hook_block_info()
  179. */
  180. function hook_block_save($delta = '', $edit = array()) {
  181. // This example comes from node.module.
  182. if ($delta == 'recent') {
  183. variable_set('node_recent_block_count', $edit['node_recent_block_count']);
  184. }
  185. }
  186. /**
  187. * Return a rendered or renderable view of a block.
  188. *
  189. * @param $delta
  190. * Which block to render. This is a unique identifier for the block
  191. * within the module, defined in hook_block_info().
  192. *
  193. * @return
  194. * Either an empty array so the block will not be shown or an array containing
  195. * the following elements:
  196. * - subject: The default localized title of the block. If the block does not
  197. * have a default title, this should be set to NULL.
  198. * - content: The content of the block's body. This may be a renderable array
  199. * (preferable) or a string containing rendered HTML content. If the content
  200. * is empty the block will not be shown.
  201. *
  202. * For a detailed usage example, see block_example.module.
  203. *
  204. * @see hook_block_info()
  205. * @see hook_block_view_alter()
  206. * @see hook_block_view_MODULE_DELTA_alter()
  207. */
  208. function hook_block_view($delta = '') {
  209. // This example is adapted from node.module.
  210. $block = array();
  211. switch ($delta) {
  212. case 'syndicate':
  213. $block['subject'] = t('Syndicate');
  214. $block['content'] = array(
  215. '#theme' => 'feed_icon',
  216. '#url' => 'rss.xml',
  217. '#title' => t('Syndicate'),
  218. );
  219. break;
  220. case 'recent':
  221. if (user_access('access content')) {
  222. $block['subject'] = t('Recent content');
  223. if ($nodes = node_get_recent(variable_get('node_recent_block_count', 10))) {
  224. $block['content'] = array(
  225. '#theme' => 'node_recent_block',
  226. '#nodes' => $nodes,
  227. );
  228. } else {
  229. $block['content'] = t('No content available.');
  230. }
  231. }
  232. break;
  233. }
  234. return $block;
  235. }
  236. /**
  237. * Perform alterations to the content of a block.
  238. *
  239. * This hook allows you to modify any data returned by hook_block_view().
  240. *
  241. * Note that instead of hook_block_view_alter(), which is called for all
  242. * blocks, you can also use hook_block_view_MODULE_DELTA_alter() to alter a
  243. * specific block.
  244. *
  245. * @param $data
  246. * The data as returned from the hook_block_view() implementation of the
  247. * module that defined the block. This could be an empty array or NULL value
  248. * (if the block is empty) or an array containing:
  249. * - subject: The default localized title of the block.
  250. * - content: Either a string or a renderable array representing the content
  251. * of the block. You should check that the content is an array before trying
  252. * to modify parts of the renderable structure.
  253. * @param $block
  254. * The block object, as loaded from the database, having the main properties:
  255. * - module: The name of the module that defined the block.
  256. * - delta: The unique identifier for the block within that module, as defined
  257. * in hook_block_info().
  258. *
  259. * @see hook_block_view_MODULE_DELTA_alter()
  260. * @see hook_block_view()
  261. */
  262. function hook_block_view_alter(&$data, $block) {
  263. // Remove the contextual links on all blocks that provide them.
  264. if (is_array($data['content']) && isset($data['content']['#contextual_links'])) {
  265. unset($data['content']['#contextual_links']);
  266. }
  267. // Add a theme wrapper function defined by the current module to all blocks
  268. // provided by the "somemodule" module.
  269. if (is_array($data['content']) && $block->module == 'somemodule') {
  270. $data['content']['#theme_wrappers'][] = 'mymodule_special_block';
  271. }
  272. }
  273. /**
  274. * Perform alterations to a specific block.
  275. *
  276. * Modules can implement hook_block_view_MODULE_DELTA_alter() to modify a
  277. * specific block, rather than implementing hook_block_view_alter().
  278. *
  279. * @param $data
  280. * The data as returned from the hook_block_view() implementation of the
  281. * module that defined the block. This could be an empty array or NULL value
  282. * (if the block is empty) or an array containing:
  283. * - subject: The localized title of the block.
  284. * - content: Either a string or a renderable array representing the content
  285. * of the block. You should check that the content is an array before trying
  286. * to modify parts of the renderable structure.
  287. * @param $block
  288. * The block object, as loaded from the database, having the main properties:
  289. * - module: The name of the module that defined the block.
  290. * - delta: The unique identifier for the block within that module, as defined
  291. * in hook_block_info().
  292. *
  293. * @see hook_block_view_alter()
  294. * @see hook_block_view()
  295. */
  296. function hook_block_view_MODULE_DELTA_alter(&$data, $block) {
  297. // This code will only run for a specific block. For example, if MODULE_DELTA
  298. // in the function definition above is set to "mymodule_somedelta", the code
  299. // will only run on the "somedelta" block provided by the "mymodule" module.
  300. // Change the title of the "somedelta" block provided by the "mymodule"
  301. // module.
  302. $data['subject'] = t('New title of the block');
  303. }
  304. /**
  305. * Act on blocks prior to rendering.
  306. *
  307. * This hook allows you to add, remove or modify blocks in the block list. The
  308. * block list contains the block definitions, not the rendered blocks. The
  309. * blocks are rendered after the modules have had a chance to manipulate the
  310. * block list.
  311. *
  312. * You can also set $block->content here, which will override the content of the
  313. * block and prevent hook_block_view() from running.
  314. *
  315. * @param $blocks
  316. * An array of $blocks, keyed by the block ID.
  317. */
  318. function hook_block_list_alter(&$blocks) {
  319. global $language, $theme_key;
  320. // This example shows how to achieve language specific visibility setting for
  321. // blocks.
  322. $result = db_query('SELECT module, delta, language FROM {my_table}');
  323. $block_languages = array();
  324. foreach ($result as $record) {
  325. $block_languages[$record->module][$record->delta][$record->language] = TRUE;
  326. }
  327. foreach ($blocks as $key => $block) {
  328. // Any module using this alter should inspect the data before changing it,
  329. // to ensure it is what they expect.
  330. if (!isset($block->theme) || !isset($block->status) || $block->theme != $theme_key || $block->status != 1) {
  331. // This block was added by a contrib module, leave it in the list.
  332. continue;
  333. }
  334. if (!isset($block_languages[$block->module][$block->delta])) {
  335. // No language setting for this block, leave it in the list.
  336. continue;
  337. }
  338. if (!isset($block_languages[$block->module][$block->delta][$language->language])) {
  339. // This block should not be displayed with the active language, remove
  340. // from the list.
  341. unset($blocks[$key]);
  342. }
  343. }
  344. }
  345. /**
  346. * Act on block cache ID (cid) parts before the cid is generated.
  347. *
  348. * This hook allows you to add, remove or modify the custom keys used to
  349. * generate a block cache ID (by default, these keys are set to the block
  350. * module and delta). These keys will be combined with the standard ones
  351. * provided by drupal_render_cid_parts() to generate the final block cache ID.
  352. *
  353. * To change the cache granularity used by drupal_render_cid_parts(), this hook
  354. * cannot be used; instead, set the 'cache' key in the block's definition in
  355. * hook_block_info().
  356. *
  357. * @params $cid_parts
  358. * An array of elements used to build the cid.
  359. * @param $block
  360. * The block object being acted on.
  361. *
  362. * @see _block_get_cache_id()
  363. */
  364. function hook_block_cid_parts_alter(&$cid_parts, $block) {
  365. global $user;
  366. // This example shows how to cache a block based on the user's timezone.
  367. $cid_parts[] = $user->timezone;
  368. }
  369. /**
  370. * @} End of "addtogroup hooks".
  371. */