hook_block_info

7 block.api.php	`hook_block_info()`
8 block.api.php	`hook_block_info()`

Define all blocks provided by the module.

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:

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 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 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.
cache: (optional) A bitmask describing what kind of caching is appropriate for the block. Drupal provides the following bitmask constants for defining cache granularity:
- DRUPAL_CACHE_PER_ROLE (default): The block can change depending on the roles the user viewing the page belongs to.
- DRUPAL_CACHE_PER_USER: The block can change depending on the user viewing the page. This setting can be resource-consuming for sites with large number of users, and should only be used when DRUPAL_CACHE_PER_ROLE is not sufficient.
- DRUPAL_CACHE_PER_PAGE: The block can change depending on the page being viewed.
- DRUPAL_CACHE_GLOBAL: The block is the same for every user on every page where it is visible.
- DRUPAL_NO_CACHE: The block should not get cached.
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. Most modules do not provide an initial value, and any value provided can be modified by a user on the block configuration screen.
status: (optional) Initial value for block enabled status. (1 = enabled, 0 = disabled). Most modules do not provide an initial value, and any value provided can be modified by a user on the block configuration screen.
region: (optional) Initial value for theme region within which this block is set. Most modules do not provide an initial value, and any value provided can be modified by a user on the block configuration screen. Note: If you set a region that isn't available in the currently enabled theme, the block will be disabled.
visibility: (optional) Initial value for the visibility flag, which tells how to interpret the 'pages' value. Possible values are:
- 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.
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.
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.

For a detailed usage example, see block_example.module.

17 functions implement hook_block_info()

4 invocations of hook_block_info()

File

modules/block/block.api.php, line 104: Hooks provided by the Block module.

Code

function hook_block_info() {
  // This example comes from node.module.
  $blocks['syndicate'] = array(
    'info' => t('Syndicate'), 
    'cache' => DRUPAL_NO_CACHE,
  );

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

  return $blocks;
}

Comments

Must be used within a function

Posted by kvvnn on November 28, 2010 at 12:33am

In my experience, the following will break the jQuery object, throwing "jQuery is not defined":

< ? php
drupal_add_js(drupal_get_path('module', 'mymodule') . '/js/mymodule.js');

It must be used within a function. The following will work :

< ? php
function mymodule_block_view($delta=''){
drupal_add_js(drupal_get_path('module', 'eyedsafe') . '/js/eyedsafe.js');

Since this is different than D6, I wanted to point it out.

This is still the wrong way

Posted by dalin on June 2, 2011 at 6:33am

This is still the wrong way to add JS to a block. See documentation on render arrays and the #attached property.

Hi Sir dalin, Thank you for

Posted by darrylmabini on November 18, 2011 at 3:58pm

Hi Sir dalin,

Thank you for the helpful info.

do I need to use render() or drupal_render() to render the array()?
I try to place it inside hook_block_view(), but if I return it together with the 'subject' and 'content' it won't work unless I use render().

Problem with 'pages' list

Posted by Vlad Stratulat on July 8, 2011 at 10:23am

Hi, I'm trying to create a block and display it in hidden region on listed pages. The block is displaying in hidden region but it doesn't work with pages.

function module_block_info() {
	$blocks = array();
	$blocks[0] = array(
		'info' => t('Title'),
		'region' => 'subregion',
		'status' => 1,
		'cache' => DRUPAL_NO_CACHE,
		'visibility' => BLOCK_VISIBILITY_NOTLISTED,
		'pages' => array('user/register', 'action/*')
	);
	return $blocks;
}

The hidden region is provided in theme.info file

regions[subregion] = Sub region
regions_hidden[] = subregion

When I point 'pages' => 'user/register' it works fine and block disappear on 'user/register', but when I'm trying to make a list of pages, it doesn't work.

Can anybody tell me where I'm wrong?

It is not an array

Posted by Martijn Houtman on July 21, 2011 at 10:21am

It should be a string with the urls, separated with \n, i.e.:

<?php
  $block['...']['pages'] = 'foo/bar\nfoo/bar/*';
?>

Front page?

Posted by opdavies on August 1, 2011 at 8:57am

Can this be used to return the front page?

I did it using: 'visibility'

Posted by opdavies on August 1, 2011 at 10:47am

I did it using:

'visibility' => BLOCK_VISIBILITY_LISTED,
'pages' => variable_get('site_frontpage', NULL)

Shouldn't we use 'pages'

Posted by opi on October 12, 2011 at 3:21pm

Shouldn't we use 'pages' = '<front>' ?

\n

Posted by mortona2k on August 3, 2011 at 5:41pm

We have to use double quotes since \n needs to be parsed:

$block['...']['pages'] = "foo/bar\nfoo/bar/*";

But how do we use a PHP condition?

I usually use the following

Posted by mpurdon on September 20, 2011 at 5:54pm

I usually use the following syntax to keep it easier to read:

<?php
$blocks['foo']['pages'] = implode("\n", array (
    'here',
    'there',
));
?>

performance

Posted by Taiger on September 12, 2011 at 6:24pm

Note that blocks in regions that are hidden are still rendered.
Here is an article about it by Webchick:
http://www.lullabot.com/articles/drupal-performance-tip-block-visibility

I was unable to find how to

Posted by Martijn Houtman on July 21, 2011 at 12:03pm

I was unable to find how to set the content-types for which this block should be visible, and found out that it is actually handled in the node module. So I finally did this:

<?php
function hook_block_info() {
    ...
    // Limit on node types
    $form_state = array(
        'values' => array(
            'module' => '...',
            'delta'  => '...',
            'types'  => array('...', '...'),
        ),
    );
    node_form_block_admin_configure_submit(NULL, $form_state);
    ...
}
?>

Not sure if it is actually a preferred way, but at least it works in a way so that the settings can still be changed through the admin interface.

Example usage of BLOCK_VISIBILITY_PHP

Posted by pkiekens on September 22, 2011 at 9:04am

This code shows an example of a block containing a link that only appears when the user hasn't already logged in.

<?php
// ...
function loginlink_block_info() {
  $blocks['myloginlink'] = array(
    'info' => t('Login Link'),
    'status' => TRUE,
    'region' => 'sidebar_first',
    'visibility' => BLOCK_VISIBILITY_PHP,
    'pages' => <?php global $user; if ($user->uid == 0) return TRUE; else return FALSE; ?>'
  );
// ..
?>

Important: Verify that the PHP filter module is enabled if you want to use BLOCK_VISIBILITY_PHP!

The hook_block_info() return arguments are not working properly

Posted by ramasubbu1984 on November 21, 2011 at 11:03am

Hi,

I wrote a custom block hook_block_info() function return arguments are like below,

function hook_block_info() {
$blocks['sample'] = array(
'info' => t('sample block'),
'region' => 'content',
'status' => 1,
'visibility' => BLOCK_VISIBILITY_LISTED,
'pages' => array('home.html'),
);
return $blocks;
}

The info, region & status arguments are working properly. But the visibility and pages are not working properly. I cleared the cache and i have updated the module also. But no reflection in my program.

See earlier comments

Posted by David_Rothstein on December 7, 2011 at 9:06pm

Your code didn't work because 'pages' is supposed to be a string, not an array.

See the comments above which already pointed that out.

How to work with buttons in block?

Posted by MarcusElectrus on January 30, 2012 at 8:03pm

Hi.

I have a block with select list and button. I want to use chosen variable as filter but when i click the button nothing happens. This is my code:

<?php
function maszynydb_block_view($delta=''){
    $block = array();

    switch($delta){
    case 'filtry':
        $block['subject'] = 'Filtr technologii';
        
        ... Select list code

        $content['filtr'] = array(
            '#type' => 'submit', 
            '#value' => 'Filtruj',
            '#submit' => array('ustaw_filtry'),
            );    

        $block['content'] = $content;
        break;
    }
    return $block;
}

function ustaw_filtry($form, $form_state){
    drupal_set_message('filtr');
}
?>

Function ustaw_filtry() should be called but it isn't. The same code put in node_form() runs correctly. What can be wrong?

You need to create the form

Posted by adaddinsane on April 24, 2012 at 10:37am

<?php
$content = drupal_get_form('function_with_my_form', $arguments...);
?>