function hook_block

You are here

4.6 core.php hook_block($op = 'list', $delta = 0, $edit = array())
4.7 core.php hook_block($op = 'list', $delta = 0, $edit = array())
5 core.php hook_block($op = 'list', $delta = 0, $edit = array())
6 core.php hook_block($op = 'list', $delta = 0, $edit = array())

Declare a block or set of blocks.

Any module can export a block (or blocks) to be displayed by defining the _block hook. This hook is called by theme.inc to display a block, and also by block.module to procure the list of available blocks.

As of 4.7, all block properties (except theme) can be set in hook_block's 'view' operation. You can give your blocks an explicit weight, enable them, limit them to given pages, etc. These settings will be registered when the block is first loaded at admin/block, and from there can be changed manually via block administration.

Note that if you set a region that isn't available in a given theme, the block will be registered instead to that theme's default region (the first item in the _regions array).

Parameters

$op: What kind of information to retrieve about the block or blocks. Possible values:

  • 'list': A list of all blocks defined by the module.
  • 'configure': A configuration form.
  • 'save': Save the configuration options.
  • 'view': Information about a particular block and default settings.

$delta: Which block to return (not applicable if $op is 'list'). Although it is most commonly an integer starting at 0, this is not mandatory. For instance, aggregator.module uses string values for $delta

$edit: If $op is 'save', the submitted form data from the configuration form.

Return value

If $op is 'list', return an array of arrays, each of which must define an 'info' element describing the block. If $op is 'configure', optionally return a string containing the configuration form. If $op is 'save', return nothing, If $op is 'view', return an array which must define a 'subject' element and a 'content' element defining the block indexed by $delta.

The functions mymodule_display_block_1 and 2, as used in the example, should of course be defined somewhere in your module and return the content you want to display to your users. If the "content" element is empty, no block will be displayed even if "subject" is present.

After completing your blocks, do not forget to enable them in the block admin menu.

For a detailed usage example, see block_example.module.

Related topics

19 functions implement hook_block()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

aggregator_block in modules/aggregator.module
Implementation of hook_block().
archive_block in modules/archive.module
Implementation of hook_block().
block_block in modules/block.module
Implementation of hook_block().
block_example_block in developer/examples/block_example.module
Implementation of hook_block().
blog_block in modules/blog.module
Implementation of hook_block().

... See full list

5 invocations of hook_block()
block_admin_configure in modules/block.module
Menu callback; displays the block configuration form.
block_admin_configure_submit in modules/block.module
block_list in modules/block.module
Return all blocks in the specified region for the current user.
block_user in modules/block.module
Implementation of hook_user().
_block_rehash in modules/block.module
Update the 'blocks' DB table with the blocks currently exported by modules.

File

developer/hooks/core.php, line 64
These are the hooks that are invoked by the Drupal core.

Code

function hook_block($op = 'list', $delta = 0, $edit = array()) {
  if ($op == 'list') {
    $blocks[0] = array(
      'info' => t('Mymodule block #1 shows ...'),
      'weight' => 0,
      'enabled' => 1,
      'region' => 'left',
    );
    $blocks[1] = array(
      'info' => t('Mymodule block #2 describes ...'),
      'weight' => 0,
      'enabled' => 0,
      'region' => 'right',
    );
    return $blocks;
  }
  else if ($op == 'configure' && $delta == 0) {
    $form['items'] = array(
      '#type' => 'select',
      '#title' => t('Number of items'),
      '#default_value' => variable_get('mymodule_block_items', 0),
      '#options' => array('1', '2', '3'),
    );
    return $form;
  }
  else if ($op == 'save' && $delta == 0) {
    variable_set('mymodule_block_items', $edit['items']);
  }
  else if ($op == 'view') {
    switch ($delta) {
      case 0:
        $block = array(
          'subject' => t('Title of block #1'),
          'content' => mymodule_display_block_1(),
        );
        break;
      case 1:
        $block = array(
          'subject' => t('Title of block #2'),
          'content' => mymodule_display_block_2(),
        );
        break;
    }
    return $block;
  }
}