Redirecting Users After Submitting a Form in Drupal 5 and 6

Last updated July 22, 2010. Created by Steven Jones on April 5, 2007.
Edited by xenophyle, Jonah Ellison, traxer, jergason. Log in to edit this page.

If you create web sites based on Drupal you know that controlling forms, how they are themed, validated and processed, is a highly valued skill for any serious developer. This article will discuss a few ways to redirect your users to another page after they've submitted a form, overriding Drupal's defaults.

Drupal 5 provides developers with a Form API, a clever way to craft HTML forms using logical and extremely flexible arrays.

Drupal Form API also allows developers to theme every little detail of a form. For simpler cases using the #prefix and #suffix properties can be enough, but if you need extreme power, and sooner or later you will, then you can use forms-exclusive theme functions and drupal_render().

I'll explain the basics of Form API in a future article. If you can't wait I suggest taking a look at the Form API Quickstart Guide. For now let's focus on redirecting users after form submission in Drupal.

In the beginning was the form function

Every form in Drupal starts as a function that creates an array, usually named $form. Then the function's name is passed to drupal_get_form().

As with every function in a module, a form creation function should start with the name of the module, for example:

boogeeks_notify_form()

First, this assumes my module is named boogeeks, the first word in my function's name. I'm separating each word with an underscore and I suggest you do the same.

Second, I've chosen the verb notify to have a clear idea of what the form will do. I used something like this in a recent project for hacking a form where users opt-in to receive email alerts.

Third, I added form, helpful when you have many functions in your module and need a quick way to tell apart the ones creating forms.

Notice that the only requirement for naming your form function is the first one, starting with your module name, the other two are my suggestions for cleaner and easier to understand code.

Theme, validate and submit

Now that we have boogeeks_notify_form() taking charge of form creation we need a few additional functions, all of them named based on the original.

• theme_boogeeks_notify_form(): Will take care of the looks of your form, this is the theming function.
• boogeeks_notify_form_validate(): Will check if user entered information that validates according to rules established here.
• boogeeks_notify_form_submit(): Will process the form and redirect the user to other page.

For this article's purposes we are interested in the third function, the one ending in _submit.

Where to go now?

Every form submission function, boogeeks_notify_form_submit() in our example, needs to return a value. This value is the url where the user will go after successfully submitting a form.

So, if you want to thank your user after opting in to receive email alerts then you can finish boogeeks_notify_form_submit() with something like:

return 'thankyou-for-subscribing';

That's the url of some page with the usual thank-you-we-love-you-dear-visitor stuff. You can also return an array. In that case, the values are passed as arguments to drupal_goto(). This way you can also set the query, the fragment and HTTP response of your redirect.

All Drupal provided forms have pre-defined values in their submit functions. Two well known and often used ones are user_login() and user_register(), used to create new accounts. Both are created in user.module.

How to override default form redirection in Drupal

There are two ways to override default form redirection: with a destination parameter in a url, and using the #redirect property of Forms API (I know this could be obvious to hardcore Drupal developers but it's still useful for new-comers). After some testing I determined the redirection processing flow is as follows:

• The url returned from the form submit function,
• which is overriden by #redirect,
• which is overriden by destination passed in the url.

You'll need to modify a form using hook_form_alter() to use #redirect.

If you want to work with destination you'll have to include it in the url used to call the page showing your form.

Now you can take your users whenever you want after submitting a form, no matter if it's a Drupal provided form or one that you've coded.

In Drupal 6, one method is:

Create a custom module custom.module and place this code in it:

Create a file custom.info and place this code in it:

Then place custom.module and custom.info in a folder 'custom' and upload it to /sites/all/modules/. Enable the module in Administer > Modules > check 'Custom'.

Create the 'thank-you-page' page and voila! If you want your thank you page to be node/22, then change $form['#redirect'] = 'thank-you-page'; to $form['#redirect'] = 'node/22';.

As with Drupal 5, you can append a query and a fragment and set the HTTP response of your redirect by using an array as the destination of the redirect:

$form['#redirect'] = array('user/login', 'destination=node');