Loader Widget

Categories: Widgets

Loader Widgetversion added: 1.2

Description: Handles the task of displaying the loading dialog when jQuery Mobile pulls in content via Ajax.

QuickNavExamples

Options

Methods

Events

The Loader Widget

The loader widget handles the task of displaying the loading dialog when jQuery Mobile pulls in content via Ajax. It can also be displayed manually for custom loading actions using the $.mobile.loading helper method (See the global method docs).

Theming

The loader widget uses the jQuery Mobile CSS framework to style its look and feel. If loader specific styling is needed, the following CSS class names can be used for overrides or as keys for the classes option:

  • ui-loader: Outermost container for loader widget. If textvisible option is used ui-loader-verbose class will be added. Additionally if textonly option is used then ui-loader-textonly class will added. In all other cases where text is not present ui-loader-default class will be added.
    • ui-loader-item: Span element of the loader representing the icon
    • ui-loader-header: Header element of the loader representing the text of the loader.

To configure the loading dialog globally the following settings can be defined on its prototype during the mobileinit event.

Below are the defaults:
1
2
3
4
5
6
 
$( document ).on( "mobileinit", function() {
  $.mobile.loader.prototype.options.text = "loading";
  $.mobile.loader.prototype.options.textVisible = false;
  $.mobile.loader.prototype.options.theme = "a";
  $.mobile.loader.prototype.options.html = "";
});

These defaults will only be superseded by the method params object described in the global method docs under $.mobile.loading.

1
2
3
4
5
6
 
$.mobile.loading( "show", {
  text: "foo",
  textVisible: true,
  theme: "z",
  html: ""
});

Options

classes 

Type: Object
Default: 
{
        "ui-loader": "ui-corner-all",
        "ui-loader-icon": "ui-icon-loading"
      }

Specify additional classes to add to the widget's elements. Any of classes specified in the Theming section can be used as keys to override their value. To learn more about this option, check out the learn article about the classes option.

Code examples:

Initialize the loader with the classes option specified, changing the theming for the ui-loader class:

1
2
3
4
5
 
$( ".selector" ).loader({
  classes: {
    "ui-loader": "highlight"
  }
});

Get or set a property of the classes option, after initialization, here reading and changing the theming for the ui-loader class:

1
2
3
4
5
 
// Getter
var themeClass = $( ".selector" ).loader( "option", "classes.ui-loader" );
 
// Setter
$( ".selector" ).loader( "option", "classes.ui-loader", "highlight" );

defaults 

Type: Boolean
Default: false
Seting this option to true indicates that other widgets options have default values and causes jQuery Mobile's widget autoenhancement code to omit the step where it retrieves option values from data attributes. This can improve startup time.

This option is also exposed as a data attribute: data-defaults="true".

Code examples:

Initialize the loader with the defaults option specified:

1
2
3
 
$( ".selector" ).loader({
  defaults: true
});

Get or set the defaults option, after initialization:

1
2
3
4
5
 
// Getter
var defaults = $( ".selector" ).loader( "option", "defaults" );
 
// Setter
$( ".selector" ).loader( "option", "defaults", true );

disabled 

Type: Boolean
Default: false
Disables the loader if set to true.

This option is also exposed as a data attribute: data-disabled="true".

Code examples:

Initialize the loader with the disabled option specified:

1
2
3
 
$( ".selector" ).loader({
  disabled: true
});

Get or set the disabled option, after initialization:

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).loader( "option", "disabled" );
 
// Setter
$( ".selector" ).loader( "option", "disabled", true );

html 

Type: string
Default: ""
If this is set to a non empty string value, it will be used to replace the entirety of the loader's inner html.
Code examples:

Initialize the loader with the html option specified:

1
2
3
 
$( ".selector" ).loader({
  html: "<span class='ui-icon ui-icon-loading'><img src='jquery-logo.png' /><h2>is loading for you ...</h2></span>"
});

Get or set the html option, after initialization:

1
2
3
4
5
 
// Getter
var html = $( ".selector" ).loader( "option", "html" );
 
// Setter
$( ".selector" ).loader( "option", "html", "<span class='ui-icon ui-icon-loading'><img src='jquery-logo.png' /><h2>is loading for you ...</h2></span>" );

text 

Type: string
Default: loading
Sets the text of the message.
Code examples:

Initialize the loader with the text option specified:

1
2
3
 
$( ".selector" ).loader({
  text: "Loading Page..."
});

Get or set the text option, after initialization:

1
2
3
4
5
 
// Getter
var text = $( ".selector" ).loader( "option", "text" );
 
// Setter
$( ".selector" ).loader( "option", "text", "Loading Page..." );

textVisible 

Type: boolean
Default: false
If true, the text value will be used under the spinner.
Code examples:

Initialize the loader with the textVisible option specified:

1
2
3
 
$( ".selector" ).loader({
  textVisible: true
});

Get or set the textVisible option, after initialization:

1
2
3
4
5
 
// Getter
var textVisible = $( ".selector" ).loader( "option", "textVisible" );
 
// Setter
$( ".selector" ).loader( "option", "textVisible", true );

textonly 

Type: boolean
Default: false
If true, the "spinner" image will be hidden when the message is shown.
Code examples:

Initialize the loader with the textonly option specified:

1
2
3
 
$( ".selector" ).loader({
  textonly: true
});

Get or set the textonly option, after initialization:

1
2
3
4
5
 
// Getter
var textonly = $( ".selector" ).loader( "option", "textonly" );
 
// Setter
$( ".selector" ).loader( "option", "textonly", true );

theme 

Type: String
Default: null, inherited from parent
Sets the color scheme (swatch) for the loader widget. It accepts a single letter from a-z that maps to the swatches included in your theme.

Possible values: swatch letter (a-z).

This option is also exposed as a data attribute: data-theme="b".

Code examples:

Initialize the loader with the theme option specified:

1
2
3
 
$( ".selector" ).loader({
  theme: "b"
});

Get or set the theme option, after initialization:

1
2
3
4
5
 
// Getter
var theme = $( ".selector" ).loader( "option", "theme" );
 
// Setter
$( ".selector" ).loader( "option", "theme", "b" );

Methods

checkLoaderPosition()Returns: jQuery (plugin only)

Check position of loader to see if it appears to be "fixed" to center.
  • This method does not accept any arguments.
Code examples:

Invoke the checkLoaderPosition method:

1
 
$( ".selector" ).loader( "checkLoaderPosition" );

fakeFixLoader()Returns: jQuery (plugin only)

For non-fixed supporting browsers. Position at y center (if scrollTop supported), above the activeBtn (if defined), or just 100px from top.
  • This method does not accept any arguments.
Code examples:

Invoke the fakeFixLoader method:

1
 
$( ".selector" ).loader( "fakeFixLoader" );

hide()Returns: jQuery (plugin only)

Hide the loader widget
  • This method does not accept any arguments.
Code examples:

Invoke the hide method:

1
 
$( ".selector" ).loader( "hide" );

loading()Returns: jQuery (plugin only)

Show or hide the loader message, which is configurable via $.mobile.loader prototype options as described in the widget docs or can be controlled via a params object.
  • This method does not accept any arguments.
Code examples:

Invoke the loading method:

1
 
$( ".selector" ).loader( "loading" );

resetHtml()Returns: jQuery (plugin only)

  • This method does not accept any arguments.
Code examples:

Invoke the resetHtml method:

1
 
$( ".selector" ).loader( "resetHtml" );

show()Returns: jQuery (plugin only)

  • This method does not accept any arguments.
Code examples:

Invoke the show method:

1
 
$( ".selector" ).loader( "show" );

Events

create( event, ui )Type: loadingcreate

Triggered when a loader widget is created.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the loader with the create callback specified:

1
2
3
 
$( ".selector" ).loader({
  create: function( event, ui ) {}
});

Bind an event listener to the loadingcreate event:

1
 
$( ".selector" ).on( "loadingcreate", function( event, ui ) {} );

Example:

Loader Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>loader demo</title>
  <link rel="stylesheet" href="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.css">
  <script src="//code.jquery.com/jquery-3.2.1.min.js"></script>
  <script src="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page1">
  <div role="main" class="ui-content">
    <div data-role="controlgroup">
      <button class="show-page-loading-msg" data-theme="b" data-textonly="false" data-textvisible="false" data-msgtext="" data-icon="arrow-r" data-iconpos="right">Default loader</button>
      <button class="show-page-loading-msg" data-theme="b" data-textonly="true" data-textvisible="true" data-msgtext="Text only loader" data-icon="arrow-r" data-iconpos="right">Text only</button>
      <button class="show-page-loading-msg" data-theme="b" data-textonly="false" data-textvisible="true" data-msgtext="Loading theme a" data-icon="arrow-r" data-iconpos="right">Theme a</button>
      <button class="show-page-loading-msg" data-theme="a" data-textonly="false" data-textvisible="true" data-msgtext="Loading theme b" data-icon="arrow-r" data-iconpos="right">Theme b</button>
      <button class="show-page-loading-msg" data-theme="b" data-textonly="true" data-textvisible="true" data-msgtext="Custom Loader" data-icon="arrow-r" data-html="<span class='ui-bar ui-overlay-a ui-corner-all'><img src='../resources/loader/jquery-logo.png' /><h2>is loading for you ...</h2></span>" data-iconpos="right">Custom HTML</button>
      <button class="hide-page-loading-msg" data-icon="delete" data-iconpos="right">Hide</button>
    </div>
  </div>
</div>
 
<script>
$(document).on( "click", ".show-page-loading-msg", function() {
  var $this = $( this ),
  theme = $this.jqmData( "theme" ) || $.mobile.loader.prototype.options.theme,
  msgText = $this.jqmData( "msgtext" ) || $.mobile.loader.prototype.options.text,
  textVisible = $this.jqmData( "textvisible" ) || $.mobile.loader.prototype.options.textVisible,
  textonly = !!$this.jqmData( "textonly" );
  html = $this.jqmData( "html" ) || "";
$.mobile.loading( 'show', {
  text: msgText,
  textVisible: textVisible,
  theme: theme,
  textonly: textonly,
  html: html
  });
})
.on( "click", ".hide-page-loading-msg", function() {
  $.mobile.loading( "hide" );
});
</script>
 
</body>
</html>

Demo: