ajax-extras.md

Extra Features

• Loading indicator
• Form validation
  • Throwing a validation error
  • Displaying error messages
  • Displaying errors with fields
• Loading button
• Flash messages
• Usage example

When using the AJAX framework, you have the option to specify the extras suffix which includes additional StyleSheet and JavaScript files. These features are useful when working with AJAX requests in frontend CMS pages.

{% framework extras %}

Loading indicator

The first feature you should notice is a loading indicator that is displayed on the top of the page when an AJAX request runs. The indicator hooks in to global events used by the AJAX framework.

When an AJAX request starts the ajaxPromise event is fired that displays the indicator and puts the mouse cursor in a loading state. The ajaxFail and ajaxDone events are used to detect when the request finishes, where the indicator is hidden again.

Form validation

You may specify the data-request-validate attribute on a form to enable validation features.

<form
    data-request="onSubmit"
    data-request-validate>
    <!-- ... -->
</form>

Throwing a validation error

In the server side AJAX handler you may throw a validation exception using the ValidationException class to make a field invalid, where the first argument is an array. The array should use field names for the keys and the error messages for the values.

function onSubmit()
{
    throw new ValidationException(['name' => 'You must give a name!']);
}

NOTE: You can also pass an instance of the validation service as the first argument of the exception.

Displaying error messages

Inside the form, you may display the first error message by using the data-validate-error attribute on a container element. The content inside the container will be set to the error message and the element will be made visible.

<div data-validate-error></div>

To display multiple error messages, include an element with the data-message attribute. In this example the paragraph tag will be duplicated and set with content for each message that exists.

<div class="alert alert-danger" data-validate-error>
    <p data-message></p>
</div>

To add custom classes on AJAX invalidation, hook into the ajaxInvalidField and ajaxPromise JS events.

$(window).on('ajaxInvalidField', function(event, fieldElement, fieldName, errorMsg, isFirst) {
    $(fieldElement).closest('.form-group').addClass('has-error');
});

$(document).on('ajaxPromise', '[data-request]', function() {
    $(this).closest('form').find('.form-group.has-error').removeClass('has-error');
});

Displaying errors with fields

Alternatively, you can show validation messages for individual fields by defining an element that uses the data-validate-for attribute, passing the field name as the value.

<!-- Input field -->
<input name="phone" />

<!-- Validation message for the field -->
<div data-validate-for="phone"></div>

If the element is left empty, it will be populated with the validation text from the server. Otherwise you can specify any text you like and it will be displayed instead.

<div data-validate-for="phone">
    Oops.. phone number is invalid!
</div>

Loading button

When any element contains the data-attach-loading attribute, the CSS class wn-loading will be added to it during the AJAX request. This class will spawn a loading spinner on button and anchor elements using the :after CSS selector.

<form data-request="onSubmit">
    <button data-attach-loading>
        Submit
    </button>
</form>

<a
    href="#"
    data-request="onDoSomething"
    data-attach-loading>
    Do something
</a>

Flash messages

Specify the data-request-flash attribute on a form to enable the use of flash messages on successful AJAX requests.

<form
    data-request="onSuccess"
    data-request-flash>
    <!-- ... -->
</form>

Combined with use of the Flash facade in the event handler, a flash message will appear after the request finishes.

function onSuccess()
{
    Flash::success('You did it!');
}

To remain consistent with AJAX based flash messages, you can render a standard flash message when the page loads by placing this code in your page or layout.

{% flash %}
    <p
        data-control="flash-message"
        class="flash-message fade {{ type }}"
        data-interval="5">
        {{ message }}
    </p>
{% endflash %}

Usage example

Below is a complete example of form validation. It calls the onDoSomething event handler that triggers a loading submit button, performs validation on the form fields, then displays a successful flash message.

<form
    data-request="onDoSomething"
    data-request-validate
    data-request-flash>

    <div>
        <input name="name" />
        <span data-validate-for="name"></span>
    </div>

    <div>
        <input name="email" />
        <span data-validate-for="email"></span>
    </div>

    <button data-attach-loading>
        Submit
    </button>

    <div class="alert alert-danger" data-validate-error>
        <p data-message></p>
    </div>

</form>

The AJAX event handler looks at the POST data sent by the client and applies some rules to the validator. If the validation fails, a ValidationException is thrown, otherwise a Flash::success message is returned.

function onDoSomething()
{
    $data = post();

    $rules = [
        'name' => 'required',
        'email' => 'required|email',
    ];

    $validation = Validator::make($data, $rules);

    if ($validation->fails()) {
        throw new ValidationException($validation);
    }

    Flash::success('Jobs done!');
}