The App.Helpers.Loaders helpers start and stop loaders for the entire page or specific elements.
Element loaders are only available outside the script sandbox.
Types of Loaders
Loaders can be attached to the entire page, elements, or to the mouse cursor.
- Page Loaders appear as a loading bar across the top of the screen.
- Element Loaders replace the contents of an element (like a link or button) with a spinning cursor.
- Cursor Loaders replace the mouse cursor with a loading icon on desktop computers. This is automatically converted to a page loader on mobile devices.
App.Helpers.Loaders.start(element = null, promise = null)
This method is also available as App.start_loader() for convenience.
The start method accepts a number of different argument types. It generates an appropriate loader when passed a Promise, Event, JavaScript or jQuery Element, Window, or nothing at all. It also accepts arrays of any of the listed types.
If this method is called with no parameters, or the first argument is a Promise, window, or document body, it calls App.Helpers.Loaders.start_page().
App.start_loader();
App.start_loader(Promise.resolve());
App.start_loader(window);
App.start_loader(document.body);
If the first parameter is an Event, it will generate an element loader for the event's currentTarget or target.
App.start_loader(event);
If the first parameter is a JavaScript or jQuery Element, the element's contents will be temporarily replaced with a spinning loader icon, until App.Helpers.Loaders.finish is called on the element.
App.start_loader(document.querySelector(".button"));
App.start_loader($(".button"));
If the second parameter is a Promise, the loader will be finished when it resolves or rejects.
App.start_loader(event, Promise.resolve());
App.Helpers.Loaders.start_page()
Add a loading bar across the top of the page.
App.Helpers.Loaders.start_page();
App.Helpers.Loaders.start_cursor(element = null)
Change the mouse cursor to a loading icon. If an element parameter is passed, the cursor will only appear when the mouse hovers over the element.
On mobile devices, this will generate a page loader instead.
App.Helpers.Loaders.start_cursor();
App.Helpers.Loaders.start_cursor(document.querySelector(".button"));
App.Helpers.Loaders.finish(element = null)
This method is also available as App.finish_loader() for convenience.
Removes any loaders on the page or element provided.
The finish method accepts most of the same arguments that start does. It can be passed an Event, JavaScript or jQuery Element, Window, or nothing at all.
If this method is called with no parameters, or the first argument is a window or document body, it calls App.Helpers.Loaders.finish_page().
App.finish_loader();
App.finish_loader(window);
App.finish_loader(document.body);
If the first parameter is an Event, it will finish element loaders for the event's currentTarget or target.
App.finish_loader(event);
If the first parameter is a JavaScript or jQuery Element, any loaders on the elements will be removed.
App.finish_loader(document.querySelector(".button"));
App.finish_loader($(".button"));
App.Helpers.Loaders.finish_page()
Removes the loading bar at the top of the page.
App.Helpers.Loaders.finish_page();
App.Helpers.Loaders.finish_cursor(element = null)
Change the mouse cursor back to the default. If an element parameter is passed, the cursor will only be reset for the element.
On mobile devices, this will remove any page loaders instead.
App.Helpers.Loaders.finish_cursor();
App.Helpers.Loaders.finish_cursor(document.querySelector(".button"));
App.Helpers.Loaders.loading(element = null)
This method is also available as App.loading() for convenience.
Checks if the page or element provided is currently loading.
The loading method accepts most of the same arguments that start does. It can be passed an Event, JavaScript or jQuery Element, Window, or nothing at all.
If this method is called with no parameters, or the argument is a window or document body, it checks if the entire page is loading.
App.loading();
App.loading(window);
App.loading(document.body);
If the argument is an Event, it will check element loaders for the event's currentTarget or target.
App.loading(event);
If the argument is a JavaScript or jQuery Element, it will check for any loaders on the elements.
App.loading(document.querySelector(".button"));
App.loading($(".button"));
Examples
Below are basic usage examples for starting and finishing loaders of the same type.
App.start_loader();
App.finish_loader();
// Adds a page loader for 1 second
var promise = new Promise(function(resolve, reject) {
setTimeout(function() { resolve() }, 1000);
});
App.start_loader(promise);
var element = document.querySelector(".button");
element.addEventListener("click", function(event) {
if (App.loading(event)) { return }
App.start_loader(event);
// Long-running code or request
App.finish_loader(event);
});
var element = document.querySelector(".button");
App.start_loader(element);
App.finish_loader(element);