Form API Quickstart Guide

Last modified: May 26, 2008 - 02:41

For an introduction to how the Form API works, check out the
Form API Quickstart Guide.

» Login or register to post comments

Nevets wrote a really good simple example

dmnd - September 26, 2008 - 19:05

This example module by Nevets is very helpful
http://drupal.org/node/68159#comment-129394

This page has a good intro
http://api.drupal.org/api/file/developer/topics/forms_api.html/4.7

This page explains how to add content to the form when you view it again, based on information submitted
http://drupal.org/node/98009

Here is an example for 5
http://www.lullabot.com/articles/drupal_5_making_forms_that_display_thei...

this page explains how you call the form builder, and how that changed from 4.7 to 5
http://www.k4ml.com/node/208
but I think the author made one mistake. $form_id is the first argument

A consolidated version 5 example

robBrennan - November 7, 2008 - 17:33

I had a lot of trouble trying to piece together the threads above into a working version for Drupal 5 (especially as the link to the "Form API Quickstart Guide" goes to the API version 6 page by default). Anyway its working now so here it is:

<?php

/**
* A small example module of using the form api
* to display and process a form
* that is not used to extend the basic node content type
*
* In this sample the form collects two numbers
* and multiplies them together
*/


/**
* Implementation of hook_help().
*
* Throughout Drupal, hook_help() is used to display help text at the top of
* pages. Some other parts of Drupal pages get explanatory text from these hooks
* as well. We use it here to provide a description of the module on the
* module administration page.
*/
function myform_help($section) {
  switch ($section) {
    case 'admin/modules#description':
      // This description is shown in the listing at admin/modules.
      return t('The myform module multiplies two numbers together.');
  }
}

/**
* Implementation of hook_perm().
*
*/
function myform_perm() {
  return array('mutiple numbers');
}

/**
* Implementation of hook_menu().
*
*/
function myform_menu($may_cache) {
  $items = array();

    $access = user_access('mutiple numbers');
   
  if ($may_cache) {
      // This determines the path used to show the form and also makes a menu entry
      // This first path is for the entry form
    $items[] = array('path' => 'myform/sample', 'title' => t('sample form'),
      'callback' => myform_edit, 'access' => $access);
     
    // This path is for the routine that actually does the multplication
    // It is only setup as a callback (no menu entry)
    $items[] = array('path' => 'myform/multiple', 'title' => t('Multiplication Results'),
      'type' => MENU_CALLBACK, 'callback' => myform_multiple, 'access' => $access);
    }
   
    return $items;
}

function myform_build_form() {
    $form = array();
   
    // Build up the form
    // See api.drupal.org/api/4.7/file/developer/topics/forms_api.html (quickstart guide)
    // and api.drupal.org/api/4.7/file/developer/topics/forms_api_reference.html (forms api)
    // for more information on creating forms
   
    $form['value1'] = array(
      '#type' => 'textfield',
      '#title' => t('Value 1'),
      '#size' => 4,
      '#maxlength' => 4,
      '#description' => t('The first value to perform the multiplication with.')
    );
   
    $form['value2'] = array(
      '#type' => 'textfield',
      '#title' => t('Value 2'),
      '#size' => 4,
      '#maxlength' => 4,
      '#description' => t('The second value to perform the multiplication with.')
    );
   
    // Make sure we have a submit button

    $form['submit'] = array('#type' => 'submit', '#value' => t('Multiple values'));

   
    // drupal_get_form produces the form
    // which return to the drupal system
    // which produces the page
   
    // The first parameter to drupal_get_form
    // is the form id.  It also determines the
    // default validation and submit function names
    //
    // In this case
    //    Validation: myform_sample_validate()
    //  Submit: my_form_submit()
   
    //return drupal_get_form('myform_sample', $form);
    return $form;
}

function myform_edit() {
  return drupal_get_form('myform_build_form');
}

function myform_build_form_validate($form_id, $form_values) {
    if ( !isset($form_values['value1']) ) {
        form_set_error('value1', t('You must provide the first multiplication value.'));
    }
    else if ( !is_numeric($form_values['value1']) ) {
        form_set_error('value1', t('The first multiplication value must be a number.'));
    }   

    if ( !isset($form_values['value2']) ) {
        form_set_error('value2', t('You must provide the second multiplication value.'));
    }
    else if ( !is_numeric($form_values['value2']) ) {
        form_set_error('value2', t('The second multiplication value must be a number.'));
    }   
}

function myform_build_form_submit($form_id, $form_values) {
    // Submit routines do not directly produce any output
    // They do something with the form values
    // which is typically to store them in the database
    // then return a path to determine what page is shown next
   
    // In this case the path constructe includes the two values
   
    return 'myform/multiple/' . $form_values['value1'] . '/' . $form_values['value2'];
}
   

function myform_multiple($value1, $value2) {
    $output = '<p>';
    $output .= $value1. ' * ' . $value2 . ' = ' . ($value1 * $value2);
    $output .= '</p>';
   
    return $output;
}
?>

Form API Quickstart Guide

Nevets wrote a really good simple example

A consolidated version 5 example

Developing for Drupal

Quick links

Handbook license

User login

Contributor links