orientationchangeorientation property equal to either "portrait" or "landscape". These values are also added as classes to the HTML element, allowing you to leverage them in your CSS selectors. Note that we currently bind to the resize event when orientationChange is not natively supported.orientation property equal to either "portrait" or "landscape". These values are also added as classes to the HTML element, allowing you to leverage them in your CSS selectors. Note that we currently bind to the resize event when orientationChange is not natively supported, or when $.mobile.orientationChangeEnabled is set to false.orientationchange with relation to the change of the client height and width is different between browsers, though the current implementation will give you the correct value for event.orientation derived from window.orientation. This means that if your bindings are dependent on the height and width values you may want to disable orientationchange all together with $.mobile.orientationChangeEnabled = false to let the fallback resize code trigger your bindings.
+ options (object)
+ options (object)
To quickly preview these global configuration options in action, check out the config test pages.
The following defaults are configurable via the $.mobile object:
ajaxEnabled boolean, default: truehashListeningEnabled boolean, default: truepushStateEnabled boolean, default: truehistory.replaceState in supported browsers, to convert the hash-based Ajax URL into the full document path. Note that we recommend disabling this feature if Ajax is disabled or if extensive use of external links are used.defaultPageTransition string, default: 'slide'touchOverflowEnabled boolean, default: falseoverflow-scrolling: touch; property.overflow: and overflow-scrolling: touch; CSS properties.defaultDialogTransition string, default: 'pop'The default theme contains the following five Bar styles:
By default, the framework assigns the "a" swatch to all headers and footers, because these are typically given high visual priority in an application. To set the color of a bar to a different swatch color, simply add the data-theme attribute to your header or footer and specify an alternate swatch letter ('b' or 'd', for example) and the specified theme swatch color will be applied. Learn more about toolbar theming.
The default theme also includes color swatch values for use in content blocks, designed to coordinate with the header color swatches in the theme.
Input type="button" based button:
- +Input type="submit" based button:
- +Input type="reset" based button:
- +Input type="image" based button:
- + diff --git a/docs/config/dialogTransition.html b/docs/config/dialogTransition.html new file mode 100644 index 00000000..d8a42b8f --- /dev/null +++ b/docs/config/dialogTransition.html @@ -0,0 +1,40 @@ + + + + + +To test, hit the button below and browse the docs. Note that if a link causes a refresh, this setting will be lost and the default settings will be seen.
+ Browse docs + Or open a basic dialog + +The following links will cause a full page refresh so that the global options configuration can take effect. Each link below will tweak a different option for quick testing.
+ + +Enhancement to use history.replaceState in supported browsers, to convert the hash-based Ajax URL into the full document path.
+ +Enable smoother page transitions and true fixed toolbars in devices that support both the overflow: and overflow-scrolling: touch; CSS properties.
+ +Set the default transition for page changes that use Ajax. Set to 'none' for no transitions by default.
+ +Set the default transition for dialog changes that use Ajax. Set to 'none' for no transitions by default.
+ +Minimum scroll distance that will be remembered when returning to a page.
+ +Set the text that appears when a page is loading. If set to false, the message will not appear at all.
+ +Set the text that appears when a page fails to load through Ajax.
+ +Test the docs with the latest jQuery core version
+ +To test, hit the button below and browse the docs. Note that if a link causes a refresh, this setting will be lost and the default settings will be seen.
+ Browse docs + + +To test, hit the button below and browse the docs. Note that if a link causes a refresh, this setting will be lost and the default settings will be seen.
+ Browse docs + + +To test, hit the button below and browse the docs. Note that if a link causes a refresh, this setting will be lost and the default settings will be seen.
+ Browse docs + + +To test, hit the button below and browse the docs. Note that if a link causes a refresh, this setting will be lost and the default settings will be seen.
+ Browse docs + Or try this broken link + + +To test, hit the button below and browse the docs. Note that if a link causes a refresh, this setting will be lost and the default settings will be seen.
+ Browse docs + +To test, hit the button below and browse the docs. Note that if a link causes a refresh, this setting will be lost and the default settings will be seen.
+ Browse docs + + +To test, hit the button below and browse the docs. Note that if a link causes a refresh, this setting will be lost and the default settings will be seen.
+ Browse docs + + +Checkboxes can also be used for grouped button sets where more than one button can be selected at once, such as the bold, italic and underline button group seen in word processors. To make a horizontal button set, add the data-type="horizontal" to the fieldset.
-<fieldset data-role="controlgroup" data-type="horizontal" data-role="fieldcontain">
+<fieldset data-role="controlgroup" data-type="horizontal">
The framework will float the labels so they sit side-by-side on a line, hide the checkbox icons and only round the left and right edges of the group.
diff --git a/docs/pages/page-dynamic.html b/docs/pages/page-dynamic.html index d1f39746..4dd23238 100644 --- a/docs/pages/page-dynamic.html +++ b/docs/pages/page-dynamic.html @@ -30,13 +30,13 @@Links that point to other domains or that have rel="external", data-ajax="false" or target attributes will not be loaded with Ajax. Instead, these links and will cause a full page refresh with no animated transition. Both attributes have the same effect, but different semanic meaning. rel="external" should be used when linking to another site or domain, while data-ajax="false" is useful for simply opting a page within your domain from being loaded via Ajax. Because of security restrictions, the framework always opts links to external domains out of the Ajax behavior.
Links that point to other domains or that have rel="external", data-ajax="false" or target attributes will not be loaded with Ajax. Instead, these links and will cause a full page refresh with no animated transition. Both attributes have the same effect, but different semantic meaning: rel="external" should be used when linking to another site or domain, while data-ajax="false" is useful for simply opting a page within your domain from being loaded via Ajax. Because of security restrictions, the framework always opts links to external domains out of the Ajax behavior.
Note: When building a jQuery Mobile application where the Ajax navigation system is disabled globally or frequently disabled on individual links, we recommend disabling the $.mobile.pushStateEnabled global configuration option to avoid inconsistent navigation behavior in some browsers.
Once the referenced page is present in the DOM, the $.mobile.changePage() function applies a transition between the current active page and the new page. Page transitions happen through adding and removing classes that apply CSS animations. For example, in a slide-left transition, the exiting page is given the classes "slideleft" and "out", and the entering page is given the classes "slideleft" and "in", as well as a class of "ui-page-active" to mark it as the new "active" page being viewed. When the animation is complete, the "in" and "out" classes are removed, and the exited page loses its "ui-page-active" class.
For those browsers that support history.pushState and history.replaceState an additional optional plugin is provided that will convert the hash change urls mentioned in the previous section into the hashless equivelant. It's important to note that it does indeed convert the hash urls by using history.replaceState as the history.pushState does not produce the desired result in some mobile browsers.
There is an optional feature is converts the longer, hash-based URLs mentioned in the previous section into the full document path which is cleaner and makes the Ajax tracking transparent in the URL structure. This is built as an enhancement on top of the hash-based URL system for Ajax links. Note that despite the name, this feature technically converts hash-based urls by using history.replaceState (not history.pushState) in the current release because this works more reliably across our target platforms. For browsers that do not support history.replaceState, or if this feature is disabled, hash-based URLs will be used instead.
Since the plugin initializes when the DOM is fully loaded you can enable and disable it manually by setting $.mobile.pushStateEnabled anytime before.
Since the plugin initializes when the DOM is fully loaded you can enable and disable it manually by setting $.mobile.pushStateEnabled global configuration option to false anytime before document ready.
Slightly different implementations of the replaceState API in various browsers can cause odd behavior in specific scenarios. For example, some browser implementations (including desktop browsers) implement the popstate event differently when linking externally and moving back to a page onto which state has already been pushed/replaced. When building a jQuery Mobile application where the ajax navigation is being explicitly disabled, either though the frequent use of rel="external" on links or by disabling Ajax navigation completely via the $.mobile.ajaxEnabled=false, we recommend disabling the pushState feature to fall back to the hash based navigation for more consistent behavior.
Another key ingredient to jQuery Mobile's page navigation model is the base element, which is injected into the head and modified on every page change to ensure that any assets (css,images,js,etc) referenced on that page will be requested from a proper path. In browsers that don't support dynamic updates to the base element (such as Firefox 3.6), jQuery Mobile loops through all of the referenced assets on the page and prefixes their href and src attributes with the base path.
Another key ingredient to jQuery Mobile's page navigation model is the base element, which is injected into the head and modified on every page change to ensure that any assets (images, CSS, JS, etc.) referenced on that page will be requested from a proper path. In browsers that don't support dynamic updates to the base element (such as Firefox 3.6), jQuery Mobile loops through all of the referenced assets on the page and prefixes their href and src attributes with the base path.
TODO: update description of internal base and urlHistory objects
The nav model maintains a data-url attribute on all data-role=”page” elements. This data-url attribute is used to track the origin of the page element. Pages embedded within the main application document all have their data-url parameter set to the ID of the @data-role="page" element. The only exception to this is the first-page in the document. The first-page is special because it can be addressed by its @id if it has one, or by the document or base URL (with no hash fragment).
+ +The nav model maintains a data-url attribute on all data-role="page" elements. This data-url attribute is used to track the origin of the page element. Pages embedded within the main application document all have their data-url parameter set to the ID of the @data-role="page" element. The only exception to this is the first-page in the document. The first-page is special because it can be addressed by its @id if it has one, or by the document or base URL (with no hash fragment).
Pages that are external to the application document get pulled in dynamically via ajax, their data-url is set to the site relative path to the external page. If you are running in an environment where loading an external page from a different domain is allowed, then the data-url is set to the absolute URL.
- +Some plugins may choose to dynamically break a page's content into separate navigable pages, which can then be reached via deep links. One example of this would be the Listview plugin, which will break a nested UL (or OL) into separate pages, which are each given a data-url attribute so they can be linked to like any normal "page" in jQuery Mobile. However, in order to link to these pages, the page that generates them must first be requested from the server. To make this work, pages that are auto-generated by plugins use the following special data-url structure: @@ -106,6 +111,7 @@
Any unique assets referenced by pages in a jQuery Mobile-driven site should be placed inside the "page" element (the element with a data-role attribute of "page"). For example, links to styles and scripts that are specific to a particular page can be referenced inside that div. However, a better approach is to use jQuery Mobile's page events to trigger specific scripting when certain pages load. Note: you can return a page from the server with a data-url already specified in the markup, and jQuery Mobile will use that for the hash update. This allows you to ensure directory paths resolve with a trailing slash and will therefore be used in the base url path for future requests.
Conversely, any non-unique assets (those used site-wide) should be referenced in the <head> section of an HTML document, or at the very least, outside of the "page" element, to prevent running scripts more than once.
The "ui-page" key name used in sub-hash url references can be set to any value you'd like, so as to blend into your URL structure. This value is stored in jQuery.mobile.subPageUrlKey.
When traveling back to a previously loaded jQuery Mobile document from an external or internal document with the push state plugin enabled, some browsers load and trigger the popstate event on the wrong document or for the wrong reasons (two edge cases recorded so far). If you are regularly linking to external documents and find the application behaving eratically try disabling pushstate support.
Since jQuery Mobile uses an Ajax-powered navigation system, there are a few helpful things to know when writing scripts that interact with the page and navigation model. You can explore the mobile API in more detail by reading up on global configuration options, events, and methods or dig into the technical details of the Ajax navigation model.
+Since jQuery Mobile uses an Ajax-powered navigation system, there are a few helpful things to know when writing scripts that manipulate your content. You can explore the mobile API in more detail by reading up on global configuration options, events, and methods or dig into the technical details of the Ajax navigation model.
-When you click a link in jQuery Mobile, the Ajax navigation system uses the link's href to formulate an Ajax request. Although the full page is loaded with Ajax, the framework only pulls in the contents of the page, and ignores anything in the head except for title tag contents.
This means that any scripts or styles in the head of the page won't have any effect when the page is loaded via Ajax. The same page will work as expected if you were to load a page directly but both scenarios need to be considered. The reason that the head is ignored for Ajax page content: it's just too complex. The framework would need to compare and reconcile the contents of multiple page head elements as they are loaded into the DOM so we leave this task to the developer.
When the user clicks a link in a jQuery Mobile-driven site, the default behavior of the navigation system is to use that link's href to formulate an Ajax request (instead of allowing the browser's default link behavior of requesting that href with full page load). When that Ajax request goes out, the framework will receive its entire text content, but it will only inject the contents of the response's body element (or more specifically the data-role="page" element, if it's provided), meaning nothing in the head of the page will be used (with the exception of the page title, which is fetched specifically).
The simplest approach is to add the same set of stylesheets and scripts into all your pages. If you need to load in specific scripts or styles for a particular page, bind to the pagecreate event (details below) to run the necessary code when a specific page ID is created. Following this approach will ensure that the code executes if the page is loaded directly or is pulled in and shown via Ajax.
This means that any scripts and styles referenced the head of a page won't have any effect when a page is loaded via Ajax, but they will execute if the page is requested normally via HTTP. When scripting jQuery Mobile sites, both scenarios need to be considered. The reason that the head of a page is ignored when requested via Ajax is that the potential of re-executing the same JavaScript is very high (it's common to reference the same scripts in every page of a site). Due to the complexity of attempting to work around that issue, we leave the task of executing page-specific scripts to the developer, and assume head scripts are only expected to execute once per browsing session.
The simplest approach when building a jQuery Mobile site is to reference the same set of stylesheets and scripts in the head of every page. If you need to load in specific scripts or styles for a particular page, we recommend binding logic to the pagecreate event (details below) to run necessary code when a specific page is created (which can be determined by its id attribute, or a number of other ways). Following this approach will ensure that the code executes if the page is loaded directly or is pulled in and shown via Ajax.
Another approach for page-specific scripting would be to include scripts at the end of the body element. If you include your custom scripting this way, be aware that these scripts will execute when that page is loaded via Ajax or regular HTTP, so if these scripts are the same on every page, you'll likely run into problems. If you're including scripts this way, we'd recommend enclosing your page content in a data-role="page" element, and placing scripts that are referenced on every page outside of that element. Scripts that are unique to that page can be placed in that element, to ensure that they execute when the page is fetched via Ajax.
The first thing you learn in jQuery is to call code inside the $(document).ready() function so everything will execute as soon as the DOM is loaded. However, in jQuery Mobile, Ajax is used to load the contents of each page into the DOM as you navigate, and the DOM ready handler only executes for the first page. To execute code whenever a new page is loaded and created by the Ajax navigation system, you must bind to the pagecreate event.
The pagecreate event is triggered on the page being initialized, right after initialization occurs. We recommend binding to this event instead of DOM ready() because this will work regardless of whether the page is loaded directly or if the content is pulled into another page as part of the Ajax navigation system.
One of the first things people learn in jQuery is to use the $(document).ready() function for executing DOM-specific code as soon as the DOM is ready (which often occurs long before the onload event). However, in jQuery Mobile site and apps, pages are requested and injected into the same DOM as the user navigates, so the DOM ready event is not as useful, as it only executes for the first page. To execute code whenever a new page is loaded and created in jQuery Mobile, you can bind to the pagecreate event.
The pagecreate event is triggered on a page when it is initialized, right after initialization occurs. Most of jQuery Mobile's official widgets auto-initialize themselves based on this event, and you can set up your code to do the same.
-$('#aboutPage').live('pagecreate',function(event){
- alert('This page was just enhanced by jQuery Mobile!');
+$( document ).delegate( "pagecreate", "#aboutPage", function() {
+ alert('A page with an ID of "aboutPage" was just created by jQuery Mobile!');
+});
+If you'd like to manipulate a page's contents before the pagecreate event fires and widgets are auto-initialized, you can instead bind to the pagebeforecreate event:
+$( document ).delegate( "pagebeforecreate", "#aboutPage", function() {
+ alert('A page with an ID of "aboutPage" is about to be created by jQuery Mobile!');
});
If you need to change the current page with JavaScript, use the changePage method. There are a lot of methods and properties that you can set when changing pages, but here are two simple examples:
If you want to change the current active page with JavaScript, you can use the changePage method. There are a lot of methods and properties that you can set when changing pages, but here are two simple examples:
//transition to the "about us" page with a slideup transition
$.mobile.changePage( "about/us.html", { transition: "slideup"} );
diff --git a/docs/toolbars/docs-navbar.html b/docs/toolbars/docs-navbar.html
index ad5720c2..362b656f 100755
--- a/docs/toolbars/docs-navbar.html
+++ b/docs/toolbars/docs-navbar.html
@@ -24,35 +24,32 @@
Simple navbar
- jQuery Mobile has a very basic navbar widget that is useful for providing up to 5 buttons with optional icons in a bar , typically within a header or footer.
-
+ jQuery Mobile has a very basic navbar widget that is useful for providing up to 5 buttons with optional icons in a bar, typically within a header or footer. There is also a persistent nav bar variation that works more like a tab bar that stays fixed as you navigate across pages.
A navbar is coded as an unordered list of links wrapped in a container element that has the data-role="navbar" attribute. To set one of links to the active (selected) state, add class="ui-btn-active" to the anchor. In this example, we have a two-button navbar in the footer with the "One" item set to active:
-<div data-role="footer">
- <div data-role="navbar">
- <ul>
- <li><a href="a.html" class="ui-btn-active">One</a></li>
- <li><a href="b.html">Two</a></li>
- </ul>
- </div><!-- /navbar -->
-</div><!-- /footer -->
+<div data-role="navbar">
+ <ul>
+ <li><a href="a.html" class="ui-btn-active">One</a></li>
+ <li><a href="b.html">Two</a></li>
+ </ul>
+</div><!-- /navbar -->
The navbar items are set to divide the space evenly so in this case, each button is 1/2 the width of the browser window:
-
+
Adding a third item will automatically make each button 1/3 the width of the browser window:
-
+
Adding a fourth more item will automatically make each button 1/4 the width of the browser window:
-
+
The navbar maxes out with 5 items, each 1/5 the width of the browser window:
-
+
If more than 5 items are added, the navbar will simply wrap to multiple lines:
-
As a fallback, navbars with 1 item will simply render as 100%.
-
-
Navbars in headers
@@ -135,9 +128,33 @@
If you want to add a navbar to the bottom of the page so it acts more like a tab bar, simply wrap the navbar in a container with a data-role="footer"
+<div data-role="footer">
+ <div data-role="navbar">
+ <ul>
+ <li><a href="#">One</a></li>
+ <li><a href="#">Two</a></li>
+ <li><a href="#">Three</a></li>
+ </ul>
+ </div><!-- /navbar -->
+</div><!-- /footer -->
+Icons can be added to navbar items by adding the data-icon attribute specifying a standard mobile icon to each anchor.
Icons can be added to navbar items by adding the data-icon attribute specifying a standard mobile icon to each anchor. By default icons are added above the text (data-iconpos="top"). The following examples add icons to a navbar in a footer.
Icons can be stacked above the labels by adding the data-iconpos="top" attribute to each anchor.
The icon position is set on the navbar container instead of for individual links within for visual consistency. For example, to place the icons below the labels, add the data-iconpos="bottom" attribute to navbar container.
+<div data-role="navbar" data-iconpos="bottom">
+This will result in a bottom icon alignment:
+ + +The icon position can be set to data-iconpos="left":