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

Drupal Form Api

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.

Drupal Form API: Initalization

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.

Drupal Form API: Creation and Modification

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.

Drupal Form API: Rendering

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.

Drupal Form API : Validation and Processing

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.

11 thoughts on “Drupal Form API : An Introduction

  1. Hi,

    I am new to drupal, i am developing a website using drupal, i understand the basics of form API , CCK etc. but i have some questions , can you please answer
    0) how can we validate, submit other form api functionalities in cck content types
    1) is there any add-on module for adding additional field type (ex: calendar field) to form api (FAPI).

  2. good article

    Could you write another formapi article more deeply?

    If want to learn the formapi code, how to track the whole process?

  3. that was terrible.

    not 1 but 2 people who have created totally useless overviews.

    I appreciate the fact that your native language is clearly not English, but the content itself is not useful in any way, all you have done is re-written in a more convoluted way what already appears on the api.drupal.org site.

    Or maybe that was the point.

  4. This is great. Pictures do speak thousands of words. Form handling process is involved enough to warrant some diagram to make it’s description a bit clearer and easier to follow.


  5. This is as useless as anything in drupal org. No BASIC help for using form_validate… Hate my corp. for choosing drupal.

  6. You could put a note at the beginning that is for Drupal 5x. Even 6x didnt change that much, but is good to notice

  7. Gees Evangelist…what does a persons native language have to do with learning Drupal!!!!

    Amit do you have any examples of form preocessing. I want to further process the submitted information but there is just no proper documentation on how this should be done. Please help.

Comments are closed.