Drupal 8 Custom Forms Inline Errors Made Easy

All,

Here is my solution to implementing inline errors in your custom form for server-side validations. In summary, I am going to use a hidden form field to store error messages that were generated within the validateForm method and then use JQuery to parse and output the results. The sample code are snippets of actual code of a module I created. It has been heavily edited for demonstrative purposes.

Below is the sample form code. While I am using text boxes, the solution does work on other form elements. You may need to adjust the jQuery script depending on your theme.

    public function buildForm (array $form, FormStateInterface $form_state) { 

        // Embed my jQuery script 
        $form['#attached']['library'] = array(
            'my_module/my_module_inline_errors',
        );

        // Field Test 1
        $form['field_test_1'] = array(
            '#type' => 'textfield',
            '#title' => t('Field 1'),
        );

        // Field Test 2
        $form['field_test_2'] = array(
            '#type' => 'textfield',
            '#title' => t('Field 2'),
        );

        // Field Test 3
        $form['field_test_3'] = array(
            '#type' => 'textfield',
            '#title' => t('Field 3'),
        );

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

      return $form ;
    }
    
    public function validateForm (array &$form, FormStateInterface $form_state) {
        // INIT
        $values = $form_state->getValues();

        // Validate
        if ( $values['field_test_1']  == '' ) {
            $form_state->setErrorByName('field_test_1', t('Error 1'));
        }

        if ( $values['field_test_2']  == '' ) {
            $form_state->setErrorByName('field_test_2', t('Error 2'));
        }

        if ( $values['field_test_3']  == '' ) {
            $form_state->setErrorByName('field_test_3', t('Error 3'));
        }

        // If validation errors, save them to the hidden form field in JSON format
        if ( $errors = $form_state->getErrors() ) {
            $form['my_module_error_msgs']['#value'] = json_encode($errors);
        }
        
        return;
    }

As you can see, the code is very straightforward. The buildForm is business as usual in that we are defining 4 form elements (3 text boxes and 1 submit button). Note that we are also attaching our jQuery script which will be discussed later on

Within the validateForm method I am checking to see if any errors were previously detected. If so then we retrieve the associative array of errors from $form_state, transform it into a JSON string and save it in the hidden form field. Note that the array keys will be the field names and the values will be the error messages.

In the next section of code, we are going to automatically alter the form using hook_form_alter.

/**
  * Implments hook_form_alter
  **/
function my_module_form_alter (&$form, FormStateInterface &$form_state) {
    // Create hidden field to store error messages
    $form['my_module_error_msgs']['#type'] = 'hidden';
    
    // Automatically add ID attribute for each form element
    foreach ($form as $key => $frm) {
	if ( stristr($key, 'field_' ) ) {
	     $form[$key]['#id'] = $key; 
	}
    }
}

So here I am taking advantage of hook_form_alter to automate a few things that help simplify the buildForm code. This also allows me to create other custom forms with very minimal code additions.

Note that I like to standardize on a naming convention for my form field names, hence they all begin with the prefix "field_". The purpose of the foreach loop is to overwrite the Drupal default ID attribute with the element name and again minimizes the code within buildForm. As you will see in the next example, using this naming convention has its advantages.

// my_module_inline_errors.js
jQuery(document).ready(function($){

    var form_errors = $('input[name="my_module_error_msgs"]').val();
    if (form_errors) {
        form_errors = JSON.parse(form_errors);
        var keys = Object.keys(form_errors);
        var count = Object.keys(form_errors).length
        for (i = 0; i < count; i++) {
            msg = form_errors[keys[i]];
            $('#' + keys[i]).after('<div class="my-module-inline-error">' + msg + '</div>' );
        }
    }
});

And so here is where the magic happens. When this JQuery script is loaded, it will check to see if any error messages have been deposited in the hidden field. If found the JSON string is converted to a JSON object. By parsing through the entire array, I can identify the invalid field and append the error message at the end of the input field. The CSS class can be customized to control proper positioning and highlighting.

My JQuery selector locates each field by ID which as you will recall, I purposely set this value in hook_form_alter. This method of searching in jQuery is much more efficient than searching via the name attribute (i.e $('input[name="field_name"]')). Regardless, you can choose whatever method works for you.

So the overall advantages for me is simplicity. Previously I tried to store my errors messages in a session variable but this will not work within the life cycle of the FormAPI. The idea was within buildForm to fetch the error messages from the session variable and output them within buildForm. The problem appeared to be with the form cache and my messages would only appear if I refresh the page. I have previously posted this question seeking help on this forum. I am fully aware there is an ongoing project to develop Inline Errors for Drupal 8 as a module and I have tried to contact the project members but to no avail.

Anyway I am very happy with this and would love to hear your comments and feedback,

Cheers