Configuring Form Validation Error Tracking

Our form validation error reporting allows to you see which form validation errors are being seen by users most often over a particular time period. You can access this by going to Analyze > Technical > Form Errors from the navigation bar.

There are two ways to configure form validation error reporting, both of which are summarised below. The first method is using inline error tagging, which requires the addition of attributes within the HTML of your website where form errors are triggered, while the second method requires the creation of a field error callback, which needs to be implemented within the DXA reporting application.

Inline error tagging

Inline Error Tagging allows you to add attributes to the relevant fields or error messages to tag form validation errors and share these with DXA. This can be achieved using the data-di-field-error and/or data-di-field-error-for.

The attribute data-di-field-error needs to be added to the relevant errored field and should only be added when the error has taken place. This attribute helps identify when a field has an error, as long as the value is not set to "false" or "0". You can either leave the attribute blank and add the data-di-field-error-for attribute to the error messages, more information below, or you add the error message directly into the data-di-field-error attribute if required; this is typically advised for fields that only return one possible error. An example of this can be seen below:

<input type="text" id="FirstName" data-di-field-error="Please enter your first name.">

This will return "Please enter your first name" to the Form Validation Error Report.

For fields with dynamic errors, you can use the data-di-field-error-for attribute. This attribute requires the field in question to have a valid HTML ID or a data-di-field-id, and the field in question to have the data-di-field-error attribute added to it. An example of this can be seen below. If an error has a data-di-field-error-for attribute, but the field that it is referencing does not have a data-di-field-error, this will not be classed as errored.

<label>
        First name: <input type="text" id="first_name" data-di-field-error>
        <span class="error" data-di-field-error-for="first_name">First name must be provided</span>
</label>

Field error callback

The field error callback requires custom configuration in the form of a JavaScript function. This should be configured to ensure that the relevant errors of fields within a form are returned to DXA. This needs to be added to the Field Error Callback field in Form Settings.

The below shows an example form including an error for the "First name" field:

<form action="submit.php" method="POST" id="contact">
    <label>
        First name: <input type="text" name="first_name">
        <span class="error">First name must be provided</span>
    </label>
    <label>
        Last name: <input type="text" name="last_name" />
    </label>
    <input type="submit" value="Submit" />
</form>

While the below code shows how a field error callback would be written for this, along with comments to explain how this has been written:

function (field) {
    // Locate the error element by finding the first sibling with a "error" class
    var error = field.parentNode ? field.parentNode.querySelector('.error') : false;

    // If no error element exists, end the function by returning false
    if(!error) return false;

    // If an error exists and has text, trim the text and return the message
    return error.innerText ? error.innerText.trim() : false;
}