Document hook_form_FORM_ID_alter()

What do you think of this (with the use of http://drupal.org/node/144132#form-id-alter):

/**
 * Provide a form-specific alteration rather than a single hook_form_alter().
 *
 * Modules can implement hook_form_$form-id_alter() rather than a single
 * hook_form_alter() with many conditional switch statements.
 * This is optional, and is most useful for tidying the code of modules that
 * alter many forms to customize a site's operations.
 *
 * Note that this hook is executed before hook_form_alter(), in this case if
 * a) Module alpha has weight 30 and implements hook_form_$form-id_alter().
 * b) Module zeta has weight 0 and implements hook_form_alter().
 * Then zeta's form alteration will be executed first.
 *
 * @param $form
 *   Nested array of form elements that comprise the form.
 * @param $form_state
 *   A keyed array containing the current state of the form.
 * @return
 *   None.
 *
 * @see drupal_prepare_form().
 */

function hook_form_my_first_form_alter(&$form, &$form_state) {
  // Form modification for 'my first form' code goes here.
}

function hook_form_my_second_form_alter(&$form, &$form_state) {
  // Form modification for 'my second form' code goes here.
}

function hook_form_my_third_form_alter(&$form, &$form_state) {
  // Form modification for 'my third form' code goes here.
}

Wow, I didn't know this. Well, I had heard of it at some point, but I've never made use of it even though it would have been very useful.

Is there a specific reason that the forms in your example are named with Greek letters (as opposed to numbers or Latin letters), or that the second form is named "zeta" instead of, say, "beta"?

Also, I'm not sure the hook needs to be implemented three times - after the first "hook_form_my_form_alter" developers might get the point...

Edit: I see that the three implementations are a legacy of the 5.x->6.x upgrading page, but I really think they're only necessary to explain that change, not to document the function itself.

/**
 * Provide a form-specific alteration rather than a single hook_form_alter().
 *
 * Modules can implement hook_form_$form-id_alter() rather than a single
 * hook_form_alter() with many conditional switch statements.
 * This is optional, and is most useful for tidying the code of modules that
 * alter many forms to customize a site's operations.
 *
 * Note that this hook is executed before hook_form_alter(), in this case if
 * a) Module alpha has weight 30 and implements hook_form_$form-id_alter().
 * b) Module beta has weight 0 and implements hook_form_alter().
 * Then beta's form alteration will be executed first.
 *
 * @param $form
 *   Nested array of form elements that comprise the form.
 * @param $form_state
 *   A keyed array containing the current state of the form.
 * @return
 *   None.
 *
 * @see drupal_prepare_form().
 */

function hook_form_my_first_form_alter(&$form, &$form_state) {
  // Form modification for 'my first form' code goes here.
}

Looks good

Changes are below.

Further comments:

- The stuff about call order is contradictory. First we state that this is called /before/ the general hook_form_alter, then we state that the hook_form_alter of module beta will be triggered before the hook_form_FORM_ID_alter of alpha. I've tried to resolve that below, please check if it is still accurate.

- Consider consistently calling it hook_form_FORM_ID_alter instead of hook_form_$form-id_alter...

/**
 * Provide a form-specific alteration rather than a single hook_form_alter().
 *
 * Modules can implement hook_form_$form-id_alter() rather than a single
 * hook_form_alter() with many conditional switch statements.
 * This is optional, and is most useful for tidying the code of modules that
 * alter many forms to customize a site's operations.
 *
 * Note that this hook is executed before hook_form_alter(), therefore if
 * a) Module alpha has weight 30 and implements hook_form_$form-id_alter().
 * b) Module beta has weight 0 and implements hook_form_alter().
 * Then alpha's form alteration will be executed first.
 *
 * @param $form
 *   Nested array of form elements that comprise the form.
 * @param $form_state
 *   A keyed array containing the current state of the form.
 * @return
 *   None.
 *
 * @see drupal_prepare_form().
 */
function hook_form_FORM_ID_alter(&$form, &$form_state) {
  // Modification for the form with the given form ID goes here. For example, if
  // FORM_ID is "user_register" this code would run only on the user
  // registration form.

  // Add a checkbox to registration form about agreeing to terms of use.
  $form['terms_of_use'] = array(
    '#type' => 'checkbox',
    '#title' => t("I agree with the website's terms and conditions."),
    '#required' => TRUE,
  );
}

Feel free to commit this once these small changes are in! :)

Lol, I thought that was your job. I keep forgetting that the docs repository is open for everybody. ;)

Well, here's my final version. I also took out some of the text that seemed specific to updating instructions - nobody needs to know that a hook is "optional".

/**
 * Provide a form-specific alteration instead of the global hook_form_alter().
 *
 * Modules can implement hook_form_FORM_ID_alter() to modify a specific form,
 * rather than implementing hook_form_alter() and checking the form ID, or
 * using long switch statements to alter multiple forms.
 *
 * Note that this hook fires before hook_form_alter(). Therefore all 
 * implementations of hook_form_FORM_ID_alter() will run before all implementations
 * of hook_form_alter(), regardless of the module order.
 *
 * @param $form
 *   Nested array of form elements that comprise the form.
 * @param $form_state
 *   A keyed array containing the current state of the form.
 * @return
 *   None.
 *
 * @see drupal_prepare_form().
 */
function hook_form_FORM_ID_alter(&$form, &$form_state) {
  // Modification for the form with the given form ID goes here. For example, if
  // FORM_ID is "user_register" this code would run only on the user
  // registration form.

  // Add a checkbox to registration form about agreeing to terms of use.
  $form['terms_of_use'] = array(
    '#type' => 'checkbox',
    '#title' => t("I agree with the website's terms and conditions."),
    '#required' => TRUE,
  );
}

Looks as if this can go in!

Here's a patch for core.php. I put the function right after hook_form_alter.

This I have done. :)

Hey that's pretty cool! But...
I'd suggest adding this to the hook_form_alter page too:
http://api.drupal.org/api/function/hook_form_alter
For people to understand there's an alternative (better) way.

+1 to #14 -- add a mention and a link.

Above are patches for 7.x and 6.x for #14

I don't have contrib access (yet, and/or haven't applied yet). Someone else?

Committed to the contrib hook docs in 6.x: http://drupal.org/cvs?commit=190462

Reopening:

+ * Note that you can also use hook_FORM_ID_alter() to alter a specific form,

It's hook_form_FORM_ID_alter()

Whoops. I put hook_FORM_ID_alter() rather than hook_form_FORM_ID_alter() in my earlier patches, and no one else noticed the error either, so those lines got committed with the wrong hook name in them. So someone needs to make a new patch (against the current D6 and D7 documentation) to fix this error.

I don't have time to do it today, so if someone else wants to take it on to get their feet wet with supplying patches (webchick marked it as "Novice" for that reason), that is fine. Otherwise, I'll try and get to it sometime soon.

I fixed the 6.x documentation, now we just need to patch system.api.php in D7.

6.x looks good to me. Here's a patch for 7.x

Let's make sure that line gets wrapped at 80 characters (move the last word to the next line).

Good idea. How about this patch?

Another minor nitpick (sorry!), can we remove this extra comma?
"Note that you can also use hook_form_FORM_ID_alter() to alter a specific form, instead of this hook,"

So that it is :
"Note that you can also use hook_form_FORM_ID_alter() to alter a specific form instead of this hook,"

Can we get a second opinion on that comma? I think the comma is necessary, because the "instead of this hook" clause refers to the beginning of the sentence (using a different hook) rather than what is just before it (alter a form).

+ * Note that you can also use hook_form_FORM_ID_alter() to alter a specific
+ * form, instead of this hook, which gets called for all forms.

Ooh! Commas.

If a sentence can be made more clear with commas, then by all means use them. However, in this case, why don't we just rearrange this sentence so that the entire thing is more clear.

This is what I understand it to be saying:

+ * Instead of hook_form_alter(), which is called for all forms, you can also use
+ * hook_form_FORM_ID_alter() to alter a specific form.

+1 to #33.

OK, here's one more go at it. :)

I also removed the @return: None. section.

If this is OK, I can also patch D6 (I have contrib CVS access now).

Gracious. Forgot one. :)

I'll assign this back to myself and patch D6 in the next day or two. I do have contrib repos access now.

I went ahead and committed the same wording change as the patch in #37 (with the end of line fix) to D6 docs: http://drupal.org/cvs?commit=204464

Hope that's OK. I figured it has now probably been reviewed to death.