loader.xml

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="../entries2html.xsl" ?>
<entry name="loader" namespace="fn" type="widget" widgetnamespace="mobile" event-prefix="loading">
	<title>Loader Widget</title>
	<desc>Handles the task of displaying the loading dialog when jQuery Mobile pulls in content via Ajax. </desc>
	<longdesc>
		<h2>The Loader Widget</h2>
		<p>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 <code>$.mobile.loading</code> helper method (See the global method docs).</p>


		<xi:include href="../includes/widget-theming.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>

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

		<p>To configure the loading dialog globally the following settings can be defined on its prototype during the <code>mobileinit</code> event.</p> Below are the defaults:

<pre><code><![CDATA[
$( 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 = "";
});
]]></code></pre>

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

<pre><code><![CDATA[
$.mobile.loading( "show", {
	text: "foo",
	textVisible: true,
	theme: "z",
	html: ""
});
]]></code></pre>
	</longdesc>
	<added>1.2</added>
	<options>
		<xi:include href="../includes/widget-option-defaults.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<option name="classes" type="Object">
			<default>{
				"ui-loader": "ui-corner-all",
				"ui-loader-icon": "ui-icon-loading"
			}</default>
			<xi:include href="../includes/classes-option-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
			<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		</option>
		<option name="html" default='""' example-value='"&lt;span class=&#39;ui-icon ui-icon-loading&#39;&gt;&lt;img src=&#39;jquery-logo.png&#39; /&gt;&lt;h2&gt;is loading for you ...&lt;/h2&gt;&lt;/span&gt;"'>
			<desc>If this is set to a non empty string value, it will be used to replace the entirety of the loader's inner html.</desc>
			<type name="string" />
		</option>
		<option name="text" default="loading" example-value='"Loading Page..."'>
			<desc>Sets the text of the message.</desc>
			<type name="string" />
		</option>
		<option name="textonly" default="false" example-value="true">
			<desc>If true, the "spinner" image will be hidden when the message is shown.</desc>
			<type name="boolean" />
		</option>
		<option name="textVisible" default="false" example-value="true">
			<desc>If true, the text value will be used under the spinner.</desc>
			<type name="boolean" />
		</option>
		<xi:include href="../includes/widget-option-theme.xml" xmlns:xi="http://www.w3.org/2003/XInclude" />
	</options>
	<events>
		<event name="create">
			<desc>Triggered when a loader widget is created.</desc>
			<argument name="event" type="Event">
			</argument>
			<argument name="ui" type="Object">
			</argument>
		</event>
	</events>
	<methods>
		<method name="checkLoaderPosition">
			<desc>Check position of loader to see if it appears to be "fixed" to center.
			</desc>
		</method>
		<method name="fakeFixLoader">
			<desc>For non-fixed supporting browsers. Position at y center (if scrollTop supported), above the activeBtn (if defined), or just 100px from top.
			</desc>
		</method>
		<method name="hide">
			<desc>Hide the loader widget
			</desc>
		</method>
		<method name="loading">
			<desc>Show or hide the loader message, which is configurable via <code>$.mobile.loader</code> prototype options as described in the widget docs or can be controlled via a params object.
			</desc>
		</method>
		<method name="resetHtml">
			<desc>
			</desc>
		</method>
		<method name="show">
			<desc>
			</desc>
		</method>
</methods>
	<example>
		<height>410</height>
		<desc>Loader Examples</desc>
		<html><![CDATA[
<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>
]]></html>
		<code><![CDATA[
$(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" );
});
]]></code>
	</example>
	<category slug="widgets"/>
</entry>