Drupal Form API : An Introduction

Update : this article is only relevant to Drupal 5.x, with coming of Drupal 7 this is completely out dated.

I am guessing you must have created lot’s of html forms before, now you have started using Drupal and wondering how to create forms in Drupal and process them. If this is so then read on….

What is Drupal Form API?

Drupal form api, is nothing but a set of functions(off-course, that’s what api means) provided by Drupal as part of core functionality, since version 4.7, for us Drupal developers to create, validate and process our html forms, in a secure manner. When i say secure, i mean that you form data is almost free from injection attacks, but you do need to validate this data as per your own application requirements.

It essentially means we will be creating arrays with relevant data and Drupal’s form generation engine will generate the html form for us.

Ok, so what?

I can create my own forms using html, why should i care about Drupal’s form api?

Simple, if you want to extend the forms provided by other Drupal modules or Drupal itself(which you will have too, most of the time), with out actually modifying their code, then use Drupal’s form api.

See if we want to use the benefits of modularity Drupal provides we should be able to modify the forms created by others to suit our needs.

Well you must be wondering, this can be done by editing the code provided by the module. Sure you can do that, but in the process you loose the ability to upgrade that module when a new version comes along, because upgrading means porting all those changes again, now you are stuck.

On the other hand if you have your own module, using form api, then all you need to it is just modify in you source files, while you can simple upgrade the module without worrying about loosing your changes.

This also means you can split you form in many usable components and the piece them together for end user. This will give you reusability benefits that we programmers strive for.

Not yet convinced…

Let me see what i can do about that.. Ok let’s try this line of thought, when you used to create html forms of similar types, one after other from one project to other did you ever thought their should be a form generator, where you specify the parameter and it automatically generates the form for you. If yes then, consider your wish granted as Drupal’s Form API is one such thing that makes form creation an easy task.

Ok, now i am assuming that you understood the importance of form api, then next thing to do is to understand how Drupal process the forms. When you understand the flow, you can control it. So let’s get on to it.

Drupal Form process flow

This whole process starts when we call the drupal_get_form() function. It starts by creating $form_values to an empty array and $form_submitted to false. $form_values variable holds the submitted data.

Next step is to set the unique token based on drupal_private_key, it is used only for logged in users, next important step is to set a form ID which is inserted with form as hidden field.

Now, form generation engine collects the information about form elements by calling element_info() function. This in turn calls hook_element(), which might be implemented by other modules. We can use this hook to create our own specialized element types, eg textbox which only takes numeric input.

Now engine know the definition of all element type, so it next it will look for form validation function. The form validation function to use can be specified in any of the forms #validate, or formID_validate() or #base _validate(). #base is the value that you specify with the form array.

Engine will look for submit function to which the form will be submitted. They can be specified as value #submit for key, or formID_submit() function or #base_submit() function. Once it gets the submit function for the form it calls hook_form_alter() to give any module which wants to change the form. Basically it’s our time to modify someone else’s form to add or remove the input fields and/or descriptions.

Now it will build the form, when whole form is build it will call any function specified in the #after_build. Then it will look for theming options for the form, by calling #theme value if specified or theme_get_function() to get the theme. Now engine is ready for rendering the form, so it gives us one last chance to alter the form by calling #pre_render value that we set.

It is convert the data array to html form by calling the drupal_render() function, the generated html will be returned. That’s it engine is done, and a form is shown to user.

Once form is submitted, Drupal form engine comes back to live again and validates it by checking $_POST is not empty and $_POST[‘form_id’] has a sting value that matches with the Drupal form ID or #base value. It also checks if the form uses the Drupal’s token mechanism, it check for valid token, if token mechanism is used. It checks to ensure the presence of all required fields and also that the value of radio buttons, check boxes and selects are actually from what was send to the form. Once this is done it call the validate function that user defined for his form.

If validation fails then, form is sent back to user with appropriate error message. If the validation passes then form engine passes the form values to the submit function defined by #submit property. This is where you can do whatever you need to do with the form data.

Finally user will be redirected to the path specified by #redirect property, in absence of this property user will be redirected to the form again.

Now, check out the presentation given by my colleague Payel, on Drupal form api for more information. She once commented that after using Forms API, she almost forgot how to use html forms.

Now the time has come to head back to Drupal’s website and read following articles.

1. Forms API QuickStart guide.
2. Forms API Reference.

Finally download or take a print of Forms API cheatsheet from edocr.