Altering forms

Before going ahead with our proposed functionality, I would like to open a parenthesis and discuss forms in detail. One of the principal things that you will do as a module developer in Drupal is alter forms defined by other modules or Drupal core. So, it behooves us to talk about it early on and what better moment than now when defining the form itself is still fresh in our minds.

Obviously, the form we just created belongs to us and we can change it however we want. However, many forms out there have been defined by others, and there will be just as many times that you will want to make changes to them. Drupal provides us with a very flexible, albeit still procedural way, of doing so--a suite of alter hooks, but what are alter hooks?

The first thing we did in this chapter was implement hook_help(). That is an example of an invoked hook by which a caller (Drupal core or any module) asks all other modules to provide input. This input is then aggregated in some way and made use of. The other type of hooks we have in Drupal are the alter hooks, which are used to allow other modules to make changes to an array or an object before that array or object is used for whatever it is used for. So, in the case of forms, there are some alter hooks that allow modules to make changes to the form before it's processed for rendering.

You may be wondering why am I saying that for making changes to a form we have more than one alter hook. Let me explain by giving an example of how other modules could alter the form we just defined:

/**
 * Implements hook_form_alter().
 */
function my_module_form_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
  if ($form_id == 'salutation_configuration_form') {
    // Perform alterations.
  }
}

In the preceding code, we implemented the generic hook_form_alter(), which gets fired for all forms when being built. The first two arguments are the form and form state (the same as we saw in the form definition), the former being passed by reference. This is the typical alter concept--we make changes to an existing variable and don't return anything. The third parameter is the form ID, the one we defined in the getFormId() method of our form class. We check to ensure that the form is correct and then we can make alterations to the form.

This is, however, almost always the wrong approach because the hook is fired for all forms indiscriminately. Even if we don't actually do anything for most of them, it's still a useless function call, not to mention that if we want to alter 10 forms in our module, there will be a lot of if conditionals in there--the price we pay for procedural functions. Instead, though, we can do this:

/**
 * Implements hook_form_FORM_ID_alter().
 */
function my_module_form_salutation_configuration_form_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
  // Perform alterations.
}

Here, we are implementing hook_form_FORM_ID_alter(), which is a dynamic alter hook in that its name contains the actual ID of the form we want to alter. So, with this approach, we ensure that this function is called only when it's time to alter our form, and the other benefit is that if we need to alter another one, we can implement the same for that and have our logic neatly separated.