hook_block_view() doesn't explain @return value for empty block [#2044791]

API page: https://api.drupal.org/api/drupal/modules%21block%21block.api.php/functi...

Enter a descriptive title (above) relating to function hook_block_view, then describe the problem you have found:

Blocks are sometimes empty depending on circumstances. A good example in core is the user login block, in https://api.drupal.org/api/drupal/modules!user!user.module/function/user...

    case 'login':
      // For usability's sake, avoid showing two login forms on one page.
      if (!$user->uid && !(arg(0) == 'user' && !is_numeric(arg(1)))) {

        $block['subject'] = t('User login');
        $block['content'] = drupal_get_form('user_login_block');
      }
      return $block;

This clearly shows it's ok to return an empty array.

However, hook_block_view() doesn't document this possibility.

Comment	File	Size	Author
#8	hook_block_view_empty_block_documentation-2044791-8.patch	964 bytes	skipyT
#8
#7	drupal_rewrite_settings_better_docs-2044791-7.patch	964 bytes	skipyT
#7
#5	hook_block_view_empty_block_documentation-2044791-5.patch	971 bytes	skipyT
#5
#2	hook_block_view_empty_block_documentation-2044791-2.patch	649 bytes	alexandre.todorov
#2

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 19 July 2013 at 16:43

Good catch! Maybe it should also mention that if $block['content'] is empty, the block is not shown at all (even the title) -- at least I think that is the case?

Comment #2

alexandre.todorov CreditAttribution: alexandre.todorov commented 20 July 2013 at 14:27

Assigned:	Unassigned	» alexandre.todorov
Priority:	Normal	» Minor
Status:	Active	» Needs review

File	Size
hook_block_view_empty_block_documentation-2044791-2.patch	649 bytes

Here is a patch about :

May be an empty array so as the block is not shown at all.
If The content is empty, the block is not shown at all.

Comment #3

DuaelFr

he/him

French

Montpellier, France

CreditAttribution: DuaelFr commented 22 July 2013 at 13:15

Assigned:

alexandre.todorov

» Unassigned

Removing forgotten assignation

Comment #4

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 22 July 2013 at 13:57

Status:

Needs review

» Needs work

Thanks! This needs a little bit of adjustment though:

...
  *     (preferable) or a string containing rendered HTML content.
+ *     If The content is empty, the block is not shown at all.
+ *   May be an empty array so as the block is not shown at all.

Can we put the last sentence before the list instead of after? Also, for formatting: The new text needs to be wrapped with the previous sentence into lines that go as close to 80 characters as possible without going over. And "The" should not be capitalized.

Comment #5

skipyT CreditAttribution: skipyT commented 8 August 2013 at 11:49

Status:

Needs work

» Needs review

File	Size
hook_block_view_empty_block_documentation-2044791-5.patch	971 bytes

Modified the documentation, please check again.

Comment #6

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 8 August 2013 at 14:02

Status:

Needs review

» Needs work

Thanks!

The first line of the @return still needs some work:

+ *   May be an empty array so as the block is not shown at all or an array
+ *   containing the following elements:

It really should just start with "Either an empty array..." not "May be an empty array...". And please change "so as the block is not shown at all" to "(the block will not be shown),".