Drupal Forms Module: Tutorial

/**
* 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_sampleform, '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_sampleform() {
    $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);
}

function myform_sample_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_sample_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'];
}