1 layout.api.php hook_block_info()

Defines to Backdrop what blocks are provided by your module.

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:

  • Passed into the other block hooks in your module as an argument to identify the block being configured or viewed.
  • Used to construct the default HTML ID of "block-MODULE-DELTA" applied to each block when it is rendered. This ID may then be used for CSS styling or JavaScript programming.
  • Used to define a theme template suggestion of block__MODULE__DELTA, for advanced theme 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 with numeric IDs). The maximum length for delta values is 32 bytes.

Return value

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:

  • info: (required) The human-readable administrative name of the block. This is used to identify the block on administration screens, and is not displayed to non-administrative users.
  • description: (optional) A human-readable administrative description of the block. Although intended to be longer than "info", it should still be no longer than a short sentence or two.
  • required contexts: (optional) An array of contexts that this block requires to display. These contexts are keyed by their internal name that this block will receive as the key in the $context parameter of hook_block_view(). The value of each item should be the type of context, as listed by hook_layout_context_info().
  • class: (optional) A class that provides the settings form, save routine, and display of this block. If specified, the class will be used instead of the hooks for hook_block_configure(), hook_block_save(), and hook_block_view(). This class should be a sub-class of the Block class.

For a detailed usage example, see block_example.module.

See also

hook_block_configure()

hook_block_save()

hook_block_view()

hook_block_info_alter()

Related topics

Hooks Allow modules to interact with the Backdrop core.

File

core/modules/layout/layout.api.php, line 513
Describe hooks provided by the Layout module.

Code

function hook_block_info() {
  $blocks['syndicate'] = array(
    'info' => t('Syndicate'),
    'description' => t('An RSS icon linking to the feed for the current page (if any).'),
  );

  $blocks['recent'] = array(
    'info' => t('Recent content'),
    'description' => t('A list of recently published content.'),
  );

  $blocks['author_picture'] = array(
    'info' => t('Author picture'),
    'description' => t('The user picture for the current content author.'),
    // A context of type "node" (the value here) will be given the key "node"
    // (specified as the key here) in hook_block_view() in the $context
    // parameter.
    'required contexts' => array('node' => 'node'),
  );

  $blocks['my_node_field'] = array(
    'info' => t('My node field'),
    'description' => t('An arbitrary field from a node.'),
    // Instead of using hook_block_view(), use a class that sub-classes the
    // Block class. Note that this class would also need to be registered in
    // hook_autoload_info().
    'class' => 'MyNodeFieldBlock',
    'required contexts' => array('node' => 'node'),
  );

  return $blocks;
}