remote validator

Perform remote checking via Ajax request

Options

Using with form field

The HTML attributes are used to set the validator options via the Declarative plugin

(* denotes a required option)

Name	HTML attribute	Type	Description
`crossDomain`	`data-fv-remote___cross-domain`	`Boolean`	Set it to `true` if you want to have a cross domain request. By default, it's set to `false`
`data`	`data-fv-remote___data`	`Object` or `Function`	The data sent to remote URL

You don't need to use the data option if there is only field, defined as field name, sent to the remote URL. If you want to use dynamic data, then use a callback as following:

data: function() {
    // Return an object
    return {
        key: value,
        otherKey: otherValue,
    };
}

When using data-fv-remote___data attribute, its value must be an encoded JSON string.

Name	HTML attribute	Type	Description
`headers`	`data-fv-remote___headers`	`Object`	Additonal headers that will be sent with the request
`message`	`data-fv-remote___message`	`String`	The error message
`name`	`data-fv-remote___name`	`String`	The name of field which need to validate
`method`	`data-fv-remote___method`	`String`	The method used to send data to back-end. It can be `GET` (the default value) or `POST`
`url` *	`data-fv-remote___url`	`String` or `Function`	The remote URL

If you want to use a dynamic URL, then use a callback as following:

url: function() {
    ...

    return 'the URL';
}

Name	HTML attribute	Type	Description
`validKey`	`data-fv-remote___valid-key`	`String`	The valid key. It's `valid` by default. This option is useful when connecting to external remote server or APIs provided by 3rd parties

The crossDomain and validKey options are mostly used when you need to connect to external API endpoint.

The remote URL has to return an encoded JSON of array containing the valid key (the key name can be changed by the validKey option):

{
    "valid": true
}
// or
{
    "valid": false
}

Using the ES6 module

// You might need to change the importing path
import { remote } from '/vendors/@form-validation/cjs/validator-remote';

const result = remote().validate({
    value: ...,
    options: {
        crossDomain: ...,
        data: ...,
        headers: ...,
        message: ...,
        name: ...,
        method: ...,
        url: ...,
        validKey: ...,
    },
});
/*
result is a Promise object which can be resolved by an object of
{
    valid: true or false,
    message: The error message,
    meta: The additional data returned by server
}
or can be rejected by an object of
{
    valid: false,
}
*/

Using the npm package

Install the validator package:

$ npm install @form-validation/validator-remote

Use the remote validator:

import { remote } from '@form-validation/validator-remote';

const result = remote().validate({
    value: ...,
    options: {
        crossDomain: ...,
        data: ...,
        headers: ...,
        message: ...,
        name: ...,
        method: ...,
        url: ...,
        validKey: ...,
    },
});

Basic example

The following example shows how to use a remote back-end to check if a given username is already taken or not.

<form id="registrationForm">
    <div class="cf mb2">
        <div class="fl w-100">
            <div class="fl w-25 pa2">Username</div>
            <div class="fl w-50">
                <input type="text" name="username" class="input-reset ba b--black-20 pa2 mb2 db w-100" />
            </div>
        </div>
    </div>
</form>

<script>
    document.addEventListener('DOMContentLoaded', function (e) {
        FormValidation.formValidation(document.getElementById('registrationForm'), {
            fields: {
                username: {
                    message: 'The username is not valid',
                    validators: {
                        // The validator will create an Ajax request
                        // sending { username: 'its value' } to the back-end
                        remote: {
                            message: 'The username is not available',
                            method: 'POST',
                            url: '/path/to/backend/',
                        },
                    },
                },
            },
            plugins: {
                trigger: new FormValidation.plugins.Trigger(),
                tachyons: new FormValidation.plugins.Tachyons(),
                submitButton: new FormValidation.plugins.SubmitButton(),
                icon: new FormValidation.plugins.Icon({
                    valid: 'fa fa-check',
                    invalid: 'fa fa-times',
                    validating: 'fa fa-refresh',
                }),
            },
        });
    });
</script>

The back-end then will determine if the username is available or not, and finally returns a JSON {"valid": "true"} or {"valid": "false"}. The code bellow demonstrates a simple back-end written in PHP:

<?php
// Get the username from request
$username = $_POST['username'];

// Check its existence (for example, execute a query from the database) ...
$isAvailable = true; // or false

// Finally, return a JSON
echo json_encode(array(
    'valid' => $isAvailable,
));

Sending static data example

For example, there is same back-end for validating both username and email address. The back-end uses additional parameter named type to determine which field is going to be validated.

<form id="signupForm">
    <div class="cf mb2">
        <div class="fl w-100">
            <div class="fl w-25 pa2">Username</div>
            <div class="fl w-50">
                <input type="text" name="username" class="input-reset ba b--black-20 pa2 mb2 db w-100" />
            </div>
        </div>
    </div>

    <div class="cf mb2">
        <div class="fl w-100">
            <div class="fl w-25 pa2">Email</div>
            <div class="fl w-50">
                <input type="text" name="email" class="input-reset ba b--black-20 pa2 mb2 db w-100" />
            </div>
        </div>
    </div>
</form>

<script>
    document.addEventListener('DOMContentLoaded', function (e) {
        FormValidation.formValidation(document.getElementById('signupForm'), {
            fields: {
                username: {
                    message: 'The username is not valid',
                    validators: {
                        // Send { username: 'its value', type: 'username' } to the back-end
                        remote: {
                            data: {
                                type: 'username',
                            },
                            message: 'The username is not available',
                            method: 'POST',
                            url: '/path/to/backend/',
                        },
                    },
                },
                email: {
                    message: 'The email address is not valid',
                    validators: {
                        // Send { email: 'its value', type: 'email' } to the back-end
                        remote: {
                            data: {
                                type: 'email',
                            },
                            message: 'The email is not available',
                            method: 'POST',
                            url: '/path/to/backend/',
                        },
                    },
                },
            },
            plugins: {
                trigger: new FormValidation.plugins.Trigger(),
                tachyons: new FormValidation.plugins.Tachyons(),
                submitButton: new FormValidation.plugins.SubmitButton(),
                icon: new FormValidation.plugins.Icon({
                    valid: 'fa fa-check',
                    invalid: 'fa fa-times',
                    validating: 'fa fa-refresh',
                }),
            },
        });
    });
</script>

The code bellow demonstrates a simple back-end written in PHP:

<?php
// Determine which field you want to check its existence
$isAvailable = true;

switch ($_POST['type']) {
    case 'email':
        $email = $_POST['email'];
        // Check the email existence ...
        $isAvailable = true; // or false
        break;

    case 'username':
    default:
        $username = $_POST['username'];
        // Check the username existence ...
        $isAvailable = true; // or false
        break;
}

// Finally, return a JSON
echo json_encode(array(
    'valid' => $isAvailable,
));

Sending dynamic data example

For instance, the registration form need to validate both the username and emails.

<form id="regForm">
    <div class="cf mb2">
        <div class="fl w-100">
            <div class="fl w-25 pa2">Username</div>
            <div class="fl w-50">
                <input type="text" name="username" class="input-reset ba b--black-20 pa2 mb2 db w-100" />
            </div>
        </div>
    </div>

    <div class="cf mb2">
        <div class="fl w-100">
            <div class="fl w-25 pa2">Email</div>
            <div class="fl w-50">
                <input type="text" name="email" class="input-reset ba b--black-20 pa2 mb2 db w-100" />
            </div>
        </div>
    </div>

    <div class="cf mb2">
        <div class="fl w-100">
            <div class="fl w-25 pa2">Password</div>
            <div class="fl w-50">
                <input type="password" name="password" class="input-reset ba b--black-20 pa2 mb2 db w-100" />
            </div>
        </div>
    </div>
</form>

<script>
    document.addEventListener('DOMContentLoaded', function (e) {
        const form = document.getElementById('regForm');
        FormValidation.formValidation(form, {
            fields: {
                username: {
                    message: 'The username is not valid',
                    validators: {
                        remote: {
                            url: '/path/to/backend/',
                            // Send { username: 'its value', email: 'its value' } to the back-end
                            data: function () {
                                return {
                                    email: form.querySelector('[name="email"]').value,
                                };
                            },
                            message: 'The username is not available',
                            type: 'POST',
                        },
                    },
                },
                email: {
                    validators: {
                        remote: {
                            url: '/path/to/backend/',
                            // Send { email: 'its value', username: 'its value' } to the back-end
                            data: function () {
                                return {
                                    email: form.querySelector('[name="username"]').value,
                                };
                            },
                            message: 'The email is not available',
                            type: 'POST',
                        },
                    },
                },
            },
            plugins: {
                trigger: new FormValidation.plugins.Trigger(),
                tachyons: new FormValidation.plugins.Tachyons(),
                submitButton: new FormValidation.plugins.SubmitButton(),
                icon: new FormValidation.plugins.Icon({
                    valid: 'fa fa-check',
                    invalid: 'fa fa-times',
                    validating: 'fa fa-refresh',
                }),
            },
        });
    });
</script>

Overriding name example

By default, it will be set as the name of field. You can override the name option by using the data-fv-remote___name attribute. Here are two cases which you might need to use this attribute.

Using different names for same field

For example, the Sign up and Profile forms use the same back-end URL to validate the email address which is declared with different name. In this case, use the same data-fv-remote___name attribute and the back-end will get the same data key.

Remember to use the Declarative plugin to turn on the validator options with the equivalent HTML attributes

<!-- In the signup form, the email address field is named as "login" -->
<form id="signForm" class="form-horizontal">
    <div class="cf mb2">
        <div class="fl w-100">
            <div class="fl w-25 pa2">Email</div>
            <div class="fl w-50">
                <input type="text" name="login" data-fv-remote___name="email" class="input-reset ba b--black-20 pa2 mb2 db w-100" />
            </div>
        </div>
    </div>
</form>

<!-- In the edit profile form, the email address field is named as "email" -->
<form id="profileForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-lg-3 control-label">Email</label>
        <div class="col-lg-5">
            <input type="text" class="form-control" name="email" data-fv-remote___name="email" />
        </div>
    </div>
</form>

Using same backend for different fields

Assume that the profile form asks you to update multiple email address (primary, secondary, for example). These emails will be validated by the same backend. In this case, just use the same data-fv-remote___name attribute for these email address fields.

<form id="demoForm" class="form-horizontal">
    <div class="cf mb2">
        <div class="fl w-100">
            <div class="fl w-25 pa2">Primary email</div>
            <div class="fl w-50">
                <input type="text" name="primary_email" data-fv-remote___name="email" class="input-reset ba b--black-20 pa2 mb2 db w-100" />
            </div>
        </div>
    </div>

    <div class="cf mb2">
        <div class="fl w-100">
            <div class="fl w-25 pa2">Secondary email</div>
            <div class="fl w-50">
                <input type="text" name="secondary_email" data-fv-remote___name="email" class="input-reset ba b--black-20 pa2 mb2 db w-100" />
            </div>
        </div>
    </div>
</form>

Changelog

v2.2.0

The validator builds an incorrect URL when using the GET method

v2.1.0

The validator doesn't work properly if the message property isn't defined

v2.0.0

Add the npm package
The validator sends a request to an incorrect URL if the url has a query string

v1.0.1

Fix an issue that the remote validator and FormValidation.utils.fetch() method don't send the correct data for POST request

regexp validator rtn validator