Changing an existing form is one of the first things that new Drupal developers will learn how to do. It is a natural extension from site building, where you might need to change one thing on a form created by a core or contributed module. One of the benefits of using the Form API to construct forms is that any module can alter any other modules form. In this tutorial, you are going to learn how to alter a Drupal form.

Add message to Create Article form

Go to Add Content -> Article. This is the form that you are going to alter.

To alter a form, you need to call hook_form_alter(). Add an empty implementation of hook_form_alter(), like so:

  
/**
 * Implements hook_form_alter().
 */
function starting_drupal_dev_form_alter(&$form, &$form_state, $form_id) {

}
  

To alter a form, you need to know its ID. There are two easy ways to find a form’s ID.

1. View source

The form ID will be the HTML ID in the form element. Here you can see that the form ID is article-node-form.

2. Print all Form IDs in form alter

Inside the hook_form_alter(), print a message to display the form_id.

  
function starting_drupal_dev_form_alter(&$form, &$form_state, $form_id) {
  dpm($form_id);
}
  

You will need to clear cache to see the dpm().

$ drush cc all

So the form ID is article_node_form. If you are really observant, you will have noticed that when viewing the source code, the form ID has hyphens instead of underscores. It should always be with underscores, so if you use the view source method, you will need to convert the hyphens to underscores.

We are going to change all the code inside the form alter function.

  
function starting_drupal_dev_form_alter(&$form, &$form_state, $form_id) {
  if ($form_id == 'article_node_form') {
    $form['field_message'] = array(
      '#type' => 'item',
      '#title' => t('New article'),
      '#markup' => t('You are about to create a new article'),
    );
  }
}
  

First, you added a condition to check that the form ID is article_node_form. Then you added a new form element, called field_message. This contains a message and is not a normal field like a textfield. You use the type item for this.

From api.drupal.org:

Item Generate a display-only form element allowing for an optional title and description.

If you reload the form, you should see the message. However, it is displayed below the tag, title, body and image fields. Not exactly what we want. To fix this, you need to add a weight to the field and weight it above the other fields.

You need to find out the weight of the existing fields. Let’s add the dpm($form) back into and inspect the relevant fields.

  
function starting_drupal_dev_form_alter(&$form, &$form_state, $form_id) {
  if ($form_id == 'article_node_form') {
    $form['field_message'] = array(
      '#type' => 'item',
      '#title' => t('New article'),
      '#markup' => t('You are about to create a new article'),
    );
    dpm($form);
  }
}
  

Expand the title field, as that is the first field on the rendered form.

As you can see, the weight is −5.

If you add a weight that is higher than −5, the new field will be positioned above the title field.

  
function starting_drupal_dev_form_alter(&$form, &$form_state, $form_id) {
  if ($form_id == 'article_node_form') {
    $form['field_message'] = array(
      '#type' => 'item',
      '#title' => t('New article'),
      '#markup' => t('You are about to create a new article'),
      '#weight' => -6,
    );
  }
}
  

And voila! The message field is now at the top of the form.

This tutorial is part of the Starting Drupal Development course. If you would like to receive all of the lessons, please add your details in the box below.

To scale the Drupal development learning curve faster, check out my book Master Drupal Development. It will help you master module development faster to become a fully fledged Drupal developer.