Moved dependency on jquery.mobile from jqm-docs to jquery.mobile.docs
Use order! plugin to ensure that jquery.mobile gets executed (dumped) first
Added pragmas around the jqm-docs define
Addresses Issue #3484
Caveats:
- This method must be called when the toolbar is visible, meaning you'll see a visible jump when a page is shown. For this reason, I'm hesitant to recommend this feature. It would be a lot smoother to set the page padding in a custom CSS file to make up for whatever EM height your toolbars happen to be.
- Height is set in Pixels, meaning changes in font size could render it inaccurate. If we want to set height in ems, we'll need to add an em conversion utility function to jQM.
- To ensure it works properly, this method will need to be called on page show, and at any time a content reflow might occur: resize, orientationchange, zoom?
This method is not currently called automatically.
It can be called like this: $(".ui-header-fixed").fixedtoolbar( "updatePagePadding" );
This simple utility is used to disable user scaling in devices like iOS. The disable() method disables user-scaling. The enable() method enables user-scaling. The enabled property keeps track of state.
Two other utilites are included here as well.
First, there's zoom.iosfocusfix.js, which disables zoom as a select or input element is focused, preventing iOS from zooming into that element and cropping the viewport. Zoom is restored just after the focus event fires (a half second timeout).
Then there's zoom.iosorientationfix.js, which is intended to fix the iOS orientationchange zoom bug, following the approach from this project https://github.com/scottjehl/iOS-Orientationchange-Fix. This may not be working yet. Needs testing, and it may require that we change the values of the meta content to use maximum-scale instead of user-scalable.
Lastly, fixedtoolbar, once it lands, should use this utility to disable/enable zoom, rather than the one that's currently included in its own source.
Cause: The vmousecancel event was not being fired for 'this'.
How Fixed: Bound vmousecancel event to document instead of 'this'.
How Tested: Ran the example provided with the issue
(http://jsbin.com/oruhu4/) with this change on BlackBerry Playbook v2.0
and iPad iOS 5.0.1
Was causing an vertical scroll bar to appear in FF9 if a button at the
end of the content div is disabled / enabled. Changed '''line-height:
999px''' to '''text-indent: -9999px'''. Thanks n0v1!
Added a new page to contrast the dialog vs. page transitions. Page has
fixed toolbars and form elements to really stress the transitions.
Switched to a table design with a button for dialog and page for each
transition.
I had to create a new set of basic keyframes for non-3D because we had
opacity baked into our keyframes. As an upside, I could tweak the scale
factor differently between Android (0 > 1) and 3D (0.8 > 1).
- Introduced a class (nofade) which is similar to dontmove for
overwriting the fade in/out classes. We're not scoping all classes to
with supported or not like in flip so we need to negate the fade rules
with a new animation
- Added a selector block at the top to lengthen all slide animations to
300ms to reduce blinkiness on Android. Shorter caused animations to
break out of sequence. Needs refinement on timing.
- Added rules to apply the "nofade" classes to the replace the fade
in/out animations for non-3D browsers. Had to set the duration equal to
the slide animations to keep it all in sync.
Removed the spin class from the loader container, tweaked opacity and
added slight glow to bottom of loader, increased padding. Downloaded a
fresh loader image.
Created a new loader that has a circle baked into the animated gif so
there's less of a chance of artifacts in bad browsers. The edge is
chunky because it's a gif but then added 1px of padding to the loader
parent and that the border-radius can smooth this out in iOS. Actually
looks sharp in Android too because of interaction effects between these
rounded corners. Loader spin is faster and more compressed (16 colors).
Removed the body-a class on the spinner since we're just setting this to
flat black = one less gradient to render.
Removed the spin class from the loader container, tweaked opacity and
added slight glow to bottom of loader, increased padding. Downloaded a
fresh loader image.
This commit moves all that logic into the transition handlers, and should provide a better starting point for adding different transition sequences, such as fade-out, scroll, fade-in.
In the process of making this change, the reFocus function was made public as $.mobile.focusPage.
It seems that some device/browser vendors use window.orientation values 0 and 180 to denote the "default" orientation. For iOS devices, and most other smart-phones tested, the default orientation is always "portrait", but in some Android and RIM based tablets, the default orientation is "landscape".
- Modified the orientationchange plugin so that it injects a landscape orientation media query into the document to figure out what the initial orientation is, it then makes adjustments to a portrait_map if necessary, so that we can properly decode the window.orientation value whenever get_orientation() is called.
Added a new page to contrast the dialog vs. page transitions. Page has
fixed toolbars and form elements to really stress the transitions.
Switched to a table design with a button for dialog and page for each
transition.
I had to create a new set of basic keyframes for non-3D because we had
opacity baked into our keyframes. As an upside, I could tweak the scale
factor differently between Android (0 > 1) and 3D (0.8 > 1).
- Introduced a class (nofade) which is similar to dontmove for
overwriting the fade in/out classes. We're not scoping all classes to
with supported or not like in flip so we need to negate the fade rules
with a new animation
- Added a selector block at the top to lengthen all slide animations to
300ms to reduce blinkiness on Android. Shorter caused animations to
break out of sequence. Needs refinement on timing.
- Added rules to apply the "nofade" classes to the replace the fade
in/out animations for non-3D browsers. Had to set the duration equal to
the slide animations to keep it all in sync.
Removed the spin class from the loader container, tweaked opacity and
added slight glow to bottom of loader, increased padding. Downloaded a
fresh loader image.
Created a new loader that has a circle baked into the animated gif so
there's less of a chance of artifacts in bad browsers. The edge is
chunky because it's a gif but then added 1px of padding to the loader
parent and that the border-radius can smooth this out in iOS. Actually
looks sharp in Android too because of interaction effects between these
rounded corners. Loader spin is faster and more compressed (16 colors).
Removed the body-a class on the spinner since we're just setting this to
flat black = one less gradient to render.
Removed the spin class from the loader container, tweaked opacity and
added slight glow to bottom of loader, increased padding. Downloaded a
fresh loader image.
This commit moves all that logic into the transition handlers, and should provide a better starting point for adding different transition sequences, such as fade-out, scroll, fade-in.
In the process of making this change, the reFocus function was made public as $.mobile.focusPage.
It seems that some device/browser vendors use window.orientation values 0 and 180 to denote the "default" orientation. For iOS devices, and most other smart-phones tested, the default orientation is always "portrait", but in some Android and RIM based tablets, the default orientation is "landscape".
- Modified the orientationchange plugin so that it injects a landscape orientation media query into the document to figure out what the initial orientation is, it then makes adjustments to a portrait_map if necessary, so that we can properly decode the window.orientation value whenever get_orientation() is called.
The degradeInputs plugin bails early for pages that do not have
data-role="page". This behavior prevented range inputs (for slider widgets)
from degrading properly when used in dialogs.
Updated degradeInputs unit tests to check dialogs, too.
- Modified findClosestEnabledButton() so that instead of checking for existence of ele.className, before using it, that it check for typeof ele.className === 'string'. This prevents us from looking at the className property of SVG elements which actually use type SVGAnimatedString which does not have the split() function in its API.
- Don't set the item class on the list item or it's btn-inner children until after the main processing loop. We now use a dictionary of item-classes to track what items get what set of classes and then set them all afterwards. This cuts down the per-item addClass() and children() function overhead significantly and gets us big wins on platforms like WP 7.5
Copied the 18 and 36px white icon and flipped it to black to ensure
that these are identical. Cleaned up antialiasing issues on the black
icons too. Added to valencia and default themes.
- Use $.data() instead of $.fn.data() in buttonMarkup().
- Avoid excess function overhead with a filtered children() call by walking the DOM ourselves in listview code.
- Added _findFirstElementByTagName() which does basic DOM traversal to find the first of an element with the given nodeName. Use this in place of $.fn.closest() and $.fn.children() calls that filter with ":eq(0)".
- Avoid calling $.fn.add() if you can. The creation of the new collection is costing about 400 msecs.
- Avoid calling $() with markup for a single node, just use document.createElement() and pass it to $().
* 'master' of https://github.com/jquery/jquery-mobile:
Speed up listview enhancement for WP 7.5 (Mango). This change allows the 400 listview item page to load in 3-4 seconds instead of 30 seconds.
- Modified refresh() so that it manually checks for the first image in the list item or .ui-link-inherit element. This allows us to avoid executing a selector with a direct descendant and :eq(0) pseudo which is quite slow on WP 7.5 IE.
* 'master' of https://github.com/jquery/jquery-mobile:
test that title is restored on link transition to first page
Update docs/pages/page-dialogs.html
Update docs/pages/page-links.html
Update docs/pages/page-titles.html
Update docs/pages/page-anatomy.html
- Cache the nsNormalize() results so we don't have to call $.camelcase() every time jqmData() is called.
- Move the regexp used in our monkey patched $.find outside of the function to save some regex compilation cycles.
- Got rid of _itemApply() and moved it's functionality to the bottom of refresh(), doing finds from $list where we can, and li where we can't. Boom, at least 1200+ less function calls.
- Modified loadPage() so that if we are attempting to load the first page of the application document, that we first check to make sure it is in the DOM before returning our cached copy. If it is not in the DOM, we let it fall through to the ajax loading code so that it gets recreated. This is necessary since some developers are agressively pruning pages, including embedded ones, for various reasons.
- Updated verbage in the 'updatelayout' section so that it is clearer that developers should trigger this event if their application manipulates the content in any way that may trigger a change in the width/height of the page.
- Moved some of the finds we used to do for every item, out of the processing loop so we do just 3 big finds. This shaves off 200-300ms on iPad iOS 4.3.5.
- Modified buttonMarkup so that it checks options against undefined before calling jqmData(). This is necessary because false is a valid option.
- Modified listview so that it doesn't check for a data-counttheme unless it actually has a count item.
- Avoid using $.each() when you can directly iterate on the collection. This avoids extra function calling overhead.
- Avoid calling jqmData() for options that are specified.
- Avoid calling $.fn.wrapInner(), creating the DOM nodes manually is much faster.
Allows submit button values to change dynamically, and update accordingly in the UI. Such as in the event a button should read "Update" instead of "Save".
This makes all swatch fonts adhere to the global font family set in
ThemeRoller. This can be manually edited to further customize the
theme, but we're simplifying the TR UI.
* 'master' of git://github.com/jquery/jquery-mobile:
Small grammar correction in docs
Releasing 1.0rc2.
Remove build.xml as it is not as feature rich as the makefile and having two build scripts is redundant
Update README.md
Update README.md
Update to include instructions on how to build using a custom theme.
* 'master' of git://github.com/jquery/jquery-mobile:
move .structure before version in css build put filenames ✨
Added documentation for $.mobile.fixedToolbars.show/hide functions.
cleaned up test to limit event binding bleed
Also, fixed a bug in textinput.js that was placing a ui-body-null class on the input element when a data-theme was not specified directly on the input.
Style note: all standard, non-inset lists have a -15px margin to negate
the 15px of padding on the content area to make lists fill to the edges
of the screen. If you add other widgets above or below a list, the
negative margin may make these elements overlap so you'll need to add
additional spacing in your custom CSS.
Just for good measure. All HTML5 inputs are now auto enhanced into the
styled versions. We may need to decide if any of these need to be
degraded if the controls are wonky in some browsers.
- Moved the settings.transition calculation code before the code that pushes a new history item on the stack. This ensures that the proper transition is stored with the history item.
Added a section at the bottom of headers explain gin how to roll your
own headers and bars with some CSS classes and custom rules. Linked to
grids from footer page.
Titles in headers and footers had the same padding value in the CSS,
but we don't support the same markup conventions for left/right button
slot in the footer so this was truncating too early. Fixes#2706
- Fixed header/footer code now listens for a custom event "contentmodified" on the document to figure out if it should be repositioned or not. Modified collapsible and listview to fire off contentmodified whenever they modify content. Developers can also fire off this event to trigger position updates for fixed headers/footers, so this could be used to address issue #2042 and the mention of collapsible in #2596.
This addition is in response to the creation of the theme roller. It doesn't make much sense to include a theme from the framework if the user is adding his/her own from the theme roller or otherwise.
This will make it easy to quickly test key settings by going to:
jquerymobile.com/test/config
This is a bit fragile because refreshing or hitting a link with
rel=external or ajax=false will lose the setting.
normally I wouldn't accept re-ordering of tests as a solution to any problem, but the issue here was multiple changepage events overlapping during our tests. generally we have browser state issues in our test suite and we need a general solution for them which will come post 1.0
The docs incorrectly stated that the icon position could be set per
link, but this is intended as a global setting for the navbar parent.
This is working as designed and helps with visual consistency. If icon
positioning needs to be be adjusted per link, you will need to manually
apply the right classes through JS and may need to tweak CSS because
top/bottom and left/right positions have different heights.
- Fixed a bug in the hashchange handler for the pushstate/replacestate plugin that was incorrectly resolving hashchanges for ids against the current location.href, which could be a different document. We now resolve id hashes against the document URL.
- Modified changePage() so that it sets the settings.dataUrl option to the documentUrl, when navigating to the first-page of the application document. This prevents any id on the first-page from being added to the location hash. This means that URLs that used to be produced like this:
http://site.com/apps/#first-page-id
will now display as:
http://site.com/apps/
Developers that wish to get the old behavior back can register a pagebeforechange handler and do something like this:
$( document ).bind( "pagebeforechange", function( e, data ) {
var toPage = data.toPage;
if ( typeof toPage === "object" && !data.options.dataUrl && toPage[ 0 ] === $.mobile.firstPage[ 0 ] && toPage[ 0 ].id ) {
data.options.dataUrl = "#" + toPage[ 0 ].id;
}
});
The handler above will make sure that any page changes to the first-page will always display as:
http://site.com/apps/#first-page-id
the frequency of the triggered event in certain android releases ( 2.1, 2.2) appears to be dependent on a host of things other than an actual orientation change, eg alerts, zoom, and scrolling. This provides a way for the user to disable it in favor for using throttled resize while still making use of the window.orientation where its available for reliability
The value attached to the event passed into handlers was based soley on screensize which is problematic given that some implementations (eg Android 2.3) don't change the screensize until after the event is fired. The orientation property appears to report a better value where it is provided so the solution is to prefer what it reports and then fallback to the screensize caculation where necessary.
- Modified loadPage() to call isFirstPage() with fileUrl instead of absUrl. Since fileUrl is the same as absUrl, but with the dialogHashKey stripped off, it will allow us to match against the url for the first-page.
- This was a regression from my fix to loadPage() for detecting un-enhanced pages by @id as a fallback. In this particular case dataUrl was being used to create an id selector, and of course if the dataUrl is an empty string we end up using "#" as the selector. The fix is to simply check for a non-empty dataUrl.
- Switch to using "click" instead of "vclick" on collapsible headers since that is the only reliable way to prevent uncaught/mismatched clicks from firing on a different element.
The test makes use of a pageremove callback that conditionally calls preventDefault() on the event so that the test can make sure a developer can prevent a specific page from being removed from the DOM.
- Modified the pagehide callback in $.mobile._bindPageRemove() so that it fires off a "pageremove" event. Callbacks can prevent the removal of the page by simply calling preventDefault() on the pagremove event object that is passed to their callback.
- So it seems just allowing changePage() to process same toPage and fromPage is not enough. I modified the CSS3 keyframe
animation plugin so that it only removes the ui-page-active class from the fromPage if it is *NOT* the same as the toPage.
- I also re-ordered the in/out transition rules for forward/reverse transitions so that the user always views some sort of animation/motion.
- Added a new allowSamePageTransition option to the changePage() method default settings.
By default, we prevent changePage() requests when the fromPage and toPage are the same element, but folks that generate content manually/dynamically and reuse pages want to be able to transition to the same page. To allow
this, they will need to change the default value of allowSamePageTransition to true, *OR*, pass it in as an option when they manually call changePage().
It should be noted that our default transition animations assume that the formPage and toPage are different elements, so they may behave unexpectedly. It is up to the developer that turns on the allowSamePageTransitiona option
to either turn off transition animations, or make sure that an appropriate animation transition is used.
// To toggle the default behavior for all changePage() calls,
// set the default value of allowSamePageTransition to whatever
// you want it to be. The default is false.
$.mobile.changePage.defaults.allowSamePageTransition = true;
// To specify the behavior when manually calling changePage(),
// pass it as an option. If not specified, the default value
// specified by $.mobile.changepage.defaults.allowSamePageTransition
// is used.
$.mobile.changePage( "#reused-page", { allowSamePageTransition: true } );
- Added the following notifications to $.mobile.loadPage():
- pagebeforeload
- Triggered just before loadPage() attempts to dynamically load an external page.
- Developers can prevent the default loading behavior by calling preventDefault() on the event. If preventDefault() is called, it is up to the developer to call resolve()/reject() on the deferred object passed within the data object (2nd arg to the event callback).
- pageload
- Triggered after an external page has been loaded and inserted into the document.
- pageloadfailed
- Triggered when the load of an external page fails.
- Developers can prevent the default behavior (error dialog display) by calling preventDefault() on the event. If preventDefault() is called, it is up to the developer to call resolve()/reject() on the deferred object (2nd arg to the event callback).
Fixes#1666 — .ui-checkbox/.ui-radio floated rather than inline, to fix height and properly hide checkboxes/radios. Visible checkboxes/radios below labels in FF4+ (Windows). Thanks Wilto!
scrolltop as a solution isn't that great but some browsers scroll to the top
of the page to where the element bearing the id matching the hash is located
*before* the hashchange event is fired meaning we don't have an opportunity
in the changepage event lifecycle to record the scrolling properly
- Modified loadPage() so that if the data-url lookup for a given page fails, that it look for the page via id (if it is an embedded page URL). This allows us to find dynamically injected pages that are un-enhanced and missing their data-url attributes.
- On iOS, giving focus to the ui-page element causes flashing during page animations/transitions. This is due to the CSS outline property which is applied when the page is given focus. Turning outlines off for all pages prevents the flashing.
Dialog not working if $.mobile.ajaxEnabled = false
https://github.com/jquery/jquery-mobile/issues/2451
related/dup bug 2202:
Dialog loads in new page with ajaxEnabled = false
https://github.com/jquery/jquery-mobile/issues/2202
- Modified the default click handler to check if the href is for an embedded page before bailing when ajaxEnabled = false. This allows us to navigate to internal/embedded pages/dialogs on the click versus waiting for the accidental hashchange that was the result of the browser's default handling of hash fragments.
- Modified the url parser regexp so that we can find the double slash that precedes the authority. This is necessary so we can reconstruct resource urls used on some devices like Rim's Playbook that use urls like:
location:/dir1/dir2/file.html
- Modified makeAbsoluteUrl() so that it uses the new doubleSlash property in the object returned from parseUrl() instead of assuming that it is ok to use a double slash.
Re-styled collapsible and collapsible set so the content of the collapsible now is applied the ui-btn-up-%%theme%% class. This way the border will match the border of the header button. In the meantime in the ui-collapsible-content class we remove the background image and tweak the margin/padding to make everything look good.
Combined the expand/collapse handlers into a single one and made extensive use of .toggleClass()
- Make sure that our hashchange resolves non-path hashes against the documentBase. This prevents the resulting changePath() call from incorrectly resolving against the URL for the current active (external) page.
- Fixed a problem in the push-state code. A hashchange event is *NOT* fired when navigating back (window.history.back()) from an external page to an internal page. This makes sense when you think about it since hashchange is only ever fired when the hash of the current document url changes, not when the document url itself changes. The fix was to make sure that the pushstate hashchange callback always sets a state object, even on embedded page URLs. This allows the hashchange callback to be triggered from within onPopState().
Replaced all occurences of "horizontal" and "vertical" with "x" and "y".
Modified samples to use data-scroll="x|y|true".
Implemented public scrollTo(0 function that gives an optional duration parameter for animated scrolling.
Once you have your own cloned repo on your computer:
make docs
The docs will be built and available in the compiled/demos folder. You can move this folder to your web server or
other location. It has no dependencies on anything other than a basic HTML web server.
Submitting bugs
===================================
===============
If you think you've found a bug, please report it by following these instructions:
If you think you've found a bug, please visit the Issue tracker (https://github.com/jquery/jquery-mobile/issues) and create an issue explaining the problem and expected result. Be sure to include any relevant information for reproducing the issue, such as the browser/device (with version #), and the version of the jQuery Mobile code you're running. It also helps a lot to make sure that the bug still exists on jquerymobile.com/test/, as it's possible we may have fixed it already! It is also best to include code to reproduce the bug.
1. Visit the [Issue tracker: https://github.com/jquery/jquery-mobile/issues](https://github.com/jquery/jquery-mobile/issues)
2. Create an issue explaining the problem and expected result
- Be sure to include any relevant information for reproducing the issue
- Include information such as:
* Browser/device (with version #)
* The version of the jQuery Mobile code you're running
* If you are running from a git version, include the date and/or hash number
- Make sure that the bug still exists at http://jquerymobile.com/test/ as it may be fixed already
- You can use the CDN hosted JS and CSS files to test in your own code by using:
- Include a link to some code of the bug in action. You can use either of these services to host your code
* [jsbin](http://jsbin.com)
* [jsfiddle](http://jsfiddle.net)
3. Submit the issue.
Recommended: [JS Bin issue template with instructions](http://jsbin.com/obowiw/edit)
Submitting patches
===================================
To contribute code and bug fixes to jQuery Mobile: fork this project on Github, make changes to the code in your fork, and then send a
"pull request" to notify the team of updates that are ready to be reviewed for inclusion.
Detailed instructions can be found at https://gist.github.com/726275
==================
To contribute code and bug fixes to jQuery Mobile: fork this project on Github, make changes to the code in your fork,
and then send a "pull request" to notify the team of updates that are ready to be reviewed for inclusion.
Detailed instructions can be found at [jQuery Mobile Patching](https://gist.github.com/1294035)
Running the jQuery Mobile demos & docs locally
===================================
==============================================
To preview locally, you'll need to clone a local copy of this repository and point your Apache & PHP webserver at its
root directory (a webserver is required, as PHP and .htaccess are used for combining development files).
To preview locally, you'll need to clone a local copy of this repository and point your Apache & PHP webserver at its root directory (a webserver is required, as PHP and .htaccess are used for combining development files).
If you don't currently have a webserver running locally, there are a few options.
If you don't currently have a webserver running locally, there are a few options.
If you're on a Mac, you can try dropping jQuery Mobile into your sites folder and turning on Web Sharing via System
Prefs. From there, you'll find a URL where you can browse folders in your sites directory from a browser.
If you have python installed (most Linux distributions) and Mac OSX, you use the built-in simple web server. Open a terminal/shell and change to the jQuery Mobile folder then type 'python -m SimpleHTTPServer', and voila you can then browse via http://localhost:8000.
Another quick way to get up and running is to download and install MAMP for Mac OSX. Once installed, just open MAMP,
click preferences, go to the Apache tab, and select your local jQuery Mobile folder as the root. Then you can open a
browser to http://localhost:8888 to preview the code.
If you're on a Mac, you can try dropping jQuery Mobile into your sites folder and turning on Web Sharing via System Prefs. From there, you'll find a URL where you can browse folders in your sites directory from a browser.
Another alternative is XAMPP (Mac, Windows). You need to actually modify Apache's httpd.conf to point to your checkout:
Another quick way to get up and running is to download and install MAMP for Mac OSX. Once installed, just open MAMP, click preferences, go to the Apache tab, and select your local jQuery Mobile folder as the root. Then you can open a browser to http://localhost:8888 to preview the code.
You need the following Apache modules loaded:
Another alternative is XAMPP, which is also available for Windows, though you need to actually modify Apache's httpd.conf to point to your checkout: http://www.apachefriends.org/en/xampp.html
You need the Rewrite (mod_rewrite.so), Expire (mod_expires.so) and Header (mod_headers.so) modules loaded.
* Rewrite (mod\_rewrite.so)
* Expire (mod\_expires.so)
* Header (mod\_headers.so)
Alternatively, with the addition of async loading, you can use the python simple http server from the project root:
$ python -m SimpleHTTPServer 8000
And in your browser visit [localhost:8000](http://localhost:8000).
AMD Support in Development
==========================
Please bear in mind that async loading is not supported for production and is primarily used for the project's build process. As a result developers should expect an initial flash of unstyled content, which will not occur when the library is compiled.
If you find dependency bugs when using the async loading support for development please log them in the github issue tracker.
Building With A Custom Theme
============================
To use a custom theme in your own build, you'll need Make installed. You can find the themes in the CSS/Themes folder.
To create a new theme:
1. Copy the `Default` folder from CSS/Themes to a new folder in the same location. The name of the folder will be the
theme's name. For testing locally, make sure the index.php file is copied as well.
2. Edit the `jquery.mobile.theme.css` file so it contains your custom fonts and colors.
3. Once you are done editing your files and saving them, open a terminal.
4. Navigate to the jQuery-Mobile folder's root.
5. Run the following command to build jQuery-Mobile (THEME is the name of the folder for your theme from step 1.):
make THEME=YourThemeName
6. The compiled files will be located in the "compiled" folder in the root of jQuery-Mobile.
/* Fixes #2588 — When Windows Phone 7.5 (Mango) tries to calculate a numeric opacity for a select—including “inherit”—without explicitly specifying an opacity on the parent to give it context, a bug appears where clicking elsewhere on the page after opening the select will open the select again. */
-webkit-transform:translateX(0);/* Needed to work around an iOS 3.1 bug that causes listview thumbs to disappear when -webkit-visibility:hidden is used. */
-webkit-transform:translateX(0);/* Needed to work around an iOS 3.1 bug that causes listview thumbs to disappear when -webkit-visibility:hidden is used. */
-webkit-transform-origin:0;
-moz-backface-visibility:hidden;
-moz-transform:translateX(0);/* Needed to work around an iOS 3.1 bug that causes listview thumbs to disappear when -webkit-visibility:hidden is used. */
// Check to see if ajax can be used. This does a quick ajax request and blocks the page until its done
$.ajax({
url:'.',
async:false,
isLocal:true
}).error(function(){
// Ajax doesn't work so turn it off
$(document).bind("mobileinit",function(){
$.mobile.ajaxEnabled=false;
varmessage=$('<div>',{
'class':"ui-footer ui-bar-e",
style:"overflow: auto; padding:10px 15px;",
'data-ajax-warning':true
});
message
.append("<h3>Note: Navigation may not work if viewed locally</h3>")
.append("<p>The AJAX-based navigation used throughout the jQuery Mobile docs may need to be viewed on a web server to work in certain browsers. If you see an error message when you click a link, try a different browser or <a href='https://github.com/jquery/jquery-mobile/wiki/Downloadable-Docs-Help'>view help</a>.</p>");
<li><strong>Built on jQuery core</strong> for familiar and consistent jQuery syntax and minimal learning curve</li>
<li><strong>Compatible with all major mobile & desktop platforms</strong> - iOS, Android, Blackberry, Palm WebOS, Nokia/Symbian, Windows Mobile, Opera Mobile/Mini, Firefox Mobile and all modern desktop browsers.</li>
<li><strong>Lightweight size</strong> (~20k compressed for all mobile functionality) and minimal image dependencies for speed.</li>
<li><strong>Built on jQuery core</strong> for familiar and consistent jQuery syntax and minimal learning curve and leverages jQuery UI code and patterns.</li>
<li><strong>Compatible with all major mobile, tablet, e-reader & desktop platforms</strong> - iOS, Android, Blackberry, Palm WebOS, Nokia/Symbian, Windows Phone 7, MeeGo, Opera Mobile/Mini, Firefox Mobile, Kindle, Nook, and all modern browsers with graded levels of support.</li>
<li><strong>Lightweight size</strong> and minimal image dependencies for speed.</li>
<li><strong>Modular architecture</strong> for creating custom builds that are optimized to only include the features needed for a particular application</li>
<li><strong>HTML5 Markup-driven configuration</strong> of pages and behavior for fast development and minimal required scripting.</li>
<li><strong>Progressive enhancement</strong> approach brings core content and functionality to all mobile, tablet and desktop platforms and a rich, installed application-like experience on newer mobile platforms.</li>
<li><strong>Automatic initialization</strong> by using HTML5 <code> data-role</code> attributes in the HTML markup to act as the trigger to automatically initialize all jQuery Mobile widgets found on a page.</li>
<li><strong>Responsive design</strong> techniques and tools allow the same underlying codebase to automatically scale from smartphone to desktop-sized screens</li>
<li><strong>Powerful Ajax-powered navigation system</strong> to enable animated page transitions while maintaining back button, bookmarking and and clean URLs though pushState. </li>
<li><strong>Accessibility</strong> features such as WAI-ARIA are also included to ensure that the pages work for screen readers (e.g. VoiceOver in iOS) and other assistive technologies.</li>
<li><strong>Touch and mouse event support</strong> streamline the process of supporting touch, mouse, and cursor focus-based user input methods with a simple API. </li>
<li><strong>UI widgets</strong> enhance native controls with touch-optimized, themable controls.</li>
<li><strong>Powerful theming framework</strong> and ThemeRoller application make highly-branded experiences easy to build.</li>
<li><strong>Unified UI widgets</strong> for common controls enhance native controls with touch-optimized, themable controls that are platform-agnostic and easy to use.</li>
<li><strong>Powerful theming framework</strong> and the <ahref="http://www.jquerymobile.com/themeroller"rel="external">ThemeRoller</a> application make highly-branded experiences easy to build.</li>
<p>jQuery Mobile provides a set of touch-friendly UI widgets and an AJAX-powered navigation system to support animated page transitions. Building your first jQuery Mobile page is easy, here's how:</p>
<h2>Create a basic page template</h2>
<p>Pop open your favorite text editor, paste in the <ahref="../pages/page-anatomy.html"id=""title="page-anatomy">page template</a> below, save and open in a browser. You are now a mobile developer!</p>
<p>Here's what's in the template. In the <code>head</code>, a meta <code>viewport</code> tag sets the screen width to the pixel width of the device and references to jQuery, jQuery Mobile and the mobile theme stylesheet from the CDN add all the styles and scripts. </p>
<p>In the <code>body</code>, a div with a <code>data-role</code> of <code>page</code> is the wrapper used to delineate a page, and the header bar (<code>data-role="header"</code>) and content region (<code>data-role="content"</code>) are added inside to create a basic page (these are both optional). These <code>data-</code> attributes are HTML5 attributes are used throughout jQuery Mobile to transform basic markup into an enhanced and styled widget.</p>
<p>Inside your content container, you can add all any standard <ahref="../content/content-html.html">HTML elements</a> - headings, lists, paragraphs, etc. You can write your own custom styles to create custom layouts by adding an additional stylesheet to the <code>head</code> after the jQuery Mobile stylesheet.</p>
<h2>Make a listview</h2>
<p>jQuery Mobile includes a diverse set of common <ahref="../lists/docs-lists.html"id=""title="docs-lists">listviews</a> that are coded as lists with a <code>data-role="listview"</code> added. Here is a simple linked list that has a role of <code>listview</code>. We're going to make this look like an inset module by adding a <code>data-inset="true"</code> and add a dynamic search filter with the <code>data-filter="true"</code> attributes.</p>
<p>The framework contains a full set of <ahref="../forms/forms-all.html">form elements</a> that automatically are enhanced into touch-friendly styled widgets. Here's a slider made with the new HTML5 input type of range, no <code>data-role</code> needed. Be sure to wrap these in a <code>form</code> element and always properly associate a <code>label</code> to every form element.</p>
<p>There are a few ways to make <ahref="../buttons/buttons-types.html"title="buttons-types">buttons</a>, but lets turn a link into a button so it's easy to click. Just start with a link and add a <code>data-role="button"</code> attribute to it. You can add an <ahref="../buttons/buttons-icons.html">icon</a> with the <code>data-icon</code> attribute and optionally set its position with the <code>data-iconpos</code> attribute.</p>
<p>jQuery Mobile has a robust <ahref="../api/themes.html"id="">theme framework</a> that supports up to 26 sets of toolbar, content and button colors, called a "swatch". Just add a <code>data-theme="e"</code> attribute to any of the widgets on this page: page, header, list, input for the slider, or button to turn it yellow. Try different swatch letters in default theme from a-e to mix and match swatches. </p>
<p>Cool party trick: add the theme swatch to the page and see how all the widgets inside the content will automatically inherit the theme (headers don't inherit, they default to swatch A).</p>
<p>When you're ready to build a custom theme, use <ahref="http://www.jquerymobile.com/themeroller"rel="external">ThemeRoller</a> to drag and drop, then download a custom theme.</p>
<h2>Go forth and build stuff</h2>
<p>This is just scratching the surface of all the cool things you can build with jQuery Mobile with little effort. Be sure to explore <ahref="../pages/page-links.html"id=""title="page-links">linking pages</a>, <ahref="../pages/page-transitions.html"id=""title="page-transitions">adding animated page transitions</a>, and <ahref="../pages/page-dialogs.html"id=""title="page-dialogs">creating dialogs</a>. Use the <ahref="../api/data-attributes.html"id=""title="data-attributes">data-attribute reference</a> to try out some of the other <code>data-</code> attributes you can play with. </p>
<p><strong>More of a developer?</strong> Great, forget everything we just covered (kidding). If you don't want to use the <code>data-</code> attribute configuration system, you can take full control of everything and call plugins directly because these are all just standard jQuery plugins built with the UI widget factory. Be sure to dig into <ahref="../api/globalconfig.html"id=""title="globalconfig">global configuration</a>, <ahref="../api/events.html"id=""title="events">events</a>, and <ahref="../api/methods.html"id=""title="methods">methods</a>. Then read up on <ahref="../pages/page-scripting.html"id=""title="page-scripting">scripting pages</a>, <ahref="../pages/page-dynamic.html"id=""title="page-dynamic">generating dynamic pages</a>, and <ahref="../pages/phonegap.html"id=""title="phonegap">building PhoneGap apps</a>.</p>
<p>To make this broad support possible, all pages in jQuery Mobile are built on a foundation of <strong>clean, semantic HTML</strong> to ensure compatibility with pretty much any web-enabled device. In devices that interpret CSS and JavaScript, jQuery Mobile applies <strong>progressive enhancement techniques</strong> to unobtrusively transform the semantic page into a rich, interactive experience that leverages the power of jQuery and CSS. <strong>Accessibility features</strong> such as WAI-ARIA are tightly integrated throughout the framework to provide support for screen readers and other assistive technologies.</p>
<imgsrc="../_assets/images/ipad-palm.png"alt="Smartphone and tablet designs"style="max-width:100%; margin-top:20px;">
<p>As of Beta 3, we've pretty much covered our target platforms for 1.0.At this stage, jQuery Mobile works on the vast majority of all modern desktop, smartphone, tablet, and e-reader platforms. In addition, feature phones and older browsersare also supported because of our progressive enhancement approach.We're very proud of our commitment to universal accessibility through our broad support for all popular platforms.</p>
<h2id="platforms">jQuery Mobile Supported Platforms</h2>
<p>jQuery Mobile has broad support for the vast majority of all modern desktop, smartphone, tablet, and e-reader platforms. In addition, feature phones and older browsersare supported because of our progressive enhancement approach.We're very proud of our commitment to universal accessibility through our broad support for all popular platforms.</p>
<p>Our <ahref="http://jquerymobile.com/gbs/">graded support matrix</a> was created over a year ago based on our goals as a project and since that time, we've been refining our grading system based on real-world device testing and the quickly evolving mobile landscape. To provide a quick summary of our browser support in Beta 1, we've created a simple A (full), B (full minus Ajax), C (basic) grade system with notes of the actual devices and versions we've been testing on in our lab.</p>
<p>The visual fidelity of the experience is highly dependent on CSS rendering capabilities of the device and platform so not all A grade experience will be pixel-perfect but that's the nature of the web.We'll be adding additional vendor-prefixed CSS rules to bring transitions, gradients and other visual improvements to non-WebKit browsers in future releases so look for even more added visual polish as we move towards 1.0.</p>
<p>We use a 3-level graded platform support system: A (full), B (full minus Ajax), C (basic). The visual fidelity of the experience is highly dependent on the CSS rendering capabilities of the device and platform so not all A grade experience will be pixel-perfect but that's the nature of the web.</p>
<li><strong>Apple iOS 3.2-5.0 beta</strong>:Tested on the original iPad (3.2 / 4.3), iPad 2 (4.3), original iPhone (3.1), iPhone 3 (3.2), 3GS (4.3), and 4 (4.3 / 5.0 beta)</li>
<li><strong>Android 2.1-2.3</strong>: Tested on the HTC Incredible (2.2), original Droid (2.2), Nook Color (2.2), HTC Aria (2.1), Google Nexus S (2.3). Functional on 1.5 & 1.6 but performance may be sluggish, tested on Google G1 (1.5)</li>
<li><strong>Android Honeycomb</strong>- Tested on the Samsung Galaxy Tab 10.1</li>
<li><strong>Windows Phone 7</strong>: Tested on the HTC 7 Surround</li>
<li><strong>Blackberry 6.0</strong>: Tested on the Torch 9800 and Style 9670</li>
<li><strong>Blackberry 7</strong><spanstyle="background: yellow; padding: 2px 5px; font-size: 10px;">NEW</span> - Tested on Nokia N8 (Symbian^3), C7 (Symbian^3), also works on N97 (Symbian^1)</li>
<li><strong>Blackberry Playbook</strong>: Tested on PlayBook version 1.0.1 / 1.0.5</li>
<li><strong>Palm WebOS (1.4-2.0)</strong>: Tested on the Palm Pixi (1.4), Pre (1.4), Pre 2 (2.0)</li>
<li><strong>Palm WebOS 3.0 </strong>- Tested on HP TouchPad</li>
<li><strong>Firebox Mobile (Beta)</strong>: Tested on Android 2.2</li>
<li><strong>Opera Mobile 11.0</strong>: Tested on the iPhone 3GS and 4 (5.0/6.0), Android 2.2(5.0/6.0), Windows Mobile 6.5 (5.0)</li>
<li><strong>Kindle 3</strong>: Tested on the built-in WebKit browser included in the Kindle 3 device</li>
<li><strong>Chrome <strong>Desktop </strong>11-13</strong> - Tested on OS X 10.6.7 and Windows 7</li>
<li><strong>Firefox Desktop 3.6-4.0</strong> - Tested onOS X 10.6.7 and Windows 7</li>
<li><strong>Apple iOS 3.2-5.0</strong> -Tested on the original iPad (4.3 / 5.0), iPad 2 (4.3), original iPhone (3.1), iPhone 3 (3.2), 3GS (4.3), and 4 (4.3 / 5.0)</li>
<li><strong>Android 2.1-2.3</strong> - Tested on the HTC Incredible (2.2), original Droid (2.2), Nook Color (2.2), HTC Aria (2.1), Google Nexus S (2.3). Functional on 1.5 & 1.6 but performance may be sluggish, tested on Google G1 (1.5)</li>
<li><strong>Android Honeycomb</strong>- Tested on the Samsung Galaxy Tab 10.1 and Motorola XOOM</li>
<li><strong>Windows Phone 7-7.5</strong> - Tested on the HTC Surround (7.0) HTC Trophy (7.5), and LG-E900 (7.5)</li>
<li><strong>Blackberry 6.0</strong> - Tested on the Torch 9800 and Style 9670</li>
<li><strong>Blackberry 7</strong> - Tested on BlackBerry® Torch 9810</li>
<li><strong>Blackberry Playbook</strong> - Tested on PlayBook version 1.0.1 / 1.0.5</li>
<li><strong>Palm WebOS (1.4-2.0)</strong> - Tested on the Palm Pixi (1.4), Pre (1.4), Pre 2 (2.0)</li>
<li><strong>Palm WebOS 3.0 </strong> - Tested on HP TouchPad</li>
<li><strong>Firebox Mobile (Beta)</strong> - Tested on Android 2.2</li>
<li><strong>Opera Mobile 11.0</strong>: Tested on Android 2.2</li>
<li><strong>Meego 1.2</strong> - Tested on Nokia 950 and N9</li>
<li><strong>Kindle 3 and Fire</strong>: Tested on the built-in WebKit browser for each</li>
<li><strong>Chrome <strong>Desktop </strong>11-15</strong>- Tested on OS X 10.6.7 and Windows 7</li>
<li><strong>Firefox Desktop 4-8</strong> - Tested onOS X 10.6.7 and Windows 7</li>
<li><strong>Internet Explorer 7-9</strong> - Tested on Windows XP, Vista and 7 (minor CSS issues)</li>
<li><strong>Opera Desktop10-11</strong> -Tested onOS X 10.6.7 and Windows 7</li>
<li><strong>SamsungBada</strong> - Tested on the device's stock Dolphin Browser</li>
<li><strong>Android UCWeb</strong> - Tested on Android 2.3</li>
<li><strong>Blackberry 5.0</strong>:Tested on the Storm 2 9550, Bold 9770</li>
<li><strong>Opera Mini (5.0-6.0)</strong> -Tested on iOS 3.2/4.3</li>
<li><strong>Windows Phone 6.5</strong> - Tested on the HTC</li>
<li><strong>Nokia Symbian^3 </strong>- Tested on Nokia N8 (Symbian^3), C7 (Symbian^3), also works on N97 (Symbian^1)</li>
</ul>
<h3style="display: block; font-size: 15px !important; font-weight: normal; background: #f0f0f0; border-left: 7px solid #FFCC33; padding: 5px 0 5px 8px;"><strong>C<strong>-grade</strong></strong> - Basic, non-enhanced HTML experience that is still functional</h3>
<ul>
<li><strong>Blackberry4.x</strong>:Tested on the Curve 8330</li>
<li><strong>Blackberry 4.x</strong> -Tested on the Curve 8330</li>
<li><strong>Windows Mobile</strong>- Tested on the HTC Leo (WInMo 5.2)</li>
<li><strong>All older smartphone platforms and featurephones</strong> - Any device that doesn't support media queries will receive the basic, C grade experience</li>
</ul>
<h3style="display: block; font-size: 15px !important; font-weight: normal; background: #f0f0f0; border-left: 7px solid #aaaaaa; padding: 6px 0 8px 8px;"><strong>Not Officially Supported - </strong>May work, but haven't been thoroughly tested or debugged</h3>
<ul>
<li><strong>Meego</strong> - Originally a target platform, but Nokia decision torelegatethis platform to "experimental", we are considering dropping support.</li>
<li><strong>SamsungBada</strong> - The project doesn't currently have test devices or emulators, but current support is known to be fairly good. Support level undecided for 1.0.</li>
<p>The jQuery Mobile framework uses HTML5 <code>data-</code> attributes to allow for markup-based initialization and configuration of widgets. These attributes are completely optional; calling plugins manually and passing options directly is also supported. To avoid naming conflicts with other plugins or frameworks that also use <code>data-</code> attributes, set a custom namespace by modifying the <ahref="globalconfig.html"><code>ns</code> global option</a>.<p>
<p>Links with <code>data-role="button"</code>. Input-based buttons and button elements are auto-enhanced, no <code>data-role</code> required</p>
<table>
<tr>
<th>data-corners</th>
<td><strong>true</strong> | false</td>
</tr>
<tr>
<th>data-icon</th>
<td>home | delete | plus | arrow-u | arrow-d | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search</td>
</tr>
<tr>
<th>data-iconpos</th>
<td><strong>left</strong> | right | top | bottom | notext</td>
</tr>
<tr>
<th>data-iconshadow</th>
<td><strong>true</strong> | false</td>
</tr>
<tr>
<th>data-inline</th>
<td>true | <strong>false</strong></td>
</tr>
<tr>
<th>data-shadow</th>
<td><strong>true</strong> | false</td>
</tr>
<tr>
<th>data-theme</th>
<td>swatch letter (a-z)</td>
</tr>
</table>
<p>Multiple buttons can be wrapped in a container with a <code>data-role="controlgroup"</code> attribute for a vertically grouped set. Add the <code>data-type="horizontal"</code> attribute for the buttons to sit side-by-side.</p>
<p>Pairs of labels and inputs with <code>type="radio"</code> are auto-enhanced, no <code>data-role</code> required</p>
<table>
<tr>
<th>data-role</th>
<td>none (prevents auto-enhancement to use native control)</td>
</tr>
<tr>
<th>data-theme</th>
<td>swatch letter (a-z) - Added to the form element</td>
</tr>
</table>
<h2><ahref="../forms/selects/">Select</a></h2>
<p>All <code>select</code> form elements are auto-enhanced, no <code>data-role</code> required</p>
<table>
<tr>
<th>data-icon</th>
<td>home | delete | plus | arrow-u | arrow-d | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search</td>
</tr>
<tr>
<th>data-iconpos</th>
<td><strong>left</strong> | right | top | bottom | notext</td>
</tr>
<tr>
<th>data-inline</th>
<td>true | <strong>false</strong></td>
</tr>
<tr>
<th>data-native-menu</th>
<td><strong>true</strong> | false</td>
</tr>
<tr>
<th>data-overlay-theme</th>
<td>swatch letter (a-z) - overlay theme for non-native selects</td>
</tr>
<tr>
<th>data-placeholder</th>
<td>true | false - Add to the Option</td>
</tr>
<tr>
<th>data-role</th>
<td>none (prevents auto-enhancement to use native control)</td>
</tr>
<tr>
<th>data-theme</th>
<td>swatch letter (a-z) - Added to the form element</td>
</tr>
</table>
<p>Multiple selects can be wrapped in a fieldset with a <code>data-role="controlgroup"</code> attribute for a vertically grouped set. Add the <code>data-type="horizontal"</code> attribute for the selects to sit side-by-side.</p>
<h2><ahref="../forms/slider/">Slider</a></h2>
<p>Inputs with <code>type="range"</code> are auto-enhanced, no <code>data-role</code> required</p>
<table>
<tr>
<th>data-role</th>
<td>none (prevents auto-enhancement to use native control)</td>
</tr>
<tr>
<th>data-theme</th>
<td>swatch letter (a-z) - Added to the form element</td>
</tr>
<tr>
<th>data-track-theme</th>
<td>swatch letter (a-z) - Added to the form element</td>
</tr>
</table>
<h2><ahref="../forms/textinputs/">Text input & Textarea</a></h2>
<p>Input <code>type="text|number|search|etc."</code> or <code>textarea</code> elements are auto-enhanced, no <code>data-role</code> required</p>
<table>
<tr>
<th>data-role</th>
<td>none (prevents auto-enhancement to use native control)</td>
</tr>
<tr>
<th>data-theme</th>
<td>swatch letter (a-z) - Added to the form element</td>
<p>jQuery Mobile offers several custom events that build upon native events to create useful hooks for development. Note that these events employ various touch, mouse, and window events, depending on event existence, so you can bind to them for use in both handheld and desktop environments. You can bind to these events like you would with other jQuery events, using <code>live()</code> or <code>bind()</code>.</p>
<divclass="ui-body ui-body-e">
<h4style="margin:.5em 0">Important: Use pageCreate(), not $(document).ready()</h4>
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, you can bind to the <code><strong>pagecreate</strong></code> event. This event is explained in detail at the bottom of this page.</div>
<h4style="margin:.5em 0">Important: Use <code>pageInit()</code>, not <code>$(document).ready()</code></h4>
<p>The first thing you learn in jQuery is to call code inside the <code>$(document).ready()</code> 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, you can bind to the <code>pageinit</code> event. This event is explained in detail at the bottom of this page.</p></div>
<p> </p>
<divclass="ui-body ui-body-e">
<h4style="margin:.5em 0">Important: <code>pageCreate()</code> vs <code>pageInit()</code></h4>
<p> Prior to Beta 2 the recommendation to users wishing to manipulate jQuery Mobile enhanced page and child widget markup was to bind to the <code>pagecreate</code> event. In Beta 2 an internal change was made to decouple each of the widgets by binding to the <code>pagecreate</code> event in place of direct calls to the widget methods. As a result, users binding to the <code>pagecreate</code> in <code>mobileinit</code> would find their binding executing before the markup had been enhanced by each of the plugins. In keeping with the lifecycle of the jQuery UI Widget Factory, the initialization method is invoked <strong>after</strong> the create method, so the <code>pageinit</code> event provides the correct timing for post enhancement manipulation of the DOM and/or Javascript objects.
In short, if you were previously using <code>pagecreate</code> to manipulate the enhanced markup before the page was shown, it's very likely you'll want to migrate to 'pageinit'.
</p></div>
<h2>Touch events</h2>
<dl>
<dt><code>tap</code></dt>
<dd>Triggers after a quick, complete touch event.</dd>
<dt><code>taphold</code></dt>
<dd>Triggers after a held complete touch event (close to one second).</dd>
<dt><code>swipe</code></dt>
<dd><p>Triggers when a horizontal drag of 30px or more (and less than 20px vertically) occurs within 1 second duration but these can be configured:</p>
<ul>
@ -46,19 +53,58 @@
<li><code>verticalDistanceThreshold</code> (default: 75px) – Swipe vertical displacement must be less than this.</li>
</ul>
</dd>
<dt><code>swipeleft</code></dt>
<dd>Triggers when a swipe event occurred moving in the left direction.</dd>
<dt><code>swiperight</code></dt>
<dd>Triggers when a swipe event occurred moving in the right direction.</dd>
</dl>
<h2>Virtual mouse events</h2>
<p>We provide a set of "virtual" mouse events that attempt to abstract away mouse and touch events. This allows the developer to register listeners for the basic mouse events, such as mousedown, mousemove, mouseup, and click, and the plugin will take care of registering the correct listeners behind the scenes to invoke the listener at the fastest possible time for that device. In touch environments, the plugin retains the order of event firing that is seen in traditional mouse environments, so for example, vmouseup is always dispatched before vmousedown, and vmousedown before vclick, etc. The virtual mouse events also normalize how coordinate information is extracted from the event, so in touch based environments, coordinates are available from the pageX, pageY, screenX, screenY, clientX, and clientY properties, directly on the event object.</p>
<dl>
<dt><code>vmouseover</code></dt>
<dd>Normalized event for handling touch or <code>mouseover</code> events</dd>
<dt><code>vmousedown</code></dt>
<dd>Normalized event for handling touchstart or <code>mousedown</code> events</dd>
<dt><code>vmousemove</code></dt>
<dd>Normalized event for handling touchmove or <code>mousemove</code> events</dd>
<dt><code>vmouseup</code></dt>
<dd>Normalized event for handling touchend or <code>mouseup</code> events</dd>
<dt><code>vclick</code></dt>
<dd>Normalized event for handling touchend or mouse <code>click</code> events. On touch devices, this event is dispatched *AFTER* vmouseup. </dd>
<dt><code>vmousecancel</code></dt>
<dd>Normalized event for handling touch or mouse <code>mousecancel</code> events</dd>
</dl>
<divclass="ui-body ui-body-e">
<h4style="margin:.5em 0">Warning: Use vclick with caution</h4>
<p> Use vclick with caution on touch devices. Webkit based browsers synthesize <code>mousedown</code>, <code>mouseup</code>, and <code>click</code> events roughly 300ms after the <code>touchend</code> event is dispatched. The target of the synthesized mouse events are calculated at the time they are dispatched and are based on the location of the touch events and, in some cases, the implementation specific heuristics which leads to different target calculations on different devices and even different OS versions for the same device. This means the target element within the original touch events could be different from the target element within the synthesized mouse events.</p>
<p>We recommend using <code>click</code> instead of <code>vclick</code> anytime the action being triggered has the possibility of changing the content underneath the point that was touched on screen. This includes page transitions and other behaviors such as collapse/expand that could result in the screen shifting or content being completely replaced.</p>
</div>
<p> </p>
<divclass="ui-body ui-body-e">
<h4style="margin:.5em 0">Canceling an elements default click behavior</h4>
<p>Applications can call <code>preventDefault()</code> on a <code>vclick</code> event to cancel an element's default click behavior. On mouse based devices, calling <code>preventDefault()</code> on a <code>vclick</code> event equates to calling <code>preventDefault()</code> on the real <code>click</code> event during the bubble event phase. On touch based devices, it's a bit more complicated since the actual <code>click</code> event is dispatched about 300ms after the <code>vclick</code> event is dispatched. For touch devices, calling <code>preventDefault()</code> on a <code>vclick</code> event triggers some code in the vmouse plugin that attempts to catch the next <code>click</code> event that gets dispatched by the browser, during the capture event phase, and calls <code>preventDefault()</code> and <code>stopPropagation()</code> on it. As mentioned in the warning above, it is sometimes difficult to match up a touch event with its corresponding mouse event because the targets can differ. For this reason, the vmouse plugin also falls back to attempting to identify a corresponding <code>click</code> event by coordinates. There are still cases where both target and coordinate identification fail, which results in the <code>click</code> event being dispatched and either triggering the default action of the element, or in the case where content has been shifted or replaced, triggering a click on a different element. If this happens on a regular basis for a given element/control, we suggest you use <code>click</code> for triggering your action.</p>
</div>
<h2>Orientation change event</h2>
<dl>
<dt><code>orientationchange</code></dt>
<dd>Triggers when a device orientation changes (by turning it vertically or horizontally). When bound to this event, your callback function can leverage a second argument, which contains an <code>orientation</code> 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.</dd>
<dd>Triggers when a device orientation changes (by turning it vertically or horizontally). When bound to this event, your callback function can leverage a second argument, which contains an <code>orientation</code> 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 <code>orientationchange</code> is not natively supported, or when <code>$.mobile.orientationChangeEnabled</code> is set to false.</dd>
<divclass="ui-body ui-body-e">
<h4>orientationchange timing</h4>
<p> The timing of the <code>orientationchange</code> 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 <code>event.orientation</code> derived from <code>window.orientation</code>. This means that if your bindings are dependent on the height and width values you may want to disable <code>orientationChange</code> all together with <code>$.mobile.orientationChangeEnabled = false</code> to let the fallback resize code trigger your bindings.</p>
</div>
</dl>
<h2>Scroll events</h2>
<dl>
<dt><code>scrollstart</code></dt>
@ -67,128 +113,399 @@
<dl>
<dt><code>scrollstop</code></dt>
<dd>Triggers when a scroll finishes.</dd>
</dl>
<h2>Page show/hide events</h2>
<p>Whenever a page is shown or hidden in jQuery Mobile, two events are triggered on that page. The events triggered depend on whether that page is being shown or hidden, so when a page transition occurs, there are actually 4 events triggered: 2 for each page. </p>
</dl>
<h2>Page load events</h2>
<p>Whenever an external page is loaded into the application DOM, 2 events are fired. The first is <code>pagebeforeload</code>. The 2nd event will be either <code>pageload</code> or <code>pageloadfailed</code>.</p>
<dl>
<dt><code>pagebeforeload</code></dt>
<dd><p>Triggered before any load request is made. Callbacks bound to this event can call <code>preventDefault()</code> on the event to indicate that they are handling the load request. Callbacks that do this *MUST* make sure they call <code>resolve()</code> or <code>reject()</code> on the deferred object reference contained in the data object passed to the callback.</p>
<p>The data object, passed as the 2nd arg to the callback function contains the following properties:</p>
<ul>
<li><code>url</code> (string)
<ul>
<li>The absolute or relative URL that was passed into $.mobile.loadPage() by the caller.</li>
</ul>
</li>
<li><code>absUrl</code> (string)
<ul>
<li>The absolute version of the url. If url was relative, it is resolved against the url used to load the current active page.</li>
</ul>
</li>
<li><code>dataUrl</code> (string)
<ul>
<li>The filtered version of absUrl to be used when identifying the page and updating the browser location when the page is made active.</li>
</ul>
</li>
<li><code>deferred</code> (object)
<ul>
<li>Callbacks that call preventDefault() on the event, *MUST* call resolve() or reject() on this object so that changePage() requests resume processing. Deferred object observers expect the deferred object to be resolved like this:</p>
<pre><code>
$( document ).bind( "pagebeforeload", function( event, data ){
// Let the framework know we're going to handle the load.
event.preventDefault();
// ... load the document then insert it into the DOM ...
// at some point, either in this callback, or through
// some other async means, call resolve, passing in
// the following args, plus a jQuery collection object
<li>This object contains the options that were passed into $.mobile.loadPage().</li>
</ul>
</li>
</ul>
</dd>
<dt><code>pageload</code></dt>
<dd>Triggered after the page is successfully loaded and inserted into the DOM. Callbacks bound to this event will be passed a data object as its 2nd arg. This object contains the following information:
<ul>
<li><code>url</code> (string)
<ul>
<li>The absolute or relative URL that was passed into $.mobile.loadPage() by the caller.</li>
</ul>
</li>
<li><code>absUrl</code> (string)
<ul>
<li>The absolute version of the url. If url was relative, it is resolved against the url used to load the current active page.</li>
</ul>
</li>
<li><code>dataUrl</code> (string)
<ul>
<li>The filtered version of absUrl to be used when identifying the page and updating the browser location when the page is made active.</li>
</ul>
</li>
<li><code>options</code> (object)
<ul>
<li>This object contains the options that were passed into $.mobile.loadPage().</li>
</ul>
</li>
<li><code>xhr</code> (object)
<ul>
<li>The jQuery XMLHttpRequest object used when attempting to load the page. This is what gets passed as the 3rd argument to the framework's $.ajax() success callback.</li>
</ul>
</li>
<li><code>textStatus</code> (null or string)
<ul>
<li>According to the jQuery Core <ahref="http://api.jquery.com/jQuery.ajax/">documentation</a>, this will be a string describing the status. This is what gets passed as the 2nd argument to the framework's $.ajax() error callback.</li>
</ul>
</li>
</ul>
</dd>
<dt><code>pageloadfailed</code></dt>
<dd>Triggered if the page load request failed. By default, after dispatching this event, the framework will display a page failed message and call reject() on the deferred object contained within the event's data object. Callbacks can prevent this default behavior from executing by calling preventDefault() on the event.
<p>The data object, passed as the 2nd arg to the callback function contains the following properties:</p>
<ul>
<li><code>url</code> (string)
<ul>
<li>The absolute or relative URL that was passed into $.mobile.loadPage() by the caller.</li>
</ul>
</li>
<li><code>absUrl</code> (string)
<ul>
<li>The absolute version of the url. If url was relative, it is resolved against the url used to load the current active page.</li>
</ul>
</li>
<li><code>dataUrl</code> (string)
<ul>
<li>The filtered version of absUrl to be used when identifying the page and updating the browser location when the page is made active.</li>
</ul>
</li>
<li><code>deferred</code> (object)
<ul>
<li>Callbacks that call preventDefault() on the event, *MUST* call resolve() or reject() on this object so that changePage() requests resume processing. Deferred object observers expect the deferred object to be resolved like this:</p>
<pre><code>
$( document ).bind( "pageloadfailed", function( event, data ){
// Let the framework know we're going to handle things.
event.preventDefault();
// ... attempt to load some other page ...
// at some point, either in this callback, or through
// some other async means, call resolve, passing in
// the following args, plus a jQuery collection object
<li>This object contains the options that were passed into $.mobile.loadPage().</li>
</ul>
</li>
<li><code>xhr</code> (object)
<ul>
<li>The jQuery XMLHttpRequest object used when attempting to load the page. This is what gets passed as the first argument to the framework's $.ajax() error callback.</li>
</ul>
</li>
<li><code>textStatus</code> (null or string)
<ul>
<li>According to the jQuery Core <ahref="http://api.jquery.com/jQuery.ajax/">documentation</a>, possible values for this property, aside from null, are "timeout", "error", "abort", and "parsererror". This is what gets passed as the 2nd argument to the framework's $.ajax() error callback.</li>
<li>According to the jQuery Core <ahref="http://api.jquery.com/jQuery.ajax/">documentation</a>, this property may be an exception object if one occured, or if an HTTP error occured this will be set to the textual portion of the HTTP status. This is what gets passed as the 3rd argument to the framework's $.ajax() error callback.</li>
</ul>
</li>
</ul>
</dd>
</dl>
<h2>Page change events</h2>
<p>Navigating between pages in the application is usually accomplished through a call to <code>$.mobile.changePage()</code>. This function is responsible for making sure that the page we are navigating to is loaded and inserted into the DOM, and then kicking off the transition animations between the current active page, and the page the caller wants to to make active. During this process, which is usually asynchronous, changePage() will fire off 2 events. The first is <code>pagebeforechange</code>. The second event depends on the success or failure of the change request. It will either be <code>pagechange</code> or <code>pagechangefailed</code>.</p>
<dl>
<dt><code>pagebeforechange</code></dt>
<dd>This event is triggered prior to any page loading or transition. Callbacks can prevent execution of the changePage() function by calling preventDefault on the event object passed into the callback. The callback also recieves a data object as its 2nd arg. The data object has the following properties:
<ul>
<li><code>toPage</code> (object or string)
<ul>
<li>This property represents the page the caller wishes to make active. It can be either a jQuery collection object containing the page DOM element, or an absolute/relative url to an internal or external page. The value exactly matches the 1st arg to the changePage() call that triggered the event.</li>
</ul>
</li>
<li><code>options</code> (object)
<ul>
<li>This object contains the configuration options to be used for the current changePage() call.</li>
</ul>
</li>
</ul>
<p>It should be noted that callbacks can modify both the <code>toPage</code> and <code>options</code> properties to alter the behavior of the current <code>changePage()</code> call. So for example, the <code>toPage</code> can be mapped to a different url from within a callback to do a sort of redirect.</p>
</dd>
<dt><code>pagechange</code></dt>
<dd>This event is triggered after the <code>changePage()</code> request has finished loading the page into the DOM and all page transition animations have completed. Note that any pageshow or pagehide events will have fired *BEFORE* this event is triggered. Callbacks for this particular event will be passed a data object as the 2nd arg. The properties for this object are as follows:
<ul>
<li><code>toPage</code> (object or string)
<ul>
<li>This property represents the page the caller wishes to make active. It can be either a jQuery collection object containing the page DOM element, or an absolute/relative url to an internal or external page. The value exactly matches the 1st arg to the changePage() call that triggered the event.</li>
</ul>
</li>
<li><code>options</code> (object)
<ul>
<li>This object contains the configuration options to be used for the current changePage() call.</li>
</ul>
</li>
</ul>
</dd>
<dt><code>pagechangefailed</code></dt>
<dd>This event is triggered when the <code>changePage()</code> request fails to load the page. Callbacks for this particular event will be passed a data object as the 2nd arg. The properties for this object are as follows:
<ul>
<li><code>toPage</code> (object or string)
<ul>
<li>This property represents the page the caller wishes to make active. It can be either a jQuery collection object containing the page DOM element, or an absolute/relative url to an internal or external page. The value exactly matches the 1st arg to the changePage() call that triggered the event.</li>
</ul>
</li>
<li><code>options</code> (object)
<ul>
<li>This object contains the configuration options to be used for the current changePage() call.</li>
</ul>
</li>
</ul>
</dd>
</dl>
<h2>Page transition events</h2>
<p>Page transitions are used to animate the change from the current active page (fromPage) to a new page (toPage). Events are triggered before and after these transitions so that observers can be notified whenever pages are shown or hidden. The events triggered are as follows:</p>
<dl>
<dt><code>pagebeforeshow</code></dt>
<dd>Triggered on the page being shown, before its transition begins.</dd>
<dd>Triggered on the "toPage" we are transitioning to, before the actual transition animation is kicked off. Callbacks for this event will recieve a data object as their 2nd arg. This data object has the following properties on it:
<ul>
<li><code>prevPage</code> (object)
<ul>
<li>A jQuery collection object that contains the page DOM element that we are transitioning away from. Note that this collection is empty when the first page is transitioned in during application startup.</li>
</ul>
</li>
</ul>
</dd>
<dt><code>pagebeforehide</code></dt>
<dd>Triggered on the page being hidden, before its transition begins.</dd>
<dd>Triggered on the "fromPage" we are transitioning away from, before the actual transition animation is kicked off. Callbacks for this event will recieve a data object as their 2nd arg. This data object has the following properties on it:
<ul>
<li><code>nextPage</code> (object)
<ul>
<li>A jQuery collection object that contains the page DOM element that we are transitioning to.</li>
</ul>
</li>
</ul>
<p>Note that this event will not be dispatched during the transition of the first page at application startup since there is no previously active page.</p>
</dd>
<dt><code>pageshow</code></dt>
<dd>Triggered on the page being shown, after its transition completes.</dd>
<dd>Triggered on the "toPage" after the transition animation has completed. Callbacks for this event will recieve a data object as their 2nd arg. This data object has the following properties on it:
<ul>
<li><code>prevPage</code> (object)
<ul>
<li>A jQuery collection object that contains the page DOM element that we just transitioned away from. Note that this collection is empty when the first page is transitioned in during application startup.</li>
</ul>
</li>
</ul>
</dd>
<dt><code>pagehide</code></dt>
<dd>Triggered on the page being hidden, after its transition completes.</dd>
<dd>Triggered on the "fromPage" after the transition animation has completed. Callbacks for this event will recieve a data object as their 2nd arg. This data object has the following properties on it:
<ul>
<li><code>nextPage</code> (object)
<ul>
<li>A jQuery collection object that contains the page DOM element that we just transitioned to.</li>
</ul>
</li>
</ul>
<p>Note that this event will not be dispatched during the transition of the first page at application startup since there is no previously active page.</p>
</dd>
</dl>
<p>Note that all four of these events expose a reference to either the next page (<code>nextPage</code>) or previous page (<code>prevPage</code>), depending on whether the page is being shown or hidden, and whether that next or previous page exists (the first ever page shown does not have a previous page to reference, but an empty jQuery object is provided just the same). You can access this reference via the second argument of a bound callback function. For example: </p>
<p>You can access the <code>prevPage</code> or <code>nextPage</code> properties via the second argument of a bound callback function. For example: </p>
<pre><code>
$('div').live('pageshow',function(event, ui){
alert('This page was just hidden: '+ ui.prevPage);
$('div').live('pageshow',function(event, ui){
alert('This page was just hidden: '+ ui.prevPage);
});
$('div').live('pagehide',function(event, ui){
alert('This page was just shown: '+ ui.nextPage);
$('div').live('pagehide',function(event, ui){
alert('This page was just shown: '+ ui.nextPage);
});
</code></pre>
<p>Also, for these handlers to be invoked during the initial page load, you must bind them before jQuery Mobile executes. This can be done in the <code>mobileinit</code> handler, as described on the <ahref="globalconfig.html">global config</a> page.
<h2>Page initialization events</h2>
<p>Internally, jQuery Mobile auto-initializes plugins based on the markup conventions found in a given "page". For example, an <code>input</code> element with a <code>type</code> of <code>range</code> will automatically generate a custom slider control.</p>
<p>This auto-initialization is controlled by the "page" plugin, which dispatches events before and after it executes, allowing you to manipulate a page either pre-or-post initialization, or even provide your own intialization behavior and prevent the auto-initializations from occuring. Note that these events will only fire once per "page", as opposed to the show/hide events, which fire every time a page is shown and hidden.</p>
<p>This auto-initialization is controlled by the "page" plugin, which dispatches events before and after it executes, allowing you to manipulate a page either pre-or-post initialization, or even provide your own intialization behavior and prevent the auto-initializations from occuring. Note that these events will only fire once per "page", as opposed to the show/hide events, which fire every time a page is shown and hidden.</p>
<dl>
<dt><code>pagebeforecreate</code></dt>
<dd>
<p>Triggered on the page being initialized, before most plugin auto-initialization occurs.</p>
alert('This page was just inserted into the dom!');
});
</code></pre>
<p>Note that by binding to <code>pagebeforecreate</code>, you can manipulate markup before jQuery Mobile's default widgets are auto-initialized. For example, say you want to add data-attributes via JavaScript instead of in the HTML source, this is the event you'd use.</p>
// manipulate this page before its widgets are auto-initialized
});
</code></pre>
</code></pre>
</dd>
<dt><code>pagecreate</code></dt>
<dd>
<p>Triggered when the page has been created in the DOM (via ajax or other) but before all widgets have had an opportunity to enhance the contained markup. This event is most useful for user's wishing to create their own custom widgets for child markup enhancement as the jquery mobile widgets do.</p>
<p>Triggered on the page being initialized, 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.</p>
alert('This page was just enhanced by jQuery Mobile!');
});
</code></pre>
</dd>
</dl>
<h2>Virtual mouse events</h2>
<p>We provide a set of "virtual" click events that normalize mouse and touch events. This allows the developer to register listeners for the basic mouse events, such as mousedown, mousemove, mouseup, and click, and the plugin will take care of registering the correct listeners behind the scenes to invoke the listener at the fastest possible time for that device. This still retains the order of event firing in the traditional mouse environment, should multiple handlers be registered on the same element for different events.</p>
<h2>Page remove events</h2>
<p>By default, the framework removes any non active dynamically loaded external pages from the DOM as soon as the user navigates away to a different page. The <code>pageremove</code> event is dispatched just before the framework attempts to remove the a page from the DOM.</p>
<dl>
<dt><code>vmouseover</code></dt>
<dd>Normalized event for handling touch or mouse <code>mouseover</code> events</dd>
<dt><code>vmousedown</code></dt>
<dd>Normalized event for handling touch or mouse <code>mousedown</code> events</dd>
<dt><code>vmousemove</code></dt>
<dd>Normalized event for handling touch or mouse <code>mousemove</code> events</dd>
<dt><code>vmouseup</code></dt>
<dd>Normalized event for handling touch or mouse <code>mouseup</code> events</dd>
<dt><code>vclick</code></dt>
<dd>Normalized event for handling touch or mouse <code>click</code> events</dd>
<dt><code>vmousecancel</code></dt>
<dd>Normalized event for handling touch or mouse <code>mousecancel</code> events</dd>
<dt><code>pageremove</code></dt>
<dd>This event is triggered just before the framework attempts to remove an external page from the DOM. Event callbacks can call preventDefault on the event object to prevent the page from being removed.
</dd>
</dl>
<h2>Layout events</h2>
<p>Some components within the framework, such as collapsible and listview search, dynamically hide and show content based on user events. This hiding/showing of content affects the size of the page and may result in the browser adjusting/scrolling the viewport to accommodate the new page size. Since this has the potential to affect other components such as fixed headers and footers, components like collapsible and listview trigger a custom <code>updatelayout</code> event to notify other components that they may need to adjust their layouts in response to their content changes. Developers who are building dynamic applications that inject, hide, or remove content from the page, or manipulate it in any way that affects the dimensions of the page, can also manually trigger this <code>updatelayout</code> event to ensure components on the page update in response to the changes.</p>
<dl>
<dt><code>updatelayout</code></dt>
<dd>This event is triggered by components within the framework that dynamically show/hide content, and is meant as a generic mechanism to notify other components that they may need to update their size or position. Within the framework, this event is fired on the component element whose content was shown/hidden, and bubbles all the way up to the document element.
<pre><code>
$( '#foo' ).hide().trigger( 'updatelayout' );
</code></pre>
</dd>
</dl>
<h2>Animation Events</h2>
<p>jQuery Mobile exposes the <code>animationComplete</code> plugin, which you can utilize after adding or removing a class that applies a CSS transition.</p>
<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 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>
<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>
<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>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>Within this event binding, you can configure defaults either by extending the <code>$.mobile</code> object using jQuery's <code>$.extend</code> method:</p>
<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>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>
<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>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>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 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>
<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>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 <ahref="../pages/page-navmodel.html">recommend</a> disabling this feature if Ajax is disabled or if extensive use of external links are used.</dd>
<dd>Enable pages to have self-contained native scrolling and fixed toolbars in devices that support the <code>overflow-scrolling: touch; </code>property.</dd>
<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>
<pclass="ui-bar-e ui-body"><strong>Note: This feature is deprecated in beta, and will be removed after that. We recommend using CSS3 Media Queries instead.</strong></p>
<pclass="ui-bar-e ui-body"><strong>Note: This feature was deprecated in beta, and removed in 1.0rc1. We recommend using CSS3 Media Queries instead.</strong> To support older versions of Internet Explorer, check out <ahref="https://github.com/scottjehl/Respond">respond.js</a>, a fast & lightweight polyfill for min/max-width CSS3 Media Queries.</p>
<pclass="ui-bar-e ui-body">If you still need this feature, you can find the code here: <ahref="https://raw.github.com/jquery/jquery-mobile/38d7ad8848f00b0921bf4ae723f3ad199eb851c1/js/jquery.mobile.media.classes.js">jquery.mobile.media.classes.js</a></p>
<p>jQuery Mobile adds classes to the <code>HTML</code> element that mimic browser orientation and common min/max-width CSS media queries. These classes are updated on load, resize and orientationchange, allowing you to key off these classes in your CSS, to create <ahref="http://www.alistapart.com/articles/responsive-web-design/">responsive layouts</a> - even in browsers that don't support media queries! </p>
<h3>Orientation Classes </h3>
<p>The HTML element will always have a class of either "portrait" or "landscape", depending on the orientation of the browser or device. You can utilize these in your CSS like this:</p>
<p>The HTML element will always have a class of either <code>"portrait"</code> or <code>"landscape"</code>, depending on the orientation of the browser or device. You can utilize these in your CSS like this:</p>
<pre>
<code>
.portrait {
@ -42,7 +43,7 @@
</pre>
<h3>Min/Max Width Breakpoint Classes</h3>
<p>By default, we create min and max breakpoint classes at the following widths: <code>320</code>,<code>480</code>,<code>768</code>,<code>1024</code>. These translate to classes that look like this: "min-width-320px", "max-width-480px", and are meant to be used as a replacement of (or in addition to) the media query equivalents they mimic.</p>
<p>By default, we create min and max breakpoint classes at the following widths: <code>320</code>,<code>480</code>,<code>768</code>,<code>1024</code>. These translate to classes that look like this: <code>"min-width-320px"</code>, <code>"max-width-480px"</code>, and are meant to be used as a replacement of (or in addition to) the media query equivalents they mimic.</p>
<pre>
<code>
.myelement {
@ -100,7 +101,7 @@ $.mobile.media("screen and (-webkit-min-device-pixel-ratio: 2)");
<li><code>transition</code> (<em>string</em>, default: $.mobile.defaultPageTransition) The transition to use when showing the page. </li>
<li><code>reverse</code> (<em>boolean</em>, default: false) Decides what direction the transition will run when showing the page. </li>
<li><code>allowSamePageTransition</code> (<em>boolean</em>, default: false) By default, changePage() ignores requests to change to the current active page. Setting this option to true, allows the request to execute. Developers should note that some of the page transitions assume that the fromPage and toPage of a changePage request are different, so they may not animate as expected. Developers are responsible for either providing a proper transition, or turning it off for this specific case.</li>
<li><code>changeHash</code> (<em>boolean</em>, default: true) Decides if the hash in the location bar should be updated. </li>
<li><code>role</code> (<em>string</em>, default: undefined) The data-role value to be used when displaying the page. By default this is undefined which means rely on the value of the @data-role attribute defined on the element.</li>
<li><code>pageContainer</code> (jQuery collection, default: $.mobile.pageContainer) Specifies the element that should contain the page. </li>
<li><code>type</code> (<em>string</em>, default: "get") Specifies the method ("get" or "post") to use when making a page request.
<ul>
<li>Used only when the 'to' argument of changePage() is a URL.</li>
</ul>
</li>
<li><code>data</code> (<em>object</em> or string, default: undefined) The data to send with an Ajax page request.
<ul>
<li>Used only when the 'to' argument of changePage() is a URL.</li>
</ul>
</li>
</li>
<li><code>dataUrl</code> (string, default: undefined) The URL to use when updating the browser location upon changePage completion.
If not specified, the value of the data-url attribute of the page element is used.</li>
<li><code>pageContainer</code> (jQuery collection, default: $.mobile.pageContainer) Specifies the element that should contain the page. </li>
<li><code>reloadPage</code> (<em>boolean</em>, default: false) Forces a reload of a page, even if it is already in the DOM of the page container.
<ul>
<li>Used only when the 'to' argument of changePage() is a URL.</li>
</ul>
</li>
<li><code>reverse</code> (<em>boolean</em>, default: false) Decides what direction the transition will run when showing the page. </li>
<li><code>showLoadMsg</code> (<em>boolean</em>, default: true) Decides whether or not to show the loading message when loading external pages.</li>
<li><code>role</code> (<em>string</em>, default: undefined) The data-role value to be used when displaying the page. By default this is undefined which means rely on the value of the @data-role attribute defined on the element.</li>
<li><code>transition</code> (<em>string</em>, default: $.mobile.defaultPageTransition) The transition to use when showing the page. </li>
<li><code>type</code> (<em>string</em>, default: "get") Specifies the method ("get" or "post") to use when making a page request.
<ul>
<li>Used only when the 'to' argument of changePage() is a URL.</li>
<li><code>role</code> (<em>string</em>, default: undefined) The data-role value to be used when displaying the page. By default this is undefined which means rely on the value of the @data-role attribute defined on the element.</li>
<li><code>data</code> (<em>object</em> or string, default: undefined) The data to send with an Ajax page request. </li>
<li><code>loadMsgDelay</code> (<em>number (in ms)</em>, default: 50) Forced delay before the loading message is shown. This is meant to allow time for a page that has already been visited to be fetched from cache without a loading message.</li>
<li><code>pageContainer</code> (jQuery collection, default: $.mobile.pageContainer) Specifies the element that should contain the page after it is loaded. </li>
<li><code>reloadPage</code> (<em>boolean</em>, default: false) Forces a reload of a page, even if it is already in the DOM of the page container. </li>
<li><code>role</code> (<em>string</em>, default: undefined) The data-role value to be used when displaying the page. By default this is undefined which means rely on the value of the @data-role attribute defined on the element.</li>
<li><code>type</code> (<em>string</em>, default: "get") Specifies the method ("get" or "post") to use when making a page request.
</li>
<li><code>data</code> (<em>object</em> or string, default: undefined) The data to send with an Ajax page request. </li>
<li><code>reloadPage</code> (<em>boolean</em>, default: false) Forces a reload of a page, even if it is already in the DOM of the page container. </li>
<li><code>loadMsgDelay</code> (<em>number (in ms)</em>, default: 50) Forced delay before the loading message is shown. This is meant to allow time for a page that has already been visited to be fetched from cache without a loading message.</li>
<dd>When working with jQuery Mobile, <code>jqmData</code> and <code>jqmRemoveData</code> should be used in place of jQuery core's <code>data</code> and <code>removeData</code> methods (note that this includes $.fn.data, $.fn.removeData, and the $.data, $.removeData, and $.hasData utilities), as they automatically incorporate getting and setting of namespaced data attributes (even if no namespace is currently in use).</dd>
<dd>
<dl>
<dt><code>·</code> Arguments:</dt>
<dd>See jQuery's <ahref="http://api.jquery.com/jQuery.data/">data</a> and <ahref="http://api.jquery.com/jQuery.removeData/">removeData</a> methods</dd>
<strong>Note: </strong>Calling jqmData() with no argument will return <code>undefined</code>. This behavior is subject to change in future versions.
<dt><code>·</code> Also:</dt>
<dd>When finding elements by their jQuery Mobile data attribute, please use the custom selector <code>:jqmData()</code>, as it automatically incorporates namespaced data attributes into the lookup when they are in use. For example, instead of calling <code>$("div[data-role='page']")</code>, you should use <code>$("div:jqmData(role='page')")</code>, which internally maps to <code>$("div[data-"+ $.mobile.ns +"role='page']")</code> without forcing you to concatenate a namespace into your selectors manually.</dd>
<dd>Utility method for displaying the fixed header and/or footer of the current active page within the viewport. Note that fixed headers/footers are never really hidden. Toggling the show/hide state of a toolbar is really toggling whether or not they are inline within the page content, or displayed within the viewport as if they were fixed.</dd>
<dd>
<dl>
<dt><code>·</code> Arguments</dt>
<dd><code>immediately</code> (<em>boolean</em>, optional) If true, any fixed header or footer for the current active page is displayed immediately within the viewport. If false or unspecified, the fixed header/footer will fade-in after a 100 millisecond delay. Note that other events such as a document resize or scroll event can result in an additional delay before the start of the header/footer display animation.</dd>
</dl>
</dd>
<dd>Example:
<pre>
<code>
<strong>// Show fixed header/footer with a fade animation.</strong>
$.mobile.fixedToolbars.show();
<strong>// Show fixed header/footer immediately.</strong>
<dd>Utility method for hiding the fixed header and/or footer of the current active page.</dd>
<dd>
<dl>
<dt><code>·</code> Arguments</dt>
<dd><code>immediately</code> (<em>boolean</em>, optional) If true, any fixed header or footer for the current active page is immediately placed inline (back in flow) with the page content, which means it will scroll along with the content and will only be visible when viewing the top or bottom of the page within the viewport. If false or unspecified, the fixed header/footer will fade-out after a 100 millisecond delay. Note that other events such as a document resize or scroll event can result in the header/footer being immediately hidden.</dd>
</dl>
</dd>
<dd>Example:
<pre>
<code>
<strong>// Hide fixed header/footer with a fade animation.</strong>
<dd>Utility method for parsing a URL and its relative variants into an object that makes accessing the components of the URL easy. When parsing relative variants, the resulting object will contain empty string values for missing components (like protocol, host, etc). Also, when parsing URLs that have no authority, such as tel: urls, the pathname property of the object will contain the data after the protocol/scheme colon.</dd>
@ -215,7 +259,7 @@ $.mobile.hidePageLoadingMsg();
<dd>The port specified within the URL. Most URLs rely on the default port for the protocol used, so this may be an empty string most of the time.</dd>
<dt><code>protocol</code></dt>
<dd>The protocol for the URL including the trailing ':' character.</dd>
<dt><code>search<</code>/dt>
<dt><code>search</code></dt>
<dd>The query component of the URL including the leading '?' character.</dd>
</dl>
<p>But it also contains additional properties that provide access to additional components as well as some common forms of the URL developers access:</p>
@ -422,7 +466,7 @@ var isRel = $.mobile.path.isRelativeUrl("#foo");
<dd><code>url</code> (<em>string</em>, required) A relative or absolute URL.</dd>
<dt><code>·</code> Return Value</dt>
<dd>This function returns a boolean true if the URL is absolute, false if it is absolute.</dd>
<dd>This function returns a boolean true if the URL is absolute, false if not.</dd>
<dd>Add width breakpoints to the min/max width classes that are added to the HTML element.</dd>
<dd>
<dl>
<dt><code>·</code> Arguments:</dt>
<dd><code>values</code> (<em>number or array</em>). Pass any number or array of numbers to add to the resolution classes. Read more about this feature here: <ahref="mediahelpers.html">Orientation & resolution targeting</a>.</dd>
<li>A <strong>simplified icon set</strong> including those most commonly used for mobile, in a sprite to reduce image weight</li>
</ul>
<h2>ThemeRoller</h2>
<ahref="http://www.jquerymobile.com/themeroller"rel="external"><imgsrc="../_assets/images/themroller-mobile-logo.png"width="250"style="float:right; margin-left:25px;"alt="Themroller Mobile Logo"></a>
The easiest way to create custom themes is with the <ahref="http://www.jquerymobile.com/themeroller"rel="external">ThemeRoller tool</a>. It allows you to build a theme, then download a custom CSS file, ready to be dropped into your project.
<h2>Themes & swatches</h2>
@ -51,11 +53,11 @@
<p>The default theme contains the following five Bar styles:</p>
<divclass="swatch-preview">
<divclass="ui-bar ui-bar-a">Bar A</div>
<divclass="ui-bar ui-bar-b">Bar B</div>
<divclass="ui-bar ui-bar-c">Bar C</div>
<divclass="ui-bar ui-bar-d">Bar D</div>
<divclass="ui-bar ui-bar-e">Bar E</div>
<divclass="ui-bar ui-bar-a">Bar A - <ahref="#"data-role="none"class="ui-link">Link</a></div>
<divclass="ui-bar ui-bar-b">Bar B - <ahref="#"data-role="none"class="ui-link">Link</a></div>
<divclass="ui-bar ui-bar-c">Bar C - <ahref="#"data-role="none"class="ui-link">Link</a></div>
<divclass="ui-bar ui-bar-d">Bar D - <ahref="#"data-role="none"class="ui-link">Link</a></div>
<divclass="ui-bar ui-bar-e">Bar E - <ahref="#"data-role="none"class="ui-link">Link</a></div>
</div><!-- end swatch-bars -->
<p>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 <code> data-theme</code> 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 <ahref="../toolbars/bars-themes.html">toolbar theming</a>.</p>
@ -66,17 +68,17 @@
<p>The default theme also includes color swatch values for use in content blocks, designed to coordinate with the header color swatches in the theme. </p>
<divclass="swatch-preview">
<divclass="ui-body ui-body-a">Block A</div>
<divclass="ui-body ui-body-b">Block B</div>
<divclass="ui-body ui-body-c">Block C</div>
<divclass="ui-body ui-body-d">Block D</div>
<divclass="ui-body ui-body-e">Block E</div>
<divclass="ui-body ui-body-a">Block A - <ahref="#">Link</a></div>
<divclass="ui-body ui-body-b">Block B - <ahref="#">Link</a></div>
<divclass="ui-body ui-body-c">Block C - <ahref="#">Link</a></div>
<divclass="ui-body ui-body-d">Block D - <ahref="#">Link</a></div>
<divclass="ui-body ui-body-e">Block E - <ahref="#">Link</a></div>
</div><!-- end swatch-bars -->
<p>If a theme isn't specified on a content block, the framework will default to "c" to maximize contrast against the default header "a", as shown here:</p>
<divdata-role="header"data-position="inline">
<divdata-role="header">
<ahref="#"data-icon="arrow-l">Back</a>
<h1>Default Header</h1>
</div>
@ -100,6 +102,7 @@
</div><!-- /controlgroup -->
</div>
<p>Learn more about <ahref="../content/content-themes.html">content theming</a>.</p>
@ -222,9 +225,27 @@
<h3>Icons</h3>
<p>There a core set of <ahref="../buttons/buttons-icons.html">standard icons</a> included in the framework that can be assigned to any button. To minimize the download size of the core icons, jQuery Mobile only includes these icons in white and automatically adds a semi-transparent black circle behind the icon to make sure it has good contrast on all background colors.</p>
<h3>Theme classes</h3>
<p>Assigning color swatches through the <code> data-theme</code> attribute is one way to leverage the theme system, but it's also possible to apply any of the theme swatches directly to your markup through classes to apply the colors, textures and font formatting of your theme to any markup. This is especially useful when creating your own custom layout elements or UI widgets. Here are a few common theme classes, but many more are available in the theme stylesheet:</p>
<dl>
<dt><code>ui-bar-(a-z)</code></dt>
<dd>Applies the toolbar theme styles for the selected swatch letter. Commonly used in conjunction with <code>ui-bar</code> structural class to add the standard bar padding styles.</dd>
<dt><code>ui-body-(a-z)</code></dt>
<dd>Applies the content body theme styles for the selected swatch letter. Commonly used in conjunction with <code>ui-body</code> structural class to add the standard content block padding styles. </dd>
<dt><code>ui-btn-up-(a-z)</code></dt>
<dd>Applies the button/clickable element theme styles for the selected swatch letter. Commonly used in with the <code>ui-btn-hover-(a-z)</code> and <code>ui-btn-down-(a-z)</code> interaction class states to provide visual feedback and <code>ui-btn-active</code> to indicate the selected or "on" state.</dd>
<dt><code>ui-corner-all</code></dt>
<dd>Applies the theme's global border-radius for rounded corners and is used for container or grouped items in the framework (inset lists, radiobutton sets). There are additional classes for all the possible combinations of rounded corners, for example: <code>ui-corner-tl</code> (top left only), <code>-top</code> (both top corners), <code>-left</code> (both left corners), etc. A second full set of corner classes is provided for buttons so these can have a different corner radius. These use classes with a similar naming convention, but with "btn-corner" instead of "corner", like this: <code>.ui-<strong>btn-corner</strong>-all</code>.</dd>
<dt><code>ui-shadow</code></dt>
<dd>Applies the theme's global drop shadow to any element using CSS <code>box-shadow</code> property. </dd>
<dt><code>ui-disabled</code></dt>
<dd>Applies the disabled look and feel which essentially reduces the opacity of any element with this class to 30%, hides the cursor, and sets <code>pointer-events: none;</code> which prevents any interaction in many modern browsers.</dd>
</dl>
<h3>Overriding themes</h3>
<p>The themes are meant as a solid starting point, but are meant to be customized to add the custom design elements that make your site or app unique. Since everything is controlled by CSS, it's easy to use a web inspector tool to identify the style properties you want to modify. The set of of theme classes (global) and semantic structural classes (widget-specific) added to elements provide a rich set of possible selectors to target style overrides against. We recommend adding an external stylesheet to the <code>head</code>, placed <strong>after</strong> the structure and theme stylesheet references, that contain all your style overrides. This allows you to easily update to newer versions of the library because overrides are kept separate from the library code.</p>
<p><strong>Learn more</strong> about theming individual components:</p>
<p>Bind events directly to the <code>a</code>, <code>input</code>, or <code>button</code> element. Use jQuery Mobile's <ahref="../api/events.html">virtual events</a>, or bind standard JavaScript events, like change, focus, blur, etc.:</p>
<p>To use custom icons, specify a <code> data-icon</code> value that has a unique name like <code>myapp-email</code> and the button plugin will generate a class by prefixing <code>ui-icon-</code> to the <code> data-icon</code> value and apply it to the button. You can then write a CSS rule that targets the <code>ui-icon-myapp-email</code> class to specify the icon background source. To maintain visual consistency, create a white icon 18x18 pixels saved as a PNG-8 with alpha transparency.</p>
<p>To use custom icons, specify a <code>data-icon</code> value that has a unique name like <code>myapp-email</code> and the button plugin will generate a class by prefixing <code>ui-icon-</code> to the <code> data-icon</code> value and apply it to the button: <code>ui-icon-myapp-email</code>. </p>
<p>You can then write a CSS rule in your stylesheet that targets the <code>ui-icon-myapp-email</code> class to specify the icon background source. To maintain visual consistency with the rest of the icons, create a white icon 18x18 pixels saved as a PNG-8 with alpha transparency.</p>
<p> In this example, we're just pointing to a standalone icon image, but you could just as easily use an icon sprite and specify the positioning instead, just like the icon sprite we use in the framework.</p>
<pre><code>.ui-icon-myapp-email {
background-image: url("app-icon-email.png");
}</code></pre>
<p>This will create the standard resolution icon, but many devices now have very high resolution displays, like the retina display on the iPhone 4. To add a HD icon, create an icon that is 36x36 pixels (exactly double the 18 pixel size), and add second rule that uses the <code>-webkit-min-device-pixel-ratio: 2</code> media query to target a rule only to high resolution displays. Specify the background image for the HD icon file and set the background size to 18x18 pixels which will fit the 36 pixel icon into the same 18 pixel space. The media query block can wrap multiple icon rules:</p>
<pre><code>
@media only screen and (-webkit-min-device-pixel-ratio: 2) {
<p>The semi-transparent black circle behind the white icon ensures good contrast on any background color so it works well with the jQuery Mobile theming system. Here are examples of the same icons sitting on top of a range of different color swatches in out theme.</p>
<p>The following options apply to <strong>all buttons</strong>:</p>
<dl>
<dt><code>corners</code><em>boolean</em></dt>
<dd>
<pclass="default">default: true</p>
<p>Applies the theme button border-radius if set to true. This option is also exposed as a data attribute: <code>data-corners="false"</code></p>
<p>Applies an icon from the <ahref="../buttons/buttons-icons.html">icon set</a>. This option is also exposed as a data attribute: <code>data-icon="star"</code></p>
<p>Positions the icon in the button. Possible values: left, right, none, notext. The notext value will display an icon-only button with no text feedback. This option is also exposed as a data attribute: <code>data-iconpos="left"</code></p>
<p>Applies the theme shadow to the button's icon if set to true. This option is also exposed as a data attribute: <code>data-iconshadow="false"</code></p>
<p>If set to true, this will make the button act like an inline button so the width is determined by the button's text. By default, this is null (false) so the button is full width, regardless of the feedback content. Possible values: true, false. This option is also exposed as a data attribute: <code>data-inline="true"</code></p>
<p>Applies the drop shadow style to the button if set to true. This option is also exposed as a data attribute: <code>data-shadow="false"</code></p>
<pclass="default">default: null, inherited from parent</p>
<p>Sets the color scheme (swatch) for all instances of this widget. It accepts a single letter from a-z that maps to the swatches included in your theme. By default, it will inherit the same swatch color as it's parent container if not explicitly set. This option is also exposed as a data attribute: <code>data-theme="a"</code></p>
<pre><code>$('a').buttonMarkup(<strong>{ theme: "a" }</strong>);</code></pre>
<p>This is used to define the selectors (element types, data roles, etc.) that will automatically be initialized as form buttons. To change which elements are initialized, bind this option to the <ahref="../api/globalconfig.html">mobileinit event</a>:</p>
<p>jQuery Mobile has a rich <ahref="../api/themes.html">theming system</a> that gives you full control of how buttons are styled. When a link is added to a container, it is automatically assigned a theme swatch letter that matches it's parent bar or content box to visually integrate the button into the parent container, like a chameleon. So a button placed inside a content container with a theme of "a" (black in the default theme) will be automatically assigned the button theme of "a" (charcoal in the default theme). Here are examples of the button theme pairings in the default theme. All buttons have the same HTML markup: </p>
<p>jQuery Mobile has a rich <ahref="../api/themes.html">theming system</a> that gives you full control of how buttons are styled. When a link is added to a container, it is automatically assigned a theme swatch letter that matches its parent bar or content box to visually integrate the button into the parent container, like a chameleon. So a button placed inside a content container with a theme of "a" (black in the default theme) will be automatically assigned the button theme of "a" (charcoal in the default theme). Here are examples of the button theme pairings in the default theme. All buttons have the same HTML markup: </p>
<p>Button can be manually assigned any of the button color swatches from the theme to add visual contrast with the container they sit inside by adding the <code> data-theme</code> attribute on the button markup and specifying a swatch letter. </p>
<p>Buttons can be manually assigned any of the button color swatches from the theme to add visual contrast with the container they sit inside by adding the <code> data-theme</code> attribute on the button markup and specifying a swatch letter. </p>
<p>Buttons that are used for navigation should be coded as anchor links, and those that submit forms as <code>button</code> elements — each will be styled identically by the framework.</p>
<p>Buttons are coded with standard HTML anchor and input elements, then enhanced by jQuery Mobile to make them more attractive and useable on a mobile device. Use anchor links (<code>a</code> elements) to mark up navigation buttons, and <code>input</code> or <code>button</code> elements for form submission. View the <ahref="../api/data-attributes.html">data- attribute reference</a> to see all the possible attributes you can add to buttons.</p>
<h2>Styling links as buttons</h2>
<p>In the main content block of a page, you can style any anchor link as a button by adding the <code> data-role="button"</code> to the link. The framework will add all necessary classes to style the link as a button. For example, this markup: </p>
<p>In the main content block of a page, you can style any anchor link as a button by adding the <code>data-role="button"</code>attribute. The framework will enhance the link with markup and classes to style the link as a button. For example, this markup: </p>
<p>Links styled like buttons have all the same visual options as true form-based buttons below, but there are a few important differences. Link-based buttons aren't part of the <code>button</code> plugin and only just use the underlying <code>buttonMarkup</code> plugin to generate the button styles so the form button methods (enable, disable, refresh) aren't supported. If you need to disable a link-based button (or any element), it's possible to apply the disabled class ui-disabled yourself with JavaScript to achieve the same effect.</p>
<h2>Form buttons</h2>
<p>For ease of styling, the framework automatically converts any <code>button</code> element or <code>input</code> with a <code>type</code> of <code>submit</code>, <code>reset</code>, <code>button</code>, or <code>image</code> into a custom styled link-based button — there is no need to add the <code> data-role="button"</code> attribute. </p>
<p>The original form-based button is hidden, but remains in the markup. When a click event fires on a link button, it triggers a click on the original form button.</p>
<p>For ease of styling, the framework automatically converts any <code>button</code> or <code>input</code> element with a <code>type</code> of <code>submit</code>, <code>reset</code>, <code>button</code>, or <code>image</code> into a custom styled button — there is no need to add the <code> data-role="button"</code> attribute. However, if needed, you can directly call the button plugin on any selector, just like any jQuery plugin:</p>
<code>
$('[type='submit']').button();
</code>
<p>To preserve events bound to the original <code>button</code> or <code>input</code>, the framework hides the original element by making it transparent and positioning it over the new button markup. When a user clicks on the the custom-styled button, they're actually clicking on the original element. To prevent a form button from being converted into an enhanced button, add the <code>data-role="none"</code> attribute and hte native control will be rendered.</p>
<p><strong>Button</strong> based button:</p>
<button>Button element</button>
<p><strong>Input type="button"</strong> based button:</p>
<inputtype="button"value="Input type=button" />
<inputtype="button"value="buttonBtn" />
<p><strong>Input type="submit"</strong> based button:</p>
<inputtype="submit"value="Input type=submit" />
<inputtype="submit"value="submitBtn" />
<p><strong>Input type="reset"</strong> based button:</p>
<inputtype="reset"value="Input type=reset" />
<inputtype="reset"value="resetBtn" />
<p><strong>Input type="image"</strong> based button:</p>
<p>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.</p>
<p>First, hit Add to Home Screen to create a new shortcut icon on the home screen. Next, open the new shortcut and hit the button below to browse the docs as a fullscreen web app.</p>
<p>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.</p>
<uldata-role="listview"data-inset="true">
<li>
<ahref="pushState.html"data-ajax="false">
<h3>pushStateEnabled - False</h3>
<p>Enhancement to use history.replaceState in supported browsers, to convert the hash-based Ajax URL into the full document path. </p>
</a>
</li>
<li>
<ahref="touchOverflow.html"data-ajax="false">
<h3>touchOverflowEnabled - True</h3>
<p>Enable smoother page transitions and true fixed toolbars in devices that support both the overflow: and overflow-scrolling: touch; CSS properties.</p>
</a>
</li>
<li>
<ahref="pageTransition.html"data-ajax="false">
<h3>defaultPageTransition - Fade</h3>
<p>Set the default transition for page changes that use Ajax. Set to 'none' for no transitions by default.</p>
</a>
</li>
<li>
<ahref="dialogTransition.html"data-ajax="false">
<h3>defaultDialogTransition - Flip</h3>
<p>Set the default transition for dialog changes that use Ajax. Set to 'none' for no transitions by default.</p>
</a>
</li>
<li>
<ahref="minScrollBack.html"data-ajax="false">
<h3>minScrollBack - 999</h3>
<p>Minimum scroll distance that will be remembered when returning to a page.</p>
</a>
</li>
<li>
<ahref="loadingMessage.html"data-ajax="false">
<h3>loadingMessage - false</h3>
<p>Set the text that appears when a page is loading. If set to false, the message will not appear at all.</p>
<p>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.</p>
<p>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.</p>
<h2>minScrollBack is now set to 999 (disabled)</h2>
<p>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.</p>
<h2>pageLoadErrorMessage is now "Yikes, we broke the internet!"</h2>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>The toolbar on this page should now be fixed, like a native toolbar. 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.</p>