Creating custom form in Drupal7

Creating a custom form in Drupal7:

The form creation in Drupal 7 comes quite handy once you start understanding how it works.

We will see step by step what is form and how to define it in Drupal way.

A form can be defined as a set of input elements which accepts inputs from user and process the input and display the output or simply reset the form when the form is submitted. Defining a form in Drupal way is not at all tricky but of course needs some learning to do. 

There are two ways you can create forms in Drupal7, such as drupal_get_form() and drupal_build_form() api function. We are going to use drupal_get_form() api as we don't need form_state values at the begining of form creation.

Define menu item for form callback:

The drupal_get_form function can be mentioned as page callback in the hook_menu, so that the renderable form array is returned when the menu link is accessed.

/**
 * Implements hook_menu
 *
 * @access  Public
 *
 * @return array $items
 */
function MYMODULE_menu() {
  $items['mycustom-form'] = array(
    'title' => 'My Custom Form',
    'description' => 'My first custom form',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('mycustom_form'),
    'access callback' => TRUE,
  );

  return $items;
}

Here the page callback is set as drupal_get_form, whereas page arguments is set as mycustom_form. The 'mycustom_form' is the function which is going to return the form. It is mandatory to clear the performance cache whenever the hook_menu is defined.

Define the mycustom_form:

It is advisable to keep the callback function suffixed with _form like we did here (mycustom_form). Although it is custom function this function should be defined with two parameters: $form and $form_state.

/**
 * Custom function to return the form
 *
 */
function mycustom_form($form, &$form_state) {
  
  $form['name'] = array(
    '#type' => 'textfield', // text input field
    '#title' => 'Your good name please?', // label value
    '#maxlength' => 25, // maximum allowed length
    '#required' => TRUE, // to make this field required 
  );

  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Submit'),
  );
  
  return $form;
}

When the mycustom-form url is called, this page will output the form asking for the name with submit button. When you click the submit button now, it will only reset the form, that is because there is no submit handler defined for this form. A submit handler is one which handles and processes the form when submitted. Lets see how to define submit handler.

To define submit handler:

The submit handler function will be automatically detected by defining the function name same as the page argument except to be suffixed with form_submit. In our case mycustom_form is the form generation and mycustom_form_submit will be the submit handler by default.

/**
 * Submit handler of the mycustom_form
 *
 * Displays simple message to the user
 */
function mycustom_form_submit($form, &$form_state) {
  $name = $form_state['values']['name'];
  drupal_set_message(t('Hi') . $name . '. You have successfully submitted the form!');
}

The above submit handler simply delivers the message using drupal_set_message api. $form_state contains the current state of the form, using which you can get the submitted value and process it as needed.

To define validation handler:

Like submit handler validation handler also be detected automatically by Drupal system. We just need to suffix the form function name with _form_validate.

/**
 * Validation handler for the mycustom_form
 */
function mycustom_form_validate($form, &$form_state) {
    $name = $form_state['values']['name'];
    if (strlen($name) < 3) {
        form_set_error('name', t("It doesn't look like your name. It's too short!!!"));
    }
}

In the above validation, we have checked if the given name contains at least 3 characters. 

We conclude that this post helps you to understand defining the custom form and accessing the form through menu callback.