1. 8.x-1.x block_example/block_example.module
  2. 6.x-1.x block_example/block_example.module
  3. 7.x-1.x block_example/block_example.module

Module file for block_example.

File

block_example/block_example.module
View source
  1. <?php
  2. /**
  3. * @file
  4. * Module file for block_example.
  5. */
  6. /**
  7. * @defgroup block_example Example: Block
  8. * @ingroup examples
  9. * @{
  10. * Demonstrates code creation of blocks.
  11. *
  12. * This is an example outlining how a module can define blocks that can be
  13. * displayed on various pages of a site, or how to alter blocks provided by
  14. * other modules.
  15. */
  16. /**
  17. * Implements hook_menu().
  18. *
  19. * Provides a default page to explain what this module does.
  20. */
  21. function block_example_menu() {
  22. $items['examples/block_example'] = array(
  23. 'page callback' => 'block_example_page',
  24. 'access callback' => TRUE,
  25. 'title' => 'Block Example',
  26. );
  27. return $items;
  28. }
  29. /**
  30. * Simple page function to explain what the block example is about.
  31. */
  32. function block_example_page() {
  33. $page = array(
  34. '#type' => 'markup',
  35. '#markup' => t('The Block Example provides three sample blocks which demonstrate the various block APIs. To experiment with the blocks, enable and configure them on <a href="@url">the block admin page</a>.', array('@url' => url('admin/structure/block'))),
  36. );
  37. return $page;
  38. }
  39. /**
  40. * Implements hook_block_info().
  41. *
  42. * This hook declares what blocks are provided by the module.
  43. */
  44. function block_example_block_info() {
  45. // This hook returns an array, each component of which is an array of block
  46. // information. The array keys are the 'delta' values used in other block
  47. // hooks.
  48. //
  49. // The required block information is a block description, which is shown
  50. // to the site administrator in the list of possible blocks. You can also
  51. // provide initial settings for block weight, status, etc.
  52. //
  53. // Many options are defined in hook_block_info():
  54. $blocks['example_configurable_text'] = array(
  55. // info: The name of the block.
  56. 'info' => t('Example: configurable text string'),
  57. // Block caching options (per role, per user, etc.)
  58. // DRUPAL_CACHE_PER_ROLE is the default.
  59. 'cache' => DRUPAL_CACHE_PER_ROLE,
  60. );
  61. // This sample shows how to provide default settings. In this case we'll
  62. // enable the block in the first sidebar and make it visible only on
  63. // 'node/*' pages. See the hook_block_info() documentation for these.
  64. $blocks['example_empty'] = array(
  65. 'info' => t('Example: empty block'),
  66. 'status' => TRUE,
  67. 'region' => 'sidebar_first',
  68. 'visibility' => BLOCK_VISIBILITY_LISTED,
  69. 'pages' => 'node/*',
  70. );
  71. $blocks['example_uppercase'] = array(
  72. // info: The name of the block.
  73. 'info' => t('Example: uppercase this please'),
  74. 'status' => TRUE,
  75. 'region' => 'sidebar_first',
  76. );
  77. return $blocks;
  78. }
  79. /**
  80. * Implements hook_block_configure().
  81. *
  82. * This hook declares configuration options for blocks provided by this module.
  83. */
  84. function block_example_block_configure($delta = '') {
  85. $form = array();
  86. // The $delta parameter tells us which block is being configured.
  87. // In this example, we'll allow the administrator to customize
  88. // the text of the 'configurable text string' block defined in this module.
  89. if ($delta == 'example_configurable_text') {
  90. // All we need to provide is the specific configuration options for our
  91. // block. Drupal will take care of the standard block configuration options
  92. // (block title, page visibility, etc.) and the save button.
  93. $form['block_example_string'] = array(
  94. '#type' => 'textfield',
  95. '#title' => t('Block contents'),
  96. '#size' => 60,
  97. '#description' => t('This text will appear in the example block.'),
  98. '#default_value' => variable_get('block_example_string', t('Some example content.')),
  99. );
  100. }
  101. return $form;
  102. }
  103. /**
  104. * Implements hook_block_save().
  105. *
  106. * This hook declares how the configured options for a block
  107. * provided by this module are saved.
  108. */
  109. function block_example_block_save($delta = '', $edit = array()) {
  110. // We need to save settings from the configuration form.
  111. // We need to check $delta to make sure we are saving the right block.
  112. if ($delta == 'example_configurable_text') {
  113. // Have Drupal save the string to the database.
  114. variable_set('block_example_string', $edit['block_example_string']);
  115. }
  116. }
  117. /**
  118. * Implements hook_block_view().
  119. *
  120. * This hook generates the contents of the blocks themselves.
  121. */
  122. function block_example_block_view($delta = '') {
  123. // The $delta parameter tells us which block is being requested.
  124. switch ($delta) {
  125. case 'example_configurable_text':
  126. // The subject is displayed at the top of the block. Note that it
  127. // should be passed through t() for translation. The title configured
  128. // for the block using Drupal UI supercedes this one.
  129. $block['subject'] = t('Title of first block (example_configurable_text)');
  130. // The content of the block is typically generated by calling a custom
  131. // function.
  132. $block['content'] = block_example_contents($delta);
  133. break;
  134. case 'example_empty':
  135. $block['subject'] = t('Title of second block (example_empty)');
  136. $block['content'] = block_example_contents($delta);
  137. break;
  138. case 'example_uppercase':
  139. $block['subject'] = t("uppercase this please");
  140. $block['content'] = t("This block's title will be changed to uppercase. Any other block with 'uppercase' in the subject or title will also be altered. If you change this block's title through the UI to omit the word 'uppercase', it will still be altered to uppercase as the subject key has not been changed.");
  141. break;
  142. }
  143. return $block;
  144. }
  145. /**
  146. * A module-defined block content function.
  147. */
  148. function block_example_contents($which_block) {
  149. switch ($which_block) {
  150. case 'example_configurable_text':
  151. // Modules would typically perform some database queries to fetch the
  152. // content for their blocks. Here, we'll just use the variable set in the
  153. // block configuration or, if none has set, a default value.
  154. // Block content can be returned in two formats: renderable arrays
  155. // (as here) are preferred though a simple string will work as well.
  156. // Block content created through the UI defaults to a string.
  157. $result = array(
  158. '#markup' => variable_get('block_example_string',
  159. t('A default value. This block was created at %time',
  160. array('%time' => date('c'))
  161. )
  162. ),
  163. );
  164. return $result;
  165. case 'example_empty':
  166. // It is possible that a block not have any content, since it is
  167. // probably dynamically constructed. In this case, Drupal will not display
  168. // the block at all. This block will not be displayed.
  169. return;
  170. }
  171. }
  172. /*
  173. * The following hooks can be used to alter blocks
  174. * provided by your own or other modules.
  175. */
  176. /**
  177. * Implements hook_block_list_alter().
  178. *
  179. * This hook allows you to add, remove or modify blocks in the block list. The
  180. * block list contains the block definitions. This example requires
  181. * search module and the search block enabled
  182. * to see how this hook implementation works.
  183. *
  184. * You may also be interested in hook_block_info_alter(), which allows changes
  185. * to the behavior of blocks.
  186. */
  187. function block_example_block_list_alter(&$blocks) {
  188. // We are going to make the search block sticky on bottom of regions. For
  189. // this example, we will modify the block list and append the search block at
  190. // the end of the list, so even if the administrator configures the block to
  191. // be on the top of the region, it will demote to bottom again.
  192. foreach ($blocks as $bid => $block) {
  193. if (($block->module == 'search') && ($block->delta == 'form')) {
  194. // Remove the block from the list and append to the end.
  195. unset($blocks[$bid]);
  196. $blocks[$bid] = $block;
  197. break;
  198. }
  199. }
  200. }
  201. /**
  202. * Implements hook_block_view_alter().
  203. *
  204. * This hook allows you to modify the output of any block in the system.
  205. *
  206. * In addition, instead of hook_block_view_alter(), which is called for all
  207. * blocks, you can also use hook_block_view_MODULE_DELTA_alter() to alter a
  208. * specific block. To change only our block using
  209. * hook_block_view_MODULE_DELTA_alter, we would use the function:
  210. * block_example_block_view_block_example_example_configurable_text_alter()
  211. *
  212. * We are going to uppercase the subject (the title of the block as shown to the
  213. * user) of any block if the string "uppercase" appears in the block title or
  214. * subject. Default block titles are set programmatically in the subject key;
  215. * titles created through the UI are saved in the title key. This module creates
  216. * an example block to demonstrate this effect (default title set
  217. * programmatically as subject). You can also demonstrate the effect of this
  218. * hook by creating a new block whose title has the string 'uppercase' in it
  219. * (set as title through the UI).
  220. */
  221. function block_example_block_view_alter(&$data, $block) {
  222. // We'll search for the string 'uppercase'.
  223. if ((!empty($block->title) && stristr($block->title, 'uppercase')) || (!empty($data['subject']) && stristr($data['subject'], 'uppercase'))) {
  224. // This will uppercase the default title.
  225. $data['subject'] = isset($data['subject']) ? drupal_strtoupper($data['subject']) : '';
  226. // This will uppercase a title set in the UI.
  227. $block->title = isset($block->title) ? drupal_strtoupper($block->title) : '';
  228. }
  229. }
  230. /**
  231. * @} End of "defgroup block_example".
  232. */

Functions

Namesort descending Description
block_example_block_configure Implements hook_block_configure().
block_example_block_info Implements hook_block_info().
block_example_block_list_alter Implements hook_block_list_alter().
block_example_block_save Implements hook_block_save().
block_example_block_view Implements hook_block_view().
block_example_block_view_alter Implements hook_block_view_alter().
block_example_contents A module-defined block content function.
block_example_menu Implements hook_menu().
block_example_page Simple page function to explain what the block example is about.