Configuring Defaults

Home

Working with jQuery Mobile's Auto-initialization

Unlike other jQuery projects, such as jQuery and jQuery UI, jQuery Mobile automatically applies many markup enhancements as soon as it loads (long before document.ready event fires). These enhancements are applied based on jQuery Mobile's default configuration, which is designed to work with common scenarios, but may or may not match your particular needs. Fortunately, these settings are easy to configure.

The mobileinit event

When the jQuery Mobile starts to execute, it triggers a mobileinit event on the document object, to which you can bind to apply overrides to jQuery Mobile's defaults.

				
$(document).bind("mobileinit", function(){
  //apply overrides here
});
				
			

Because the mobileinit event is triggered immediately upon execution, you'll need to bind your event handler before jQuery Mobile is loaded. Thus, we recommend linking to your JavaScript files in the following order:

				
<script src="jquery.js"></script>
<script src="custom-scripting.js"></script>
<script src="jquery-mobile.js"></script>
				
			

Within this event binding, you can configure defaults either by extending the $.mobile object using jQuery's $.extend method:

				
$(document).bind("mobileinit", function(){
  $.extend(  $.mobile , {
    foo: bar
  });
});
				
			

...or by setting them individually:

				
$(document).bind("mobileinit", function(){
  $.mobile.foo = bar;
});
				
			

Configurable options

The following defaults are configurable via the $.mobile object:

subPageUrlKey (string, default: "ui-page"):
The url parameter used for referencing widget-generated sub-pages (such as those generated by nested listviews). Translates to to example.html&ui-page=subpageIdentifier. The hash segment before &ui-page= is used by the framework for making an Ajax request to the URL where the sub-page exists.
nonHistorySelectors (string, default: "dialog"):
Anchor links with a data-rel attribute value, or pages with a data-role value, that match these selectors will not be trackable in history (they won't update the location.hash and won't be bookmarkable).
activePageClass (string, default: "ui-page-active"):
The class assigned to page currently in view, and during transitions
activeBtnClass (string, default: "ui-page-active"):
The class used for "active" button state, from CSS framework.
ajaxEnabled (boolean, default: true):
jQuery Mobile will automatically handle link clicks and form submissions through Ajax, when possible. If false, url hash listening will be disabled as well, and urls will load as regular http requests.
ajaxLinksEnabled (deprecated boolean, default: true):
jQuery Mobile will automatically handle link clicks through Ajax, when possible.
ajaxFormsEnabled (deprecated boolean, default: true):
jQuery Mobile will automatically handle form submissions through Ajax, when possible.
autoInitialize (boolean, default: true):
Auto initialize, when set to false, will defer the enhancement of your embeded pages until
 $.mobile.initializePage(); 
is invoked explicitly. By default the page is enhanced when the dom is ready.
defaultTransition (string, default: 'slide'):
Set the default transition for page changes that use Ajax. Set to 'none' for no transitions by default.
loadingMessage (string, default: "loading"):
Set the text that appears when a page is loading. If set to false, the message will not appear at all.
metaViewportContent (string, default: "width=device-width, minimum-scale=1, maximum-scale=1"):
Configure the auto-generated meta viewport tag's content attribute. If false, no meta tag will be appended to the DOM.
gradeA (function that returns a boolean, default: a function returning the value of $.support.mediaquery):
Any support conditions that must be met in order to proceed.