Principle

Client ( your web browser ) send an Ajax request to server.
Then, server return an Json response respecting the good format.

See response format [ { 'action' : 'toast', 'params' : { text: "Lorem ipsum ...", ... } }, { 'action' : 'redirect', 'params' : { value : "umbrella-demo.dev/foo/bar" } }, ... ]

So, Client resolves each actions one by one, calling the right js function depending of action type :

  • action : toast → Toastify({text: 'Lorem ipsum'}).showToast()
  • action : redirect → window.location.href=...

Easiest way to return response in good format is to use the service JsResponseBuilder on Symfony controller.

data-xhr attribute

This attribute will override the default behaviour of link or form and send an Ajax request to server on click or on submit.

<a data-xhr="..." href>My link</a> <form data-xhr="..."></form>

data-spinner attribute

Display a spinner until the server responds.

<a data-xhr="..." data-spinner="true" href>My link</a>

data-confirm attribute

Display a confirm modal before call server.

<a data-xhr="..." data-confirm="Are you sure ?" href>My link</a>

data-xhr-id attribute

New

One ajax call can be performed at the same time if they have the same xhr-id.

<a data-xhr="..." data-xhr-id="my-id" href>My link</a>

JavaScript API

Instead of use data- attribute, you can use Javascript methods.

import AjaxUtils from 'umbrella_core/utils/AjaxUtils'; AjaxUtils.request({ 'method' : 'get', 'url' : 'umbrella.dev/foo/bar', 'confirm' : '...', 'xhr-id' : 'my-id', 'spinner' : true, 'data' : { ...}, ... // All $.ajax options are available }); AjaxUtils.get({...}); AjaxUtils.post({...});

To go further...

Error handling

If server return a response with an error HTTP status code, a toast will be displayed A specific message will be displayed if HTTP status code is 404 not found or 401 Unauthorized.

Handle action on JavaScript - jsResponseHandler

Each type of action is handled by a function. The following code handle action of type 'toast' :

/* globals umbrella */ umbrella.jsResponseHandler.registerAction('toast', (params) => { umbrella.Toast.show(params['type'], params['text'], params['title'], params['options']); });

So, it's easy to override default action or add new action.