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.

Use the hook_field_schema function from your custom module’s .install file

Many custom modules will not need to add information directly to your MySQL database. But if you do want to store new info from your module, you’ll need to include a .install file with your .module and .info files and use the hook function listed above to do this.

This references a great book that I picked up from Yeah, I know; another shameless plug. But it is worth it.

This is the code that you need to place in your install file. You’ll note that it looks similar to the SQL statements that you would use to add the info manually.

* Implements hook_field_schema()
function countryinfo_field_schema() {
$columns = array(
‘country’ => array(
‘description’ => ‘Two letter ISO country code of this
‘type’ => ‘varchar’,
‘length’ => 2,
‘not null’ => FALSE,
‘default’ => ”,
return array(
‘columns’ => $columns,

If this is the type of development you want to be able to do, take a look at the book at

Drupal – When to Code and when NOT to….

I have found a really great book for those who want to do Drupal development from O’Reilly.Programmer’s Guide to Drupal. This isn’t really a book for those who want to lhaveearn PHP though. It’s for those who are already comfortable with coding and want to apply those skills to Drupal.


What this book does really well is to show you when to start writing your own code and when not to. It also recommends that a novice Drupal developer learn to build sites in Drupal without any custom coding at all in the beginning. With something like 24,000 modules out there, there is always a good chance that someone has already written code for the very purpose you have. Or that judicious use of core modules will allow you to get where you need to be.

Check this book out: it is AWESOME!

How to write a working Drupal Module

The power of Drupal can only be leveraged best if you learn how to write your own custom modules. If you know a bit of PHP and aren’t intimidated by functions, elements, arrays and the like, this is the best place to start. Community Docs. This tutorial will take you through the ins and outs of writing a basic but very functional Drupal module. This tutorial will, in great detail, explain all the steps needed to create a module that will allow you to show a configurable number of posts in a block, create a configuration menu option for the module and include a Help page.

I’ve looked at many online tutorials on how to write basic modules and this one is the best. It has the most thorough explanations and is rigorous in its adherence to Drupal commenting standards, coding standards and naming conventions. As well as the Drupal specific functions that make developing for Drupal easier. If you want to learn Drupal PHP development, this is the place to start.

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

WAMP and Aptana code editor

well, i have all my great drupal environments setup. but as i started working with php code in aptana, i realized pretty quickly that i was going to need a local web server to test the php pages. so, install apache for windows xp. let me digress. windows xp is one of the best OSs ever developed. this MCSE isn’t big on MS much these days but XP is still a masterpiece. it will run so much stuff and run it well. i have a nearly ten year old dell running XP and it works great. it will run all the modern open source crap that i want and it is as solid as a rock. there is a reason that the biz community ran XP for as long as it did. and DOES. there are still millions of PCs out there in offices all over the place that run xp. there just isn’t a good reason to get rid of it when it will do 96% of what you need on hardware that is now pretty old. the only thing it won’t run that i actually care about is IE9. and i would never use that anyway if i didn’t have to plan my development around its css quirks.

i love XP. it’s great and it is a product like americans used to make: no planned obsolescence.

so, i’m installing a full WAMP server. most of the config for WAMP was pretty easy. the hard part was getting aptana to work properly with apache and the installed browsers so that the preview features could be used. for clues on that i am attaching a SS of what my server config looked like in aptana. it was a pain and i don’t believe that it was well documented. so, i posted what i did to stackoverflow here:

Prod and Dev

I have everything set up the way that I want it. i set up ftp on my dev server and  did a little configuring to get the permissions setup so that I could get to the /var/… dir tree. that wasn’t too much of a stretch. since it is dev, i just opened it up. plus, it is on a vm on my laptop so it isn’t a big deal.

so i can open the dev site with ftp, the prod site from ssh and open the same file from each side. the have the same name and the same dir location. so, i test the code on dev and then copy and paste it to the prod server. works pretty well.

Production and Development, SSH, Quality and Testing

So I have my two environments up and running. What I need to do now is get them aligned so I can do proper testing in the dev environment before moving the files to prod with a minimum of trouble. So, I have my dev environment on a vm on my laptop. i can access prod from the laptop or desktop via the drupal web interface. I can also access it via SSH and aptana. that’s the way that i can upload the code to prod. but i need to be able to access the dev code consistently from the desktop (the vm is on the laptop and the files are too big to move around).

so i need to be able to access the laptop vm from the desktop. and since they (desk n vm) are on different networks i have to route packets from the vm network to the home wireless network. otherwise, i’m going to have to sync the code files from the desk to the lap, upload the files on the laptop to the vm for testing, then upload from desk to prod via ssh. i think that i might try to get SSH running on the vm centos install then make it accessible to the desk. that would also closely mimic prod. that’s the ticket.