function hook_form_BASE_FORM_ID_alter

Same name in other branches
  1. 9 core/lib/Drupal/Core/Form/form.api.php \hook_form_BASE_FORM_ID_alter()
  2. 8.9.x core/lib/Drupal/Core/Form/form.api.php \hook_form_BASE_FORM_ID_alter()
  3. 10 core/lib/Drupal/Core/Form/form.api.php \hook_form_BASE_FORM_ID_alter()
  4. 11.x core/lib/Drupal/Core/Form/form.api.php \hook_form_BASE_FORM_ID_alter()

Provide a form-specific alteration for shared ('base') forms.

By default, when drupal_get_form() is called, Drupal looks for a function with the same name as the form ID, and uses that function to build the form. In contrast, base forms allow multiple form IDs to be mapped to a single base (also called 'factory') form function.

Modules can implement hook_form_BASE_FORM_ID_alter() to modify a specific base form, rather than implementing hook_form_alter() and checking for conditions that would identify the shared form constructor.

To identify the base form ID for a particular form (or to determine whether one exists) check the $form_state. The base form ID is stored under $form_state['build_info']['base_form_id'].

See hook_forms() for more information on how to implement base forms in Drupal.

Form alter hooks are called in the following order: hook_form_alter(), hook_form_BASE_FORM_ID_alter(), hook_form_FORM_ID_alter(). See hook_form_alter() for more details.

Parameters

$form: Nested array of form elements that comprise the form.

$form_state: A keyed array containing the current state of the form.

$form_id: String representing the name of the form itself. Typically this is the name of the function that generated the form.

See also

hook_form_alter()

hook_form_FORM_ID_alter()

drupal_prepare_form()

hook_forms()

Related topics

57 functions implement hook_form_BASE_FORM_ID_alter()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

aggregator_form_aggregator_admin_form_alter in modules/aggregator/aggregator.processor.inc
Implements hook_form_aggregator_admin_form_alter().
block_form_form_test_alter_form_alter in modules/simpletest/tests/form_test.module
Implements hook_form_FORM_ID_alter() on behalf of block.module.
block_form_system_performance_settings_alter in modules/block/block.module
Implements hook_form_FORM_ID_alter().
block_form_user_profile_form_alter in modules/block/block.module
Implements hook_form_FORM_ID_alter() for user_profile_form().
book_form_node_delete_confirm_alter in modules/book/book.module
Implements hook_form_FORM_ID_alter() for node_delete_confirm().

... See full list

File

modules/system/system.api.php, line 1757

Code

function hook_form_BASE_FORM_ID_alter(&$form, &$form_state, $form_id) {
    // Modification for the form with the given BASE_FORM_ID goes here. For
    // example, if BASE_FORM_ID is "node_form", this code would run on every
    // node form, regardless of node type.
    // Add a checkbox to the node 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,
    );
}

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.