jquery-loading

Example of usage

Year	Numbers	Status	Another
2013	23,789.23	Finished	Good
2014	19,990.11	Open	Bad
2015	8,123.42	Open	Ugly

setInterval(function() {
  $('#example-table').loading('toggle');
}, 2000);

See more examples

Getting started

Install from bower:
```
$ bower install jquery-loading
```
Or download the source code on github.

Include jquery and jquery-loading in your page:

<script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
<script src="jquery.loading.js"></script>

Call the plugin in the element you want to add the loading state:
```
$("#some-element").loading();
```
(optional) If you want to use some default themes and styles (like the ones used on this page), include the CSS file:
```
<link href="jquery.loading.css" rel="stylesheet">
```
You don't need to include it if you are using a custom overlay element.

Motivation

The idea is to lock elements that are loading or working (in decorrence of an Ajax request, for example) while keeping the rest of the page available to the user.

Jquery-loading does that by adding an overlay on top of the loading element.

You can customize this overlay however you want or use our default themes. It's your call.

Basic usage

Starting

This div is always loading

Stopping

This div will stop loading if you click it

Toggling

This div is toggling the loading state

Full page loader

$('body').loading({
  stoppable: true
});

States and events

`loading.start`

Triggered when the loading state is started. Receives the loading object as parameter. Example:

$('#my-element').on('loading.start', function(event, loadingObj) {
  // do something whenever the loading state of #my-element is turned on
});

`loading.stop`

Triggered when the loading state is stopped. Receives the loading object as parameter. Example:

$('#my-element').on('loading.stop', function(event, loadingObj) {
  // do something whenever the loading state of #my-element is turned off
});

`loading.click`

Triggered when the overlay element is clicked. Receives the loading object as parameter. Example:

$('#my-element').on('loading.click', function(event, loadingObj) {
  // do something whenever the loading overlay of #my-element is clicked
});

Initializing

There is a shortcut to provide event handlers at initilization:

$('#my-element').loading({
  onStart: function(loadingObj) { ... },
  onStop: function(loadingObj) { ... },
  onClick: function(loadingObj) { ... }
});

The `:loading` selector

Use it to get elements with the loading state currently on.

$(':loading') // Get all the elements with the loading state on

$('#element').is(':loading') // Check if the '#element' is loading

Custom loading...

Customization

Custom overlay

This div has a custom overlay element

Custom animation

This div has a custom start / stop animation

Themes and default styles

You must include the dist/jquery.loading.css file in your page if you want to use the default themes. If you're working with a custom overlay element, the following options have no effect.

Light theme

This div has the light theme

Dark theme

This div has the dark theme

Custom message

This div has a custom loading message

Full list of options

Option	Default value	Comments
`overlay`	-	jQuery element to be used as overlay. If not informed, the plugin will create a default one
`message`	Loading...	Message to be rendered on the overlay content. Has no effect if a custom `ovelay` was informed
`theme`	light	Theme to be used for the `overlay` element. Some default themes are defined on the `jquery.loading.css` file (include it if you want to use the default themes). Has no effect if a custom `ovelay` was informed
`shownClass`	loading-shown	Class(es) to be applied to the overlay element when the loading state is started
`hiddenClass`	loading-hidden	Class(es) to be applied to the overlay element when the loading state is stopped
`stoppable`	false	Setting this option to true will make the loading state be stopped if the overlay element is clicked by the user. This option does *not* override the `onClick` option
`start`	true	Define whether to start or not the loading state when the plugin is initialized
`onStart`	`loading.overlay.fadeIn(150)`	Function to be executed when the loading state is started. Receives the loading object as parameter
`onStop`	`loading.overlay.fadeOut(150)`	Function to be executed when the loading state is stopped. Receives the loading object as parameter
`onClick`	-	Function to be executed when the overlay is clicked. Receives the loading object as parameter

Methods of Interest

Method	Return type	Description	Example
`jQuery.fn.loading`	`jQuery`	Initializes the plugin.	`$('#my-loading-element').loading({ ... })`
`jQuery.fn.Loading`	`Loading`	Return the internal plugin object associated to the jQuery element. Also initialize the plugin if this the first call using this target. Note that this function is different from the common `$.fn.loading` wich start the plugin and return a chainable jQuery object.	`$('#my-loading-element').Loading()`
`resize`	`jQuery`	Recalculate and apply new dimensions and position to the overlay, based on the state of the target element. Call this method if the the overlay is not being shown on the right position and/or dimensions.	`$(...).loading('resize')`
`start`	`jQuery`	Turn on the loading state of some element and trigger the `loading.start` event.	`$(...).loading('start')`
`stop`	`jQuery`	Turn off the loading state of some element and trigger the `loading.stop` event.	`$(...).loading('stop')`
`destroy`	`jQuery`	Remove from DOM the overlay element.	`$(...).loading('destroy')`
`toggle`	`jQuery`	Turn on or off the loading state of some element, depending of the current state, and trigger the respective event.	`$(...).loading('toggle')`
`$.Loading.setDefaults`	`-`	Extend the Loading plugin default options	`$.Loading.setDefaults({ theme: 'blurred', ... })`