libs/js/jquery-mobile-1.0.1pre/docs/api/globalconfig.html

   1 <!DOCTYPE html>
   2 <html>
   3         <head>
   4         <meta charset="utf-8">
   5         <meta name="viewport" content="width=device-width, initial-scale=1">
   6         <title>jQuery Mobile Docs - Configuring default settings</title>
   7         <link rel="stylesheet"  href="../../css/themes/default/" />
   8         <link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
   9         <script src="../../js/jquery.js"></script>
  10         <script src="../../experiments/themeswitcher/jquery.mobile.themeswitcher.js"></script>
  11         <script src="../_assets/js/jqm-docs.js"></script>
  12         <script src="../../js/"></script>
  13 </head>
  14 <body>
  15
  16 <div data-role="page" class="type-interior">
  17
  18         <div data-role="header" data-theme="f">
  19                 <h1>Configuring Defaults</h1>
  20                 <a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse" class="ui-btn-right jqm-home">Home</a>
  21         </div><!-- /header -->
  22
  23         <div data-role="content" data-theme="c">
  24                 <div class="content-primary">
  25
  26                         <h2>Working with jQuery Mobile's Auto-initialization</h2>
  27                         <p>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.</p>
  28
  29                         <h3>The mobileinit event</h3>
  30                         <p>When the jQuery Mobile starts to execute, it triggers a <code>mobileinit</code> event on the <code>document</code> object, to which you can bind to apply overrides to jQuery Mobile's defaults.</p>
  31
  32                         <pre>
  33                                 <code>
  34 $(document).bind("mobileinit", function(){
  35   //apply overrides here
  36 });
  37                                 </code>
  38                         </pre>
  39
  40                         <p>Because the <code>mobileinit</code> 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:</p>
  41
  42                         <pre>
  43                                 <code>
  44 &lt;script src=&quot;jquery.js&quot;&gt;&lt;/script&gt;
  45 <strong>&lt;script src=&quot;custom-scripting.js&quot;&gt;&lt;/script&gt;</strong>
  46 &lt;script src=&quot;jquery-mobile.js&quot;&gt;&lt;/script&gt;
  47                                 </code>
  48                         </pre>
  49
  50                         <p>Within this event binding, you can configure defaults either by extending the <code>$.mobile</code> object using jQuery's <code>$.extend</code> method:</p>
  51
  52                         <pre>
  53                                 <code>
  54 $(document).bind("mobileinit", function(){
  55   $.extend(  $.mobile , {
  56     <strong>foo: bar</strong>
  57   });
  58 });
  59                                 </code>
  60                         </pre>
  61
  62                         <p>...or by setting them individually:</p>
  63                         <pre>
  64                                 <code>
  65 $(document).bind("mobileinit", function(){
  66   <strong>$.mobile.foo = bar;</strong>
  67 });
  68                                 </code>
  69                         </pre>
  70
  71                 <p>To quickly preview these global configuration options in action, check out the <a href="../config/index.html">config test pages</a>.</p>
  72
  73                 <h2>Configurable options</h2>
  74                 <p>The following defaults are configurable via the <code>$.mobile</code> object:</p>
  75
  76 <dl>
  77         <dt><code>ns</code> <em>string</em>, default: ""</dt>
  78         <dd>The namespace used in data- attributes, for example, data-role. Can be set to anything, including a blank string which is the default. When using, it's clearest if you include a trailing dash, such as "mynamespace-" which maps to <code>data-mynamespace-foo="..."</code>.
  79                 <p><strong>NOTE:</strong> if you're using data- namespacing, you'll need to manually update/override one selector in the theme CSS. The following data selectors should incorporate the namespace you're using:
  80                 <pre><code>
  81 .ui-mobile [data-<strong>mynamespace-</strong>role=page], .ui-mobile [data-<strong>mynamespace-</strong>role=dialog], .ui-page { ...
  82                 </code></pre>
  83                 </p>
  84         </dd>
  85
  86         <dt><code>autoInitializePage</code> <em>boolean</em>, default: true</dt>
  87         <dd>When the DOM is ready, the framework should automatically call <code>$.mobile.initializePage</code>. If false, page will not initialize, and will be visually hidden until until <code>$.mobile.initializePage</code> is manually called.</dd>
  88
  89         <dt><code>subPageUrlKey</code> <em>string</em>, default: "ui-page"</dt>
  90         <dd>The url parameter used for referencing widget-generated sub-pages (such as those generated by nested listviews). Translates to to <em>example.html<strong>&ui-page=</strong>subpageIdentifier</em>. The hash segment before &ui-page= is used by the framework for making an Ajax request to the URL where the sub-page exists.</dd>
  91
  92         <dt><code>activePageClass</code> <em>string</em>, default: "ui-page-active"</dt>
  93         <dd>The class assigned to page currently in view, and during transitions</dd>
  94
  95
  96         <dt><code>activeBtnClass</code> <em>string</em>, default: "ui-btn-active"</dt>
  97         <dd>The class used for "active" button state, from CSS framework.</dd>
  98
  99         <dt><code>ajaxEnabled</code> <em>boolean</em>, default: true</dt>
 100         <dd>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.</dd>
 101
 102         <dt><code>linkBindingEnabled</code> <em>boolean</em>, default: true</dt>
 103         <dd>jQuery Mobile will automatically bind the clicks on anchor tags in your document. Setting this options to false will prevent all anchor click handling <em>including</em> the addition of active button state and alternate link bluring. This should only be used when attempting to delegate the click management to another library or custom code.</dd>
 104
 105         <dt><code>hashListeningEnabled</code> <em>boolean</em>, default: true</dt>
 106         <dd>jQuery Mobile will automatically listen and handle changes to the location.hash. Disabling this will prevent jQuery Mobile from handling hash changes, which allows you to handle them yourself, or simply to use simple deep-links within a document that scroll to a particular ID.</dd>
 107
 108         <dt><code>pushStateEnabled</code> <em>boolean</em>, default: true</dt>
 109         <dd>Enhancement to use <code>history.replaceState</code> in supported browsers, to convert the hash-based Ajax URL into the full document path. Note that we <a href="../pages/page-navmodel.html">recommend</a> disabling this feature if Ajax is disabled or if extensive use of external links are used.</dd>
 110
 111         <dt><code>defaultPageTransition</code> <em>string</em>, default: 'slide'</dt>
 112         <dd>Set the default transition for page changes that use Ajax. Set to 'none' for no transitions by default.</dd>
 113
 114         <dt><code>touchOverflowEnabled</code> <em>boolean</em>, default: false</dt>
 115         <dd>Enable smoother page transitions and true fixed toolbars in devices that support both the <code>overflow:</code> and <code>overflow-scrolling: touch; </code> CSS properties.</dd>
 116
 117         <dt><code>defaultDialogTransition</code> <em>string</em>, default: 'pop'</dt>
 118         <dd>Set the default transition for dialog changes that use Ajax. Set to 'none' for no transitions by default.</dd>
 119
 120         <dt><code>minScrollBack</code> <em>string</em>, default: 150</dt>
 121         <dd>Minimum scroll distance that will be remembered when returning to a page. </dd>
 122
 123         <dt><code>loadingMessage</code> <em>string</em>, default: "loading"</dt>
 124         <dd>Set the text that appears when a page is loading. If set to false, the message will not appear at all.</dd>
 125
 126         <dt><code>pageLoadErrorMessage</code> <em>string</em>, default: "Error Loading Page"</dt>
 127         <dd>Set the text that appears when a page fails to load through Ajax.</dd>
 128
 129         <dt><code>gradeA</code> <em>function that returns a boolean</em>, default: a function returning the value of $.support.mediaquery</dt>
 130         <dd>Any support conditions that must be met in order to proceed.</dd>
 131
 132
 133 </dl>
 134         </div><!--/content-secondary -->
 135
 136         <div class="content-secondary">
 137
 138                 <div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">
 139
 140                                 <h3>More in this section</h3>
 141
 142                                 <ul data-role="listview"  data-theme="c" data-dividertheme="d">
 143
 144                                         <li data-role="list-divider">API</li>
 145                                         <li data-theme="a"><a href="../../docs/api/globalconfig.html">Configuring defaults</a></li>
 146                                         <li><a href="../../docs/api/events.html">Events</a></li>
 147                                         <li><a href="../../docs/api/methods.html">Methods &amp; Utilities</a></li>
 148                                         <li><a href="../../docs/api/data-attributes.html">Data attribute reference</a></li>
 149                                         <li><a href="../../docs/api/themes.html">Theme framework</a></li>
 150                                 </ul>
 151                 </div>
 152         </div>
 153
 154 </div><!-- /content -->
 155
 156 <div data-role="footer" class="footer-docs" data-theme="c">
 157                 <p>&copy; 2011 The jQuery Project</p>
 158 </div>
 159
 160 </div><!-- /page -->
 161
 162 </body>
 163 </html>