Given that they really go together, this week we will look at two different hooks: hook_block_configure() and hook_block_save(). Their purpose is to programatically add extra configuration options to the block configuration form: you know, the one with the region and visibility settings.

Since last week we created a simple block to illustrate how we can declare our own hooks, I decided to now show you something related. Remember when I told you that under normal circumstances you'd let the user set in the UI the number of Articles nodes displayed by the block? As opposed to hardcoding that number?

Well, how can we let the user do this? You can put a text field nearly anywhere for this purpose, but wouldn't it make sense for it to be in the block configuration form? Right there with the block title and what not? So for that, we need to implement two quick hooks. First the code, then the explanation:

function demo_block_configure($delta = '') {
  $form = array();
  if ($delta == 'demo') {
    $form['demo_number'] = array(
      '#type' => 'textfield',
      '#title' => t('Number of nodes you want the block to show'),
      '#default_value' => variable_get('demo_number', 10),
      '#size' => 60,
    );
  }
  return $form;
}

function demo_block_save($delta = '', $edit = array()) {
  if ($delta == 'demo') {
    variable_set('demo_number', $edit['demo_number']);
  }
}

Both of these hooks deal closely with the Drupal Form API. What this means is that their job is to create form fields with various options, gather information submitted by the user and store that information in the database.

The first one - hook_block_configure() - first checks that what happens next gets applied only to our block (demo) and then adds another item to the form. In our case, a simple text field with a relevant title and max size. I will explain what the #default_value is in a moment.

The second one - hook_block_save() - takes the information provided by the user in that form item and saves it into the database as a persistent variable. There is a database table full of them by the way. This is done using the variable_set() function Drupal has, which takes two parameters: the name of the variable to be stored (so you can later find it in the db) and the content.

Now, getting back to the first hook, #default_value simply sets the value that the user finds in our field by default when he opens the block configuration form. Using the variable_get() Drupal function, we retrieve the value that is currently set in the database - see hook_block_save(). If none is set, we provide a default value of 10 to appear there.

Now this is pretty much it. After adding these hooks, clear the cache and go edit the block configuration. You’ll find the new field you can now assign another number with. But wait, the block displays the same number of Article nodes no matter what number you set there. That’s because you also need to go back to where we hardcoded the number 10 as the range in the SQL query. Simply change that to:

$number = variable_get('demo_number', 10);

And there you have it. Fully functioning block that displays Article titles and that the user can control - at least when it comes to the number of nodes to display. But by now, I’m sure you also figured out you can go much further than this. So if you want some homework, try to make it so that the user can choose also what content type the block will display.

And as always, if anything is unclear, just go to the comments.