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

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