Validate

Helps validate form fields and display the filling errors. The main principle: the addon only sends data to the server and shows errors, validation must necessarily occur on the server. Because this is the only way to make the validation of forms reliable and safe.

• Usage
• Settings
• Events
• Methods

Usage #

Here is a typical form that we will validate. Try clicking the Send button.

The validation of the form has several parts.

First, you need to specify the validation module in the data-kube attribute. In the form action attribute, you must specify the path to the server-side script that will check the data and return the result of the validation.

<form action="/validation/" method="post" data-kube="validate">
    <div class="form-item">
        <label>Email</label>
        <input type="email" name="email">
    </div>
    <div class="form-item is-buttons">
        <button class="button is-secondary">Send</button>
    </div>
</form>

The module is already ready for use and when you click Send button, the form will be sent to the server as POST data.

When the form has errors, inputs are automatically highlighted using the error class. If you need to output the error text, then you need to use an element with the ID consisting of the input name and the prefix -validation-error.

<form action="/validation/" method="post" data-kube="validate">
    <div class="form-item">
        <label>Email <span id="email-validation-error" class="is-hidden"></span></label>
        <input type="email" name="email">
    </div>
    <div class="form-item is-buttons">
        <button class="button is-secondary">Send</button>
    </div>
</form>

Now let's see what response is needed from the server to show the form errors. This is JSON, which has the error type and lists of the input names whose data contains an error. As you can see, if you do not want to show the error text, it's enough to set true for the input name.

// JSON Error Response
{
    "type": "error",
    "errors": {
        "country": "Please, select your country",
        "name": "Please, fill the name",
        "about": true,
        "check": true
    }
}

What if the form does not have errors? In this case, you can return any response from the server that will be parsed using the Response service. In the example below, the form does not contain errors. When it is sent, a response from the server says: hide the form and show the message about the successful sending of the form.

// The form
<form id="myform" action="/validation/" method="post" data-kube="validate">
    <div class="form-item">
        <label>Email</label>
        <input type="email" name="email">
    </div>
    <div class="form-item is-buttons">
        <button>Send</button>
    </div>
</form>

// The successful message
<div id="myform-message" class="is-hidden">
    <h4>Thank you! The form successfully sent.</h4>
</div>

// JSON Response
[
    {
        "type": "show",
        "data": {
            "#myform-message": true
        }
    },
    {
        "type": "hide",
        "data": {
            "#myform":true
        }
    }
]

Settings #

errorClass

Type: String

Default: 'is-error'

This option sets the class that will be added to the field containing the error.

<form action="/validation/" method="post" data-kube="validate" data-error-class="error">
    ...
</form>

send

Type: Boolean

Default: true

This setting turns off submit event on the form. That means that the form will not be sent to the server after the validation.

<form action="/validation/" method="post" data-kube="validate" data-send="false">
    ...
</form>

trigger

Type: Boolean String

Default: false

This setting sets the trigger button or link outside the form to send it for validation to the server.

<form action="/validation/" method="post" data-kube="validate" data-trigger="#mytrigger">
    ...
</form>

// trigger
<button id="mytrigger">Send form</button>

shortcut

Type: Boolean

Default: false

This option enable shortcut ctrl+s or cmd+s to send the form for validation to the server.

<form action="/validation/" method="post" data-kube="validate" data-shortcut="true">
    ...
</form>

progress

Type: Boolean

Default: false

This setting allows to show the progress bar when the form is sending for validation to the server.

<form action="/validation/" method="post" data-kube="validate" data-progress="true">
    ...
</form>

Events #

Catch events in your module:

(function($K)
{
    $K.add('module', 'mymodule', {
        init: function(app, context)
        {
            this.app = app;
        },
        // catch event
        onmessage: {
            validate: {
                success: function(sender)
                {
                    console.log('Validation is successfully!');
                }
            }
        }
    });
})(Kube);

Catch events from a specific form

Set an ID for the form:

<form id="myform" action="/validation/" method="post" data-kube="validate">
    ...
</form>

Or set data-name attribute:

<form data-name="myform" action="/validation/" method="post" data-kube="validate">
    ...
</form>

Catch events in your module by the specified ID or data-name:

(function($K)
{
    $K.add('module', 'mymodule', {
        init: function(app, context)
        {
            this.app = app;
        },
        // catch event
        onmessage: {
            validate: {
                error: function(sender)
                {
                    if (sender._id === 'myform')
                    {
                        console.log('There are errors of #myform validation.');
                    }
                }
            }
        }
    });
})(Kube);

Methods #

Use API inside modules

(function($K)
{
    $K.add('module', 'mymodule', {
        init: function(app, context)
        {
            this.app = app;
        },
        clearFormErrors: function()
        {
            // for all validated forms on the page
            this.app.api('validate.clear');

            // for specified form
            this.app.api('validate.myform.clear');
        }
    });
})(Kube);

Use API from outside

// for all validated forms on the page
<button onclick="$K.api('validate.clear');">Clear</button>

// for specified form
<button onclick="$K.api('validate.myform.clear');">Clear</button>