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. The loader dialog was previously configured globally with three settings $.mobile.loadingMessage, $.mobile.loadingMessageTextVisible, and $.mobile.loadingMessageTheme which are now deprecated. In addition to the methods for showing and hiding, $.mobile.showPageLoadingMsg and $.mobile.hidePageLoadingMsg are also deprecated.

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).

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 settings will be overridden by the deprecated settings to preserve backward compatibility. Once the deprecated settings are removed 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

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 loading with the html option specified:

1
2
3
 
$( ".selector" ).loading({
  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" ).loading( "option", "html" );
 
// Setter
$( ".selector" ).loading( "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 loading with the text option specified:

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

Get or set the text option, after initialization:

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

textVisible 

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

Initialize the loading with the textVisible option specified:

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

Get or set the textVisible option, after initialization:

1
2
3
4
5
 
// Getter
var textVisible = $( ".selector" ).loading( "option", "textVisible" );
 
// Setter
$( ".selector" ).loading( "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 loading with the textonly option specified:

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

Get or set the textonly option, after initialization:

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

theme 

Type: string
Default: a
Sets the color scheme (swatch) for the loading message. It accepts a single letter from a-z that maps to the swatches included in your theme.
Code examples:

Initialize the loading with the theme option specified:

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

Get or set the theme option, after initialization:

1
2
3
4
5
 
// Getter
var theme = $( ".selector" ).loading( "option", "theme" );
 
// Setter
$( ".selector" ).loading( "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" ).loading( "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" ).loading( "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" ).loading( "hide" );

hidePageLoadingMsg()Returns: jQuery (plugin only)

Deprecated in 1.2 - use $.mobile.loading( "hide" ) instead, see examples above

Hide the loader message, which is configurable via $.mobile.loadingMessage.
1
2
 
//hide the page loader
$.mobile.hidePageLoadingMsg();
  • This method does not accept any arguments.
Code examples:

Invoke the hidePageLoadingMsg method:

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

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" ).loading( "loading" );

resetHtml()Returns: jQuery (plugin only)

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

Invoke the resetHtml method:

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

show()Returns: jQuery (plugin only)

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

Invoke the show method:

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

showPageLoadingMsg()Returns: jQuery (plugin only)

Deprecated in 1.2 - use $.mobile.loading( "show" ) instead, see examples above

Show the loader message, which is configurable via $.mobile.loadingMessage.
1
2
3
4
5
 
//cue the page loader
$.mobile.showPageLoadingMsg();
 
//use theme swatch "b", a custom message, and no spinner
$.mobile.showPageLoadingMsg( "b", "This is only a test", true );
  • This method does not accept any arguments.
Code examples:

Invoke the showPageLoadingMsg method:

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

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 loading with the create callback specified:

1
2
3
 
$( ".selector" ).loading({
  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
49
50
51
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>loading demo</title>
  <link rel="stylesheet" href="//code.jquery.com/mobile/1.3.2/jquery.mobile-1.3.2.min.css">
  <script src="//code.jquery.com/jquery-1.9.1.min.js"></script>
  <script src="//code.jquery.com/mobile/1.3.2/jquery.mobile-1.3.2.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page1">
  <div data-role="content">
    <div data-role="controlgroup">
      <button class="show-page-loading-msg" data-theme="a" 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="a" 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="a" 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="b" 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="c" data-textonly="false" data-textvisible="true" data-msgtext="Loading theme c" data-icon="arrow-r" data-iconpos="right">Theme c</button>
      <button class="show-page-loading-msg" data-theme="d" data-textonly="false" data-textvisible="true" data-msgtext="Loading theme d" data-icon="arrow-r" data-iconpos="right">Theme d</button>
      <button class="show-page-loading-msg" data-theme="e" data-textonly="false" data-textvisible="true" data-msgtext="Loading theme e" data-icon="arrow-r" data-iconpos="right">Theme e</button>
      <button class="show-page-loading-msg" data-theme="a" data-textonly="true" data-textvisible="true" data-msgtext="Custom Loader" data-icon="arrow-r" data-html="<span class='ui-bar ui-overlay-c ui-corner-all'><img src='../_assets/images/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: