function hook_form_BASE_FORM_ID_alter
Same name in other branches
- 7.x modules/system/system.api.php \hook_form_BASE_FORM_ID_alter()
- 9 core/lib/Drupal/Core/Form/form.api.php \hook_form_BASE_FORM_ID_alter()
- 8.9.x core/lib/Drupal/Core/Form/form.api.php \hook_form_BASE_FORM_ID_alter()
- 10 core/lib/Drupal/Core/Form/form.api.php \hook_form_BASE_FORM_ID_alter()
Provide a form-specific alteration for shared ('base') forms.
Implementations are responsible for adding cache contexts/tags/max-age as needed. See https://www.drupal.org/docs/8/api/cache-api/cache-api.
By default, when \Drupal::formBuilder()->getForm() 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->getBuildInfo()['base_form_id'].
The call order is as follows: all existing form alter functions are called for module A, then all for module B, etc., followed by all for any base theme(s), and finally for the theme itself. The module order is determined by system weight, then by module name.
Within each module, form alter hooks are called in the following order: first, hook_form_alter(); second, hook_form_BASE_FORM_ID_alter(); third, hook_form_FORM_ID_alter(). So, for each module, the more general hooks are called first followed by the more specific.
Parameters
array $form: Nested array of form elements that comprise the form.
\Drupal\Core\Form\FormStateInterface $form_state: The current state of the form.
string $form_id: String representing the name of the form itself. Typically this is the name of the function that generated the form.
See also
\Drupal\Core\Form\FormBuilderInterface::prepareForm()
Related topics
43 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.
- book_form_node_confirm_form_alter in core/
modules/ book/ book.module - Implements hook_form_BASE_FORM_ID_alter() for \Drupal\node\Form\NodeDeleteForm.
- book_form_node_form_alter in core/
modules/ book/ book.module - Implements hook_form_BASE_FORM_ID_alter() for \Drupal\node\NodeForm.
- ckeditor5_read_only_mode_form_node_page_form_alter in core/
modules/ ckeditor5/ tests/ modules/ ckeditor5_read_only_mode/ ckeditor5_read_only_mode.module - Implements hook_form_alter().
- claro_form_media_form_alter in core/
themes/ claro/ claro.theme - Implements hook_form_BASE_FORM_ID_alter() for \Drupal\media\MediaForm.
- claro_form_media_library_add_form_alter in core/
themes/ claro/ claro.theme - Implements hook_form_BASE_FORM_ID_alter().
File
-
core/
lib/ Drupal/ Core/ Form/ form.api.php, line 310
Code
function hook_form_BASE_FORM_ID_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) : void {
// 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'] = [
'#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.