block.api.php 14.2 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13
<?php

/**
 * @file
 * Hooks provided by the Block module.
 */

/**
 * @addtogroup hooks
 * @{
 */

/**
14
 * Define all blocks provided by the module.
15
 *
16 17 18 19 20 21 22
 * This hook declares to Drupal what blocks are provided by your module and can
 * optionally specify initial block configuration settings.
 *
 * In hook_block_info(), each block your module provides is given a unique
 * identifier referred to as "delta" (the array key in the return value). Delta
 * values only need to be unique within your module, and they are used in the
 * following ways:
23 24
 * - Passed into the other block hooks in your module as an argument to identify
 *   the block being configured or viewed.
25
 * - Used to construct the default HTML ID of "block-MODULE-DELTA" applied to
26 27
 *   each block when it is rendered. This ID may then be used for CSS styling or
 *   JavaScript programming.
28 29 30 31 32 33 34 35
 * - Used to define a theming template suggestion of block__MODULE__DELTA, for
 *   advanced theming possibilities.
 * - Used by other modules to identify your block in hook_block_info_alter() and
 *   other alter hooks.
 * The values of delta can be strings or numbers, but because of the uses above
 * it is preferable to use descriptive strings whenever possible, and only use a
 * numeric identifier if you have to (for instance if your module allows users
 * to create several similar blocks that you identify within your module code
36
 * with numeric IDs). The maximum length for delta values is 32 bytes.
37 38
 *
 * @return
39 40 41
 *   An associative array whose keys define the delta for each block and whose
 *   values contain the block descriptions. Each block description is itself an
 *   associative array, with the following key-value pairs:
42
 *   - info: (required) The human-readable administrative name of the block.
43 44
 *     This is used to identify the block on administration screens, and
 *     is not displayed to non-administrative users.
45
 *   - cache: (optional) A bitmask describing what kind of caching is
46 47
 *     appropriate for the block. Drupal provides the following bitmask
 *     constants for defining cache granularity:
48
 *     - DRUPAL_CACHE_PER_ROLE (default): The block can change depending on the
49
 *       roles the user viewing the page belongs to.
50
 *     - DRUPAL_CACHE_PER_USER: The block can change depending on the user
51 52
 *       viewing the page. This setting can be resource-consuming for sites
 *       with large number of users, and should only be used when
53 54
 *       DRUPAL_CACHE_PER_ROLE is not sufficient.
 *     - DRUPAL_CACHE_PER_PAGE: The block can change depending on the page
55
 *       being viewed.
56
 *     - DRUPAL_CACHE_GLOBAL: The block is the same for every user on every
57
 *       page where it is visible.
58
 *     - DRUPAL_NO_CACHE: The block should not get cached.
59 60 61 62 63 64 65
 *   - properties: (optional) Array of additional metadata to add to the block.
 *     Common properties include:
 *     - administrative: Boolean that categorizes this block as usable in an
 *       administrative context. This might include blocks that help an
 *       administrator approve/deny comments, or view recently created user
 *       accounts.
 *   - weight: (optional) Initial value for the ordering weight of this block.
66 67
 *     Most modules do not provide an initial value, and any value provided can
 *     be modified by a user on the block configuration screen.
68 69 70
 *   - status: (optional) Initial value for block enabled status. (1 = enabled,
 *     0 = disabled). An initial value for 'region' is required for 'status' to
 *     take effect.
71 72
 *     Most modules do not provide an initial value, and any value provided can
 *     be modified by a user on the block configuration screen.
73 74 75 76
 *   - region: (optional) Initial value for theme region within which this block
 *     is set. If the specified region is not available in a theme, the block
 *     will be disabled. The initial value for 'status' must be enabled or the
 *     initial region value is ignored.
77 78
 *     Most modules do not provide an initial value, and any value provided can
 *     be modified by a user on the block configuration screen.
79 80
 *   - visibility: (optional) Initial value for the visibility flag, which tells
 *     how to interpret the 'pages' value. Possible values are:
81 82 83 84 85 86
 *     - BLOCK_VISIBILITY_NOTLISTED: Show on all pages except listed pages.
 *       'pages' lists the paths where the block should not be shown.
 *     - BLOCK_VISIBILITY_LISTED: Show only on listed pages. 'pages' lists the
 *       paths where the block should be shown.
 *     - BLOCK_VISIBILITY_PHP: Use custom PHP code to determine visibility.
 *       'pages' gives the PHP code to use.
87 88 89
 *     Most modules do not provide an initial value for 'visibility' or 'pages',
 *     and any value provided can be modified by a user on the block
 *     configuration screen.
90 91 92 93 94 95 96 97
 *   - pages: (optional) See 'visibility' above. A string that contains one or
 *     more page paths separated by '\n', '\r', or '\r\n' when 'visibility' is
 *     set to BLOCK_VISIBILITY_NOTLISTED or BLOCK_VISIBILITY_LISTED, or custom
 *     PHP code when 'visibility' is set to BLOCK_VISIBILITY_PHP. Paths may use
 *     '*' as a wildcard (matching any number of characters); '<front>'
 *     designates the site's front page. For BLOCK_VISIBILITY_PHP, the PHP
 *     code's return value should be TRUE if the block is to be made visible or
 *     FALSE if the block should not be visible.
98 99
 *
 * For a detailed usage example, see block_example.module.
100 101 102 103 104
 *
 * @see hook_block_configure()
 * @see hook_block_save()
 * @see hook_block_view()
 * @see hook_block_info_alter()
105
 */
106
function hook_block_info() {
107 108 109 110
  // This example comes from node.module.
  $blocks['syndicate'] = array(
    'info' => t('Syndicate'),
    'cache' => DRUPAL_NO_CACHE
111
  );
112

113 114 115
  $blocks['recent'] = array(
    'info' => t('Recent content'),
    // DRUPAL_CACHE_PER_ROLE will be assumed.
116
  );
117

118 119 120
  return $blocks;
}

121 122 123 124
/**
 * Change block definition before saving to the database.
 *
 * @param $blocks
125 126
 *   A multidimensional array of blocks keyed by the defining module and delta;
 *   the values are blocks returned by hook_block_info(). This hook is fired
127 128 129 130 131
 *   after the blocks are collected from hook_block_info() and the database,
 *   right before saving back to the database.
 * @param $theme
 *   The theme these blocks belong to.
 * @param $code_blocks
132
 *   The blocks as defined in hook_block_info() before being overwritten by the
133
 *   database data.
134 135
 *
 * @see hook_block_info()
136 137 138 139 140 141
 */
function hook_block_info_alter(&$blocks, $theme, $code_blocks) {
  // Disable the login block.
  $blocks['user']['login']['status'] = 0;
}

142
/**
143
 * Define a configuration form for a block.
144 145
 *
 * @param $delta
146 147 148
 *   Which block is being configured. This is a unique identifier for the block
 *   within the module, defined in hook_block_info().
 *
149
 * @return
150 151
 *   A configuration form, if one is needed for your block beyond the standard
 *   elements that the block module provides (block title, visibility, etc.).
152 153
 *
 * For a detailed usage example, see block_example.module.
154 155 156
 *
 * @see hook_block_info()
 * @see hook_block_save()
157 158
 */
function hook_block_configure($delta = '') {
159 160 161 162
  // This example comes from node.module.
  $form = array();
  if ($delta == 'recent') {
    $form['node_recent_block_count'] = array(
163
      '#type' => 'select',
164 165 166
      '#title' => t('Number of recent content items to display'),
      '#default_value' => variable_get('node_recent_block_count', 10),
      '#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)),
167 168
    );
  }
169
  return $form;
170 171 172
}

/**
173 174 175 176
 * Save the configuration options from hook_block_configure().
 *
 * This hook allows you to save the block-specific configuration settings
 * defined within your hook_block_configure().
177 178
 *
 * @param $delta
179 180
 *   Which block is being configured. This is a unique identifier for the block
 *   within the module, defined in hook_block_info().
181 182 183 184
 * @param $edit
 *   The submitted form data from the configuration form.
 *
 * For a detailed usage example, see block_example.module.
185 186 187
 *
 * @see hook_block_configure()
 * @see hook_block_info()
188 189
 */
function hook_block_save($delta = '', $edit = array()) {
190 191 192
  // This example comes from node.module.
  if ($delta == 'recent') {
    variable_set('node_recent_block_count', $edit['node_recent_block_count']);
193
  }
194 195 196
}

/**
197
 * Return a rendered or renderable view of a block.
198 199
 *
 * @param $delta
200 201
 *   Which block to render. This is a unique identifier for the block
 *   within the module, defined in hook_block_info().
202
 *
203
 * @return
204 205 206 207 208
 *   An array containing the following elements:
 *   - subject: The default localized title of the block. If the block does not
 *     have a default title, this should be set to NULL.
 *   - content: The content of the block's body. This may be a renderable array
 *     (preferable) or a string containing rendered HTML content.
209 210
 *
 * For a detailed usage example, see block_example.module.
211 212 213 214
 *
 * @see hook_block_info()
 * @see hook_block_view_alter()
 * @see hook_block_view_MODULE_DELTA_alter()
215 216
 */
function hook_block_view($delta = '') {
217
  // This example is adapted from node.module.
218 219
  $block = array();

220
  switch ($delta) {
221 222
    case 'syndicate':
      $block['subject'] = t('Syndicate');
223 224 225 226 227
      $block['content'] = array(
        '#theme' => 'feed_icon',
        '#url' => 'rss.xml',
        '#title' => t('Syndicate'),
      );
228
      break;
229

230 231 232 233
    case 'recent':
      if (user_access('access content')) {
        $block['subject'] = t('Recent content');
        if ($nodes = node_get_recent(variable_get('node_recent_block_count', 10))) {
234 235 236 237
          $block['content'] = array(
            '#theme' => 'node_recent_block',
            '#nodes' => $nodes,
          );
238 239 240 241
        } else {
          $block['content'] = t('No content available.');
        }
      }
242
      break;
243
  }
244
  return $block;
245 246
}

247 248 249 250 251 252 253 254 255 256 257 258
/**
 * Perform alterations to the content of a block.
 *
 * This hook allows you to modify any data returned by hook_block_view().
 *
 * Note that instead of hook_block_view_alter(), which is called for all
 * blocks, you can also use hook_block_view_MODULE_DELTA_alter() to alter a
 * specific block.
 *
 * @param $data
 *   An array of data, as returned from the hook_block_view() implementation of
 *   the module that defined the block:
259
 *   - subject: The default localized title of the block.
260 261 262 263 264 265
 *   - content: Either a string or a renderable array representing the content
 *     of the block. You should check that the content is an array before trying
 *     to modify parts of the renderable structure.
 * @param $block
 *   The block object, as loaded from the database, having the main properties:
 *   - module: The name of the module that defined the block.
266 267
 *   - delta: The unique identifier for the block within that module, as defined
 *     in hook_block_info().
268
 *
269
 * @see hook_block_view_MODULE_DELTA_alter()
270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299
 * @see hook_block_view()
 */
function hook_block_view_alter(&$data, $block) {
  // Remove the contextual links on all blocks that provide them.
  if (is_array($data['content']) && isset($data['content']['#contextual_links'])) {
    unset($data['content']['#contextual_links']);
  }
  // Add a theme wrapper function defined by the current module to all blocks
  // provided by the "somemodule" module.
  if (is_array($data['content']) && $block->module == 'somemodule') {
    $data['content']['#theme_wrappers'][] = 'mymodule_special_block';
  }
}

/**
 * Perform alterations to a specific block.
 *
 * Modules can implement hook_block_view_MODULE_DELTA_alter() to modify a
 * specific block, rather than implementing hook_block_view_alter().
 *
 * @param $data
 *   An array of data, as returned from the hook_block_view() implementation of
 *   the module that defined the block:
 *   - subject: The localized title of the block.
 *   - content: Either a string or a renderable array representing the content
 *     of the block. You should check that the content is an array before trying
 *     to modify parts of the renderable structure.
 * @param $block
 *   The block object, as loaded from the database, having the main properties:
 *   - module: The name of the module that defined the block.
300 301
 *   - delta: The unique identifier for the block within that module, as defined
 *     in hook_block_info().
302 303 304 305 306 307 308 309 310 311 312 313 314 315
 *
 * @see hook_block_view_alter()
 * @see hook_block_view()
 */
function hook_block_view_MODULE_DELTA_alter(&$data, $block) {
  // This code will only run for a specific block. For example, if MODULE_DELTA
  // in the function definition above is set to "mymodule_somedelta", the code
  // will only run on the "somedelta" block provided by the "mymodule" module.

  // Change the title of the "somedelta" block provided by the "mymodule"
  // module.
  $data['subject'] = t('New title of the block');
}

316 317 318 319
/**
 * Act on blocks prior to rendering.
 *
 * This hook allows you to add, remove or modify blocks in the block list. The
320 321 322
 * block list contains the block definitions, not the rendered blocks. The
 * blocks are rendered after the modules have had a chance to manipulate the
 * block list.
323
 *
324 325
 * You can also set $block->content here, which will override the content of the
 * block and prevent hook_block_view() from running.
326
 *
327 328
 * @param $blocks
 *   An array of $blocks, keyed by the block ID.
329
 */
330
function hook_block_list_alter(&$blocks) {
331
  global $language_interface, $theme_key;
332

333 334 335
  // This example shows how to achieve language specific visibility setting for
  // blocks.

336 337 338 339 340 341 342 343 344
  $result = db_query('SELECT module, delta, language FROM {my_table}');
  $block_languages = array();
  foreach ($result as $record) {
    $block_languages[$record->module][$record->delta][$record->language] = TRUE;
  }

  foreach ($blocks as $key => $block) {
    // Any module using this alter should inspect the data before changing it,
    // to ensure it is what they expect.
345
    if (!isset($block->theme) || !isset($block->status) || $block->theme != $theme_key || $block->status != 1) {
346 347 348 349 350 351 352 353 354
      // This block was added by a contrib module, leave it in the list.
      continue;
    }

    if (!isset($block_languages[$block->module][$block->delta])) {
      // No language setting for this block, leave it in the list.
      continue;
    }

355
    if (!isset($block_languages[$block->module][$block->delta][$language_interface->language])) {
356 357 358 359 360 361 362
      // This block should not be displayed with the active language, remove
      // from the list.
      unset($blocks[$key]);
    }
  }
}

363 364 365
/**
 * @} End of "addtogroup hooks".
 */