Using hook_form_alter in a custom module

Making what would seem to be really simple HTML changes in Drupal can appear really perplexing until you learn about the hook_alter functions. These Drupal specific functions are great for you to override Drupal behavior when the normal configuration options don’t provide a means to do so. That’s really important too: learning when to write code and when not to for Drupal. Always explore the available options for changing the way a module or theme presents data before you try to write code until you really know how to use Drupal properly. Writing code is satisfying but a waste of time in Drupal if someone has already written it for you.

But if there is an occasion to write some code, here is a really simple example of what to do to alter the presentation through a hook. Specifically, we are going to reverse the display of the user name and email fields on the user registration form so that the user name field is listed below the email field, the opposite of the way the form is written. This is the high level stuff that we are about to do.

The function or “hook” to override a form is:

hook_form_FORM_ID_alter()

where hook will be replaced by the name of the module I am going to create to do this and FORM_ID will be replaced by the ID of the actual form.

  1.  Identify the form ID of the Drupal form, in this case the User Registration Form.
  2.  Find the form in the core so that we can see what it is, where it lives and how it does what it does
  3. Create a new module to override the form so that we can make a very simple change

Find the form
Go to the form in a browser
View its HTML source in the browser
Figure out the form ID of the form you are altering. The ID will be the “id” attribute of the HTML form tag.
In the case of the User Registration form, the ID is, user_register_form. I can see this in the HTML source as “ID=user-register-form” but I know that the machine name will be with underscores and not dashes. Now, this is where it gets a bit tricky. Since the form is the user registration form, I know that I am certainly dealing with the Core User Module. I know enough about Drupal to know this is likely true so I know where to look. What I am emphasizing is to be really careful and ONLY do this in a test environment until you really know what you are doing. See my post about Get Pantheon if you want a good free Drupal testbed. One of the things that you can do to track down the area of code that you want to work with is to search through the .module file(s) for rendered text. When I look at the Drupal form (the user registration form in this case) that I want to alter, I note that there is a description that says, “Spaces are allowed; punctuation is not allowed except for periods, hyphens, apostrophes, and underscores.” If I search for that specific text in the user.module file, I am taken to line 1039. This is the precise area that I want to change, so I know that I am in the right area. If you are unsure of which .module file you need, you can expand your spearch to look at multiple files.

This is the code from the user.module file. It shows the user name code, then the email code below.

//THIS IS THE CODE’S START
$form[‘account’][‘name’] = array(
‘#type’ => ‘textfield’,
‘#title’ => t(‘Username’),
‘#maxlength’ => USERNAME_MAX_LENGTH,
‘#description’ => t(‘Spaces are allowed; punctuation is not allowed except for periods, hyphens, apostrophes, and underscores.’),
‘#required’ => TRUE,
‘#attributes’ => array(‘class’ => array(‘username’)),
‘#default_value’ => (!$register ? $account->name : ”),
‘#access’ => ($register || ($user->uid == $account->uid && user_access(‘change own username’)) || $admin),
‘#weight’ => -10,
);
$form[‘account’][‘mail’] = array(
‘#type’ => ‘textfield’,
‘#title’ => t(‘E-mail address’),
‘#maxlength’ => EMAIL_MAX_LENGTH,
‘#description’ => t(‘A valid e-mail address. All e-mails from the system will be sent to this address. The e-mail address is not made public and will only be used if you wish to receive a new password or wish to receive certain news or notifications by e-mail.’),
‘#required’ => TRUE,
‘#default_value’ => (!$register ? $account->mail : ”),
);
//THIS IS THE END OF THE CODE

Since we want to reverse the display order of the two fields, this is what we’ll do. Notice the ‘#weight’ key of the array for the user name? since that weight is “light” it will float to the top. If we give it a heavier weight, it will sink.

I create these items:

  • a folder called registeruser in sites/all/modules
  • a file called registeruser.info – this can just have all the normal .info stuff
  • a file called registeruser.module – the code is below:

<?php
function registeruser_form_user_register_form_alter(&$form, &$form_state, $form_id) {
$form[‘account’][‘name’][‘#weight’] = 1;
}

Since I just want to alter the one key, I can write it on just the two lines to make it simpler. The weight is now 1 instead of -10 so it will sink below the default of 0.
I enable my new module and test it out. I see now that the fields are in the reversed order. This change isn’t groundbreaking or anything, but it is a good example of how to user the hook_form_alter() function.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: