Information for: DEVELOPERS   PARTNERS

Build a new form

Fast Track to Drupal 8 Coding – Back to intro
Previous lesson - Alter an existing simple form
Next lesson – Add a field to an existing form

Lesson Goal

Build a new form that validates entries (in this example, the title must be at least 15 characters in length) and also provides a submission function.

Implementation Method

Drupal Version Method
Drupal 7 Use hook_menu and drupal_get_form
Drupal 8 Use routing.yml and FormBase class

Drupal 7 method

Create a lotus.info file to register your module, with the following contents:

name = Lotus
description = Build a simple form.
package = Custom
core = 7.x

Register a menu link using hook_menu. To this, add the following code in the lotus.module file:

/**
* Implements hook_menu().
*/
function lotus_menu() {
  $items['simple-form'] = array(
    'title' => 'Simple Form',
    'description' => 'Build a simple form',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('lotus_simple_form'),
    'access arguments' => array('access content'),
  );
  return $items;

}

Create a form by calling drupal_get_form and using Form API. To build the form, add the following code to the lotus.module file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 /**
 * Creates a simple form. Page callback.
 */
 function lotus_simple_form($form, &$form_state) {
   $form['title'] = array(
     '#type' => 'textfield',
     '#title' => t('Title'),
     '#description' => t('Title must be at least 15 characters in length.'),
     '#required' => TRUE,
   );
   // Group submit handlers in an actions element with a key of "actions" so
   // that it gets styled correctly, and so that other modules may add actions
   // to the form. This is not required, but is convention.
   $form['actions'] = [
     '#type' => 'actions',
   ];

   // Add a submit button that handles the submission of the form.
   $form['actions']['submit'] = [
     '#type' => 'submit',
     '#value' => t('Submit'),
   ];

   return $form;
 }

 /**
 * Validation for title. Title must be at least 15 characters in length.
 */
 function lotus_simple_form_validate($form, &$form_state) {
   $title = $form_state['values']['title'];
   if (strlen($title) < 15) {
     // Set an error for the form element with a key of "title".
     form_set_error('title', t('The title must be at least 15 characters long.'));
   }
 }

 /**
 * Display a message after successful form submit.
 */
 function lotus_simple_form_submit($form, &amp;$form_state) {
   $title = $form_state['values']['title'];
   drupal_set_message(t('You specified a title of %title.', ['%title' => $title]));
 }

Drupal 8 method

  1. Create a lotus.info.yml file with the following contents:

    name: Lotus
    description: Build a basic form.
    type: module
    core: 8.x
    
  2. Register a route by adding the following code to the lotus.routing.yml file:

    lotus.simple_form:
      path: '/simple-form'
      defaults:
        _form:  '\Drupal\lotus\Form\SimpleForm'
        _title: 'Simple Form Example'
      requirements:
        _permission: 'access content'
    
  3. Create a form class extending FormBase to build your form. To do this, add the following code to the lotus/src/Form/SimpleForm.php file:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    <?php
    namespace Drupal\lotus\Form;
    
    use Drupal\Core\Form\FormBase;
    use Drupal\Core\Form\FormStateInterface;
    
    /**
    * Implements a simple form.
    */
    class SimpleForm extends FormBase {
    
      /**
      * Build the simple form.
      *
      * @param array $form
      *   Default form array structure.
      * @param FormStateInterface $form_state
      *   Object containing current form state.
      */
      public function buildForm(array $form, FormStateInterface $form_state) {
    
        $form['title'] = [
          '#type' => 'textfield',
          '#title' => $this->t('Title'),
          '#description' => $this->t('Title must be at least 15 characters in length.'),
          '#required' => TRUE,
        ];
    
        // Group submit handlers in an actions element with a key of "actions" so
        // that it gets styled correctly, and so that other modules may add actions
        // to the form. This is not required, but is convention.
        $form['actions'] = [
          '#type' => 'actions',
        ];
    
        // Add a submit button that handles the submission of the form.
        $form['actions']['submit'] = [
          '#type' => 'submit',
          '#value' => $this->t('Submit'),
        ];
    
        return $form;
      }
    
      /**
      * Getter method for Form ID.
      *
      * The form ID is used in implementations of hook_form_alter() to allow other
      * modules to alter the render array built by this form controller.  it must
      * be unique site wide. It normally starts with the providing module's name.
      *
      * @return string
      *   The unique ID of the form defined by this class.
      */
      public function getFormId() {
        return 'lotus_simple_form';
      }
    
      /**
      * Implements form validation.
      *
      * The validateForm method is the default method called to validate input on
      * a form.
      *
      * @param array $form
      *   The render array of the currently built form.
      * @param FormStateInterface $form_state
      *   Object describing the current state of the form.
      */
      public function validateForm(array &amp;$form, FormStateInterface $form_state) {
        $title = $form_state->getValue('title');
        if (strlen($title) < 15) {
          // Set an error for the form element with a key of "title".
          $form_state->setErrorByName('title', $this->t('The title must be at least 15 characters long.'));
        }
      }
    
      /**
      * Implements a form submit handler.
      *
      * The submitForm method is the default method called for any submit elements.
      *
      * @param array $form
      *   The render array of the currently built form.
      * @param FormStateInterface $form_state
      *   Object describing the current state of the form.
      */
      public function submitForm(array &amp;$form, FormStateInterface $form_state) {
        /*
        * This would normally be replaced by code that actually does something
        * with the title.
        */
        $title = $form_state->getValue('title');
        drupal_set_message($this->t('You specified a title of %title.', ['%title' => $title]));
      }
    
    }