Block API - Developers information

Here you will find information on how to hook in to the Block API in your module to provide a custom block type.

Available hooks

hook_block_api_info() *deprecated*

Replaced with hook_block_api_block_types() as of beta2

Define the name and options of custom block types to be made available to the user.

Return a keyed array with the following keys: title, description, storage.

Where storage can be either BLOCK_API_STORAGE_DATABASE or BLOCK_API_STORAGE_OWN where the later would require you to define your own storage of your data. BLOCK_API_STORAGE_DATABASE will store the result of all the form fields in a serialized array in the block_api table.

Example:

<?phpfunction html_block_block_api_info() {
  $types['html'] = array(
    'title' => t('HTML Block'),
    'description' => t('Create a basic block containing HTML code.'),
    'storage' => BLOCK_API_STORAGE_DATABASE,
  );
  return $types;
}?>

hook_block_api_block_types()

Define the name and options of custom block types to be made available to the user.

Return a keyed array with the following keys: title, description, storage.

Where storage can be either BLOCK_API_STORAGE_DATABASE or BLOCK_API_STORAGE_OWN where the later would require you to define your own storage of your data. BLOCK_API_STORAGE_DATABASE will store the result of all the form fields in a serialized array in the block_api table.

Example:

<?phpfunction html_block_block_api_block_types() {
  $types['html'] = array(
    'title' => t('HTML Block'),
    'description' => t('Create a basic block containing HTML code.'),
    'storage' => BLOCK_API_STORAGE_DATABASE,
  );
  return $types;
}?>

hook_block_api_form($config, $edit)

Define the form layout to be displayed on the configuration screen of the block.

Params:

$config - A keyed array of details of the current block being modified. Includes delta, module (the module which implemented the block), block_type (as defined in hook_block_api_info()), admin_title, storage (the storage method as defined in hook_block_api_info()) and settings (a keyed array of options defined by hook_block_api_form()).

$edit - Submitted form values.

Example:

<?phpfunction html_block_block_api_form($config, $edit) {
  if ($config['block_type'] == 'html') {
    $form['block_body']['body'] = array(
      '#type' => 'textarea',
      '#title' => t('Block body'),
      '#description' => t('The content of the block as shown to the user.'),
      '#rows' => 15,
      '#required' => TRUE,
      '#default_value' => $config['settings']['body'],
    );
    if (!isset($config['settings']['format'])) {
      $config['settings']['format'] = FILTER_FORMAT_DEFAULT;
    }
    $form['block_body']['format'] = filter_form($config['settings']['format']);
  }
  return $form;
}?>

hook_block_api_view($config) *deprecated*

Replaced with hook_block_api_display() as of beta2

Sets the output of the block when viewed.

Params:

$config - A keyed array of details of the current block being modified. Includes delta, module (the module which implemented the block), block_type (as defined in hook_block_api_info()), admin_title, storage (the storage method as defined in hook_block_api_info()) and settings (a keyed array of options defined by hook_block_api_form()).

Example:

<?phpfunction html_block_block_api_view($config) {
  if ($config['block_type'] == 'html') {
    $output .= $config['settings']['body'];
  }
  return array('content' => $output);
}?>

hook_block_api_display($config)

Sets the output of the block when viewed.

Params:

$config - A keyed array of details of the current block being modified. Includes delta, module (the module which implemented the block), block_type (as defined in hook_block_api_info()), admin_title, storage (the storage method as defined in hook_block_api_block_types()) and settings (a keyed array of options defined by hook_block_api_form()).

Example:

<?phpfunction html_block_block_api_display($config) {
  if ($config['block_type'] == 'html') {
    $output .= $config['settings']['body'];
  }
  return array('content' => $output);
}?>

hook_block_api_save($config, $edit)

Allows you to save form values when submitting the block edit page. If $config['storage'] is set to BLOCK_API_STORAGE_DATABASE or 0, this isn't required.

Params:

$config - A keyed array of details of the current block being modified. Includes delta, module (the module which implemented the block), block_type (as defined in hook_block_api_info()), admin_title, storage (the storage method as defined in hook_block_api_info()) and settings (a keyed array of options defined by hook_block_api_form()).

$edit - Submitted form values.

hook_block_api_delete($block_type, $delta)

Run when a block defined by the module is deleted. When storage is set to BLOCK_API_STORAGE_DATABASE or 0, this isn't usually required.

Implementation

In Drupal 6 beta 1 only

To implement these hooks, you also need to add the following to hook_block().

<?phpfunction html_block_block($op = 'list', $delta = NULL, $edit = array()) {
  $function = 'block_api_block_'. $op;
  return $function('html_block', $delta, $edit);
}?>

If you wish to provide a set block as well as providing custom blocks you can do the following:

<?phpfunction html_block_block($op = 'list', $delta = NULL, $edit = array()) {
  if ($delta == 'html_block_set_block_1') {
    /** Normal block code **/
  }
  else {
    $function = 'block_api_block_'. $op;
    return $function('html_block', $delta, $edit);
  }
}?>

From Drupal 6 beta 2 and Drupal 7 beta 1

You just need to define hook_block_api_block_types().

Dependencies

In your modules .info file, you will want to add the following:

<?phpdependencies[] = block_api?>

Comments

New Drupal modu...

Wed, 2010-06-30 14:25

[...] information on how to use the module is available on the Block API Developer information page. « New [...]