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:


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.

$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 : ”),

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 – this can just have all the normal .info stuff
  • a file called registeruser.module – the code is below:

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.

More about theming – Devel Themer

What I really want to do is to be able to do whatever I want. Haha. Seriously, I want to be able to customize Drupal so that it doesn’t look like Drupal. So I am now working on theming functions. And to find out how a particular part of my site is generated, I am using the Devel module along with Devel Themer. These used to be packaged together but now they are separate contrib modules.

I had a sort of hard time getting Devel_themer to work properly. It was on the harder side of medium as far as modules go. But, I paid close attention to the issue queue at for the Devel_themer module and I was able to get it all figured out eventually. If you are getting 404 AJAZ errors, look at the queue and you will find answers there.

Lullabot has some good videos on how to use Devel_Themer. Check them out here.

Developing your site

In case you haven’t figured it out yet, Drupal is best if you learn ALL the ins and outs of the product. and that means learning how to:

  • Create subthemes from existing themes
  • Customize modules as needed and sharing with the community
  • Customize CSS (Very important)
  • Theme functions
  • Become a member of for the ridiculously low price of 30 bucks.
  • Get involved with the community
  • Probably a lot more

Here is a great site that will help you get started with some of the more serious development work that can be done in Drupal. With Drupal, it seems to me that knowing where the HTML that you see in Firebug is generated is an enormous part of making the platform work for you. So check this site out.

I also recommend trying out Aptana Code Editor.

Firebug for Firefox

Chrome’s Element Inspector