Skip to content
This repository has been archived by the owner on Oct 8, 2021. It is now read-only.

Commit

Permalink
Merge pull request #3910 from Trott/api-globalconfig-documentation-fixes
Browse files Browse the repository at this point in the history 
Minor fixes to documentation in api/globalconfig.html
  • Loading branch information
@Wilto
Wilto committed Mar 25, 2012
2 parents e12ab6d + 994de79 commit 485cf50
Showing 1 changed file with 21 additions and 21 deletions.
42 changes: 21 additions & 21 deletions docs/api/globalconfig.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,10 @@ <h1>Configuring Defaults</h1>
<div class="content-primary">

<h2>Working with jQuery Mobile's Auto-initialization</h2>
<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 <code>document.ready</code> 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>
<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 the <code>document.ready</code> event fires). These enhancements are applied based on jQuery Mobile's default settings, which are designed to work with common scenarios. If changes to the settings are needed, they are easy to configure.</p>

<h3>The mobileinit event</h3>
<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>
<p>When jQuery Mobile starts, it triggers a <code>mobileinit</code> event on the <code>document</code> object. To override default settings, bind to <code>mobileinit</code>.</p>

<pre>
<code>
Expand All @@ -39,7 +39,7 @@ <h3>The mobileinit event</h3>
</code>
</pre>

<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>
<p>Because the <code>mobileinit</code> event is triggered immediately, you'll need to bind your event handler before jQuery Mobile is loaded. Link to your JavaScript files in the following order:</p>

<pre>
<code>
Expand All @@ -49,7 +49,7 @@ <h3>The mobileinit event</h3>
</code>
</pre>

<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>
<p>You can override default settings by extending the <code>$.mobile</code> object using jQuery's <code>$.extend</code> method.</p>

<pre>
<code>
Expand All @@ -61,7 +61,7 @@ <h3>The mobileinit event</h3>
</code>
</pre>

<p>...or by setting them individually:</p>
<p>Alternatively, you can set them using object property notation.</p>
<pre>
<code>
$(document).bind("mobileinit", function(){
Expand All @@ -70,60 +70,60 @@ <h3>The mobileinit event</h3>
</code>
</pre>

<p>To quickly preview these global configuration options in action, check out the <a href="../config/index.html">config test pages</a>.</p>
<p>To explore the effects of global configuration options, see the <a href="../config/index.html">config test pages</a>.</p>

<h2>Configurable options</h2>
<p>The following defaults are configurable via the <code>$.mobile</code> object:</p>

<dl>
<dt><code>activeBtnClass</code> <em>string</em>, default: "ui-btn-active"</dt>
<dd>The class used for "active" button state, from CSS framework.</dd>
<dd>The CSS class used for "active" button state.</dd>

<dt><code>activePageClass</code> <em>string</em>, default: "ui-page-active"</dt>
<dd>The class assigned to page currently in view, and during transitions</dd>
<dd>The CSS class used for the page currently in view or in a transition.</dd>

<dt><code>ajaxEnabled</code> <em>boolean</em>, default: true</dt>
<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>
<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 ordinary HTTP requests.</dd>

<dt><code>allowCrossDomainPages</code> <em>boolean</em>, default: false</dt>
<dd>When jQuery Mobile attempts to load an external page, the request runs through <code>$.mobile.loadPage()</code>. This will only allow cross-domain requests if <code>$.mobile.allowCrossDomainPages</code> is set to true. Because the jQuery Mobile framework tracks what page is being viewed within the browser's location hash, it is possible for a cross-site scripting (XSS) attack to occur if the XSS code in question can manipulate the hash and set it to a cross-domain URL of its choice. This is the main reason that the default setting for $.mobile.allowCrossDomainPages is set to false. In PhoneGap apps that must "phone home" by loading assets off a remote server, both the <code>$.support.cors</code> AND <code>$.mobile.allowCrossDomainPages</code> must be set to true.</dd>

<dt><code>autoInitializePage</code> <em>boolean</em>, default: true</dt>
<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 <code>$.mobile.initializePage</code> is manually called.</dd>
<dd>When the DOM is ready, the framework should automatically call <code>$.mobile.initializePage</code>. If false, the page will not initialize and will be visually hidden until <code>$.mobile.initializePage</code> is manually called.</dd>

<dt><code>defaultDialogTransition</code> <em>string</em>, default: 'pop'</dt>
<dd>Set the default transition for dialog changes that use Ajax. Set to 'none' for no transitions by default.</dd>
<dd>Set the default transition for dialog changes that use Ajax. Set to 'none' for no transitions.</dd>

<dt><code>defaultPageTransition</code> <em>string</em>, default: 'slide'</dt>
<dd>Set the default transition for page changes that use Ajax. Set to 'none' for no transitions by default.</dd>
<dd>Set the default transition for page changes that use Ajax. Set to 'none' for no transitions.</dd>

<dt><code>gradeA</code> <em>function that returns a boolean</em>, default: a function returning the value of $.support.mediaquery</dt>
<dd>Any support conditions that must be met in order to proceed.</dd>

<dt><code>hashListeningEnabled</code> <em>boolean</em>, default: true</dt>
<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>
<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 use simple deep-links within a document that scroll to a particular ID.</dd>

<dt><code>ignoreContentEnabled</code> <em>boolean</em>, default: false</dt>
<dd><em>Warning:</em> Setting this property to true will cause performance degredation on enhancement. Once set, all automatic enhancements made by the framework to each enhanceable element of the user's markup will first check for a <code>data-enhance=false</code> parent node. If one is found the markup will be ignored. This setting and the accompanying data attribute provide a mechanism through which users can prevent enhancement over large sections of markup.</dd>
<dd><em>Warning:</em> Setting this property to true will cause performance degradation on enhancement. Once set, all automatic enhancements made by the framework to each enhanceable element of the user's markup will first check for a <code>data-enhance=false</code> parent node. If one is found the markup will be ignored. This setting and the accompanying data attribute provide a mechanism through which users can prevent enhancement over large sections of markup.</dd>

<dt><code>linkBindingEnabled</code> <em>boolean</em>, default: true</dt>
<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>

<dt><code>loadingMessage</code> <em>string</em>, default: "loading"</dt>
<dd>Set the text that appears when a page is loading. If set to false, the message will not appear at all.</dd>

<dt><code>loadingMessageTextVisible</code> <em>string</em>, default: false</dt>
<dd>Should the text be visible when loading message is shown. (note: currently, the text is always visible for loading errors)</dd>
<dt><code>loadingMessageTextVisible</code> <em>boolean</em>, default: false</dt>
<dd>Whether the text should be visible when a loading message is shown. The text is always visible for loading errors.</dd>

<dt><code>loadingMessageTheme</code> <em>string</em>, default: "a"</dt>
<dd>Set the theme that the loading message box uses, when text is visible.</dd>
<dd>The theme that the loading message box uses when text is visible.</dd>

<dt><code>minScrollBack</code> <em>string</em>, default: 250</dt>
<dd>Minimum scroll distance that will be remembered when returning to a page. </dd>
<dd>Minimum scroll distance that will be remembered when returning to a page.</dd>

<dt><code>ns</code> <em>string</em>, default: ""</dt>
<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>.
<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:
<dd>The namespace used in data- attributes (e.g., data-role). Can be set to any string, 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>.
<p>If you use data- namespacing, you will need to update/override one selector in the theme CSS. The following data selectors should incorporate the namespace you're using:
<pre><code>
.ui-mobile [data-<strong>mynamespace-</strong>role=page], .ui-mobile [data-<strong>mynamespace-</strong>role=dialog], .ui-page { ...
</code></pre>
Expand All @@ -140,7 +140,7 @@ <h2>Configurable options</h2>
<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>

<dt><code>subPageUrlKey</code> <em>string</em>, default: "ui-page"</dt>
<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>
<dd>The url parameter used for referencing widget-generated sub-pages (such as those generated by nested listviews). Translates 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>

<dt><code>touchOverflowEnabled</code> <em>boolean</em>, default: false</dt>
<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>
Expand Down

0 comments on commit 485cf50

Please sign in to comment.