Redirecting Users After Submitting a Form in Drupal 5
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 Forms API, a clever way to craft HTML forms using logical and extremely flexible arrays.
Drupal Forms 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 Forms API in a future article, if you can't wait I suggest taking a look at the Forms API Quickstart Guide, for now let's focus in 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 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.
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. After some testing, I know this could be obvious to hardcore Drupal developers but it's still useful for new comers, 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.