Block configuration form validation

It's not obvious from reading the api doc at http://api.drupal.org/api/function/hook_block/6 and http://api.drupal.org/api/function/block_example_block/6 how to do form validation for block configure form. The key is to realize they are form sub-elements that are part of a form defined by the block core module. Let's say we have a block that supplies one textfield for the user to enter a lucky number. We need to validate that the input is a number and that it's a lucky number. The hook_block() is something like this:

function mymodule_block($op = 'list', $delta = 0, $edit = array()) {
  swith($op) {
    case 'list':
      // return block info array()
    case 'configure':
      return $form['mymodule_lucky_number'] = array(
        '#type' => 'textfield',
        '#title' => t('Enter a lucky number, this must be a number!'),
        '#default_value' => 7,
        '#element_validation' => array('_mymodule_validate'),
      );
    case 'save':
      // save the lucky number here
      break;
    case 'view':
      // handle view op
      return ....
  }
}

we can use '#element_validation' form api key set validation function of each element we define here. This key takes an array of validate function names like the top level '#validate' key. This is how to define the element validation function:

function _mymodule_validate($element, &$form_state) {
  $value = $form_state['values']['mymodule_lucky_number'];
  if (!is_numeric($value)) {
    form_error($element, t('Input is not a number.'));
  }
}

But in case you have many form elements and you need to validate them together say the elements are interdependent so they need to be validated together, or just for convenience you just prefer one validation function. Then there is another way to implement validation by alter the block configure form itself to add additional form validation function. This form's id is "block_admin_configure". And so we can adds our validation fucntion using hook_form_FORM-ID_alter():

function mymodule_form_block_admin_configure_alter(&$form, $form_state) {
  // only modify the form if it involve our form element
  // this function will be called for every block configure form
  if (empty($form['block_settings']['mymodule_lucky_number'])) {
    return;
  }
  // add our validation
  $form['#validate'][] = '_mymodule_validate';
}

The block module puts any block supplied form elements inside the 'block_settings' key. So we look in there for our form key to determine if this is our form, then alter. The form id is 'block_admin_configure' so we define mymodule_form_block_admin_configure_alter() to alter this specific form. Once our validate function _mymodule_validate() is added, it's called as part of the normal form validation process. We can then do whatever validation we need:

function _mymodule_validate($form, &$form_state) {
  $value = $form_state['values']['mymodule_lucky_number'];
  if (!is_numeric($value)) {
    form_error($form['block_settings']['mymodule_lucky_number'], t('Input is not a number.'));
  }
  // only number divisible by 8 is lucky
  $value = (int)$value;
  if (($value % 8) != 0) {
    form_error($form['block_settings']['mymodule_lucky_number'], t('The number is not a lucky number.'));
  }
}