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().
Also checking in the first example of how to use the pagebeforechange notification to allow for dynamically updating and re-using a page that is already in the DOM.
- Added "dataUrl" option to changePage(). This allows a caller to specify a page element to change to, but specify an alternate URL for location display purposes. This is useful for dynamic applications that re-use and over-write existing page content to avoid overwhelming the DOM.
- Renamed the "beforechangepage" and "changepage" events to "pagebeforechange" and "pagechange" respectively. This was done to match the page widget naming of its notifications. Left the triggers for the old events in place but with DEPRECATED comments.
- Renamed the properties of the data object passed to the page events.
jquery.mobile.vmouse.js:
- Modified triggerVirtualEvent() so that it returns the virtual event instead of the isDefaultPrevented() result of the virtual event.
- Updated all references to triggerVirtualEvent() that relied on the boolean return value to instead check the isDefaultPrevented() call on the event now returned.
- Updated mouseEventCallback() to propagate the iDefaultPrevented(), isPropagationStopped(), and stopImmediatePropagation() values from the virtual event on to the original mouse event.
jquery.mobile.event.js
- Modified the "taphold" trigger code to create a new $.Event() instead of passing the stale vmousedown event.
- Added clearTapTimer() which is called from a new vmouseup binding, to prevent the timer from firing between the tie the finger/mouse goes up and the click event is dispatched.
- Added some propagation tests for the "tap" event. Tests for "taphold" will have to wait until we fix the problem where multiple taphold timers are fired off when an element and one of its ancestors is bound to taphold.
I removed the binding for the handler completely since it doesn't hurt to just leave the transition in place. I also removed the code that was setting the position of the slider since it really should only be set within the mouseup if the user did not change the switch setting (toggle).
- Changed the target selector for ui-slider-handle-snapping from:
div.ui-slider-handle-snapping
to:
a.ui-slider-handle-snapping
to match the actual markup being generated.
- Trigger the list item and keyboard return/space key up to the "click" event instead of "vclick". This delays the dismissal of the custom select menu until the click event, thereby avoiding the case where the menu disappears before the browser dispatches it's synthesized mouse events (in the touch case) with a target of whatever element was underneath the menu.
- Moved the setting of isPageTransitioning *AFTER* the beforechangepage notification.
- Modified the trigger("beforechangepage") call to pass the args to changePage() as an object since trigger only expects one data arg.
Also, this change removes a reference in memory that we were keeping to the $activeClickedLink on each page. We stored this in attempt to refocus a link after returning to a page. Unfortunately, it doesn't seem that this data can be retained after pages are removed from the DOM, outside of somehow remembering a unique selector string to reach that element again (which could be achieved by adding some overhead, ala http://stackoverflow.com/questions/2068272/getting-a-jquery-selector-for-an-element )
jquery.mobile.vmouse.js:
- Modified triggerVirtualEvent() so that it returns the virtual event instead of the isDefaultPrevented() result of the virtual event.
- Updated all references to triggerVirtualEvent() that relied on the boolean return value to instead check the isDefaultPrevented() call on the event now returned.
- Updated mouseEventCallback() to propagate the iDefaultPrevented(), isPropagationStopped(), and stopImmediatePropagation() values from the virtual event on to the original mouse event.
jquery.mobile.event.js
- Modified the "taphold" trigger code to create a new $.Event() instead of passing the stale vmousedown event.
- Added clearTapTimer() which is called from a new vmouseup binding, to prevent the timer from firing between the tie the finger/mouse goes up and the click event is dispatched.
- Added some propagation tests for the "tap" event. Tests for "taphold" will have to wait until we fix the problem where multiple taphold timers are fired off when an element and one of its ancestors is bound to taphold.
I removed the binding for the handler completely since it doesn't hurt to just leave the transition in place. I also removed the code that was setting the position of the slider since it really should only be set within the mouseup if the user did not change the switch setting (toggle).
- Changed the target selector for ui-slider-handle-snapping from:
div.ui-slider-handle-snapping
to:
a.ui-slider-handle-snapping
to match the actual markup being generated.
- Trigger the list item and keyboard return/space key up to the "click" event instead of "vclick". This delays the dismissal of the custom select menu until the click event, thereby avoiding the case where the menu disappears before the browser dispatches it's synthesized mouse events (in the touch case) with a target of whatever element was underneath the menu.
Added a ui-li-has-count class for listview items that contain a count bubble. Changed default padding-right to 25px adjusting it to 75px when count bubble is present.
Using dom-ready within dom-ready meant that initializePage went to the end of
the queue. That brought problems when other dom-ready code expected jQM to be
set up, capable of changing pages and so on. But because $.mobile.pageContainer
is also set in initializePage, changePage and others didn't work.
Also included in this commit is a Nokia-specific condition that re-appends existing stylesheets to force them to render, as all pre-7.3 devices we tested would not render the CSS if it was referenced before the JavaScript (as we'd recommend doing). There may be a non-JS way to work around this problem, but for now, this seems to do the trick.
- Internally, each plugin self-initializes by binding to the pagecreate event.
- Unit tests have been added and adjusted to support some internal changes involved in this commit.
- In the process, the portions of the page plugin that were used to enhance the header,content,and footer sections of a native-app style page layout are now located in jquery.mobile.page.sections.js.
- No public API options have changed, except that the page plugin no longer has options for keepNative, and degradeInputs, as plugins now handle these internally (keepNative was never documented, and degradeInputs only affected slider, so it lives there now. Page options related to the page sections are now located in the page.sections script, but they are still configurable via the page plugin's options api.
- Make, Ant, and index files are updated with a new load order for all JS files.
Turns out this little code was enough to invoke the error:
"/dir1/dir2".replace(/\/?/, "");
Rewrote the regexp in path.makePathAbsolute() that was stripping leading slash, and trailing filename/slash. This gets around the problem.
Special thanks to @adambiggs for helping me test 33 iterations when trying to narrow down what in jquery.mobile.navigation.js was choking BB5.
- Added code to calculate whether to choose the documentUrl or the page Url in the case where an action is not specified on a form element.
- Fixed bug in the navigation "submit" handler where an error was being thrown if "type" was not specified.
- Fixed typo "diabled" id typos in tests/unit/navigation/index.html.
- Added tests for form submissions with no action in both base and non-base specified cases.
The included tests pass most of the time, but they need improvements as they will occasionally fail due to faulty timing in the tests themselves, as far as I can tell (the code tests out fine in our functional demos).
- Don't set a default value for the 'role' option to loadPage() and changePage(). Instead, rely on the role attribute that is on the element.
- Fixed an error that was happening when a hash change involves going from a dialog back to another dialog. I had recently made changes that assumed the 'to' variable was always going to be a url string, but it turns out in the dialog back to dialog case, it is an actual jQuery collection.
- Added changepagefailed notification for the case where the load fails. Note we still need beforeloadpage/loadpage notifications.
- Misc fixes to stop the navigation unit tests from seemingly random failures. It seems that the hash resets in setup/teardown of the test modules sometimes interferes with the changePage() requests in the tests. Added code to the setup/teardown functions to wait for the reset to complete before moving on to the tests.
- Removed unused path functions: setOrigin(), makeAbsolute(), and isQuery().
- Modified loadPage() so that it uses addSearchParams() instead of naively appending it to the URL.
- Switched the global "click" handler back to using the link @href attribute and manually converting it to an absolute URL. This was necessary because it turns out that the href property on a link is dynamically calculated at the time of access based on the *CURRENT* base tag setting. This means the same link can return a different href value if the the base tag is different each time you access it.
- We should be using makeUrlAbsolute() instead of makePathAbsolute() when calculating the documentBase.
- Removed bogus code in pathname calculatino in makeUrlAbsolute().
- Reworked calculation of search in makeUrlAbsolute() to prevent an undefined in the case where rel and abs urls have no search.
- The test case calls changePage() with a hash ("#b"). In our normal processing of clicks/form submits we strip it before calling. The old code did a strip in changePage() just in case, so I added it back in to fix the last bug.
- Check the returned active object to see if it is valid before attempting to extract the transition out of it. Default to $.mobile.defaultDialogTransition if there is no active object.
- Check the returned active object to see if it is valid before attempting to extract the transition out of it. Default to $.mobile.defaultDialogTransition if there is no active object.
- Modified changePage() to set isPageTransitioning earlier.
- Modified pageSequence() to allow the current changepage callback stack to unwind before firing off the next function in the sequence.
* docs/forms/index.html: Removed reference to the jQuery-UI Datepicker which is too heavy for mobile.
* experiments/ui-datepicker folder: deleted since it is no longer referenced.
Signed-off-by: Steven Black <steveb@stevenblack.com>
- Modified changePage() click test so that it expects changePage() to be called twice.
- Added changePage() test that makes sure it is called once when it is invoked with a page element instead of a URL.
- Added siteDirectory path to be used with some tests which assumed that the tests directory was at the top-level of the server site.
Modified the hashchange callback so that it specifies a "none" transition, instead of a false boolean, for the case where the hash changed and there is nothing on the urlHistory stack.
- loadPage() now loads all pages into the DOM.
- changePage() only functions on pages that are in the DOM. If you call it with a URL instead of an element, it will call loadPage() which will then trigger a call to changePage() with the resulting page at a later time.
- Modified changePage() so that it can take an options object. Updated all references throughout the framework.
- Split $.mobile.pageLoading() into 2 functions $.mobile.show/hidePageLoadingMsg(). Updated docs accordingly.
- Renamed $.mobile.defaultTransition to $.mobie.defaultPageTransition. Updated docs accordingly.
- Added $.mobile.defaultDialogTransition so that it isn't hard coded in the changePage/transitionPages and select code.
- Hand integrated jquery.mobile.navigation.js checkins from master: 4b4ee54a, e775f5e8, e597ccb3, 084bbbd8.
jQuery Search Textbox change to add new focus event which will show clear button when some item gets pasted directly without key event to search text box. Thanks joshiabk
If 'input' element has id string with dots in it, code fails. Fixed by tweaking the regex to escape dots in the selector. Thanks markandy and eddiemonge
In the $.ajax() callback, we look for elements with @href, @src, and @data-ajax="false" elements, the code then assumes that matching elements will have either @href or @src, which of course forms don't ... they have @action ... so the code throws an exception because thisUrl is undefined.
- I reworked the code to handle action and check to make sure we have an attribute and url string before attempting to use them.
This was caused by this checkin:
4b4ee54a72
The change caused the base tag to be reset to file:// (literally with no path).
All that was missing was a small tweak to base.reset() to use the new initialPath variable instead of docBase.
Remove greedy matches from start and end of regex - there's no need for them, and they cause immense slowdown (on the order of 3-4 seconds on medium-size pages loaded via ajax).
* whitespace within parenthesis
* double quotes
* line breaking for object key assignments
Also made several changes suggested by jsHint.
All tests pass as before -- still failing first three tests as before.
Signed-off-by: Steven Black <steveb@stevenblack.com>
The expected prototype for a transitionHandler is as follows:
function handler(name, reverse, $to, $from)
The name parameter is the name of the transition as specified by @data-transition attribute, reverse is a boolean that is false for a normal transition, and true for a reverse transition. The $to param is a jQuery collection containing the page that is being transitioned "to", and $from is an optional collection that tells us what page we are transitioning "from". Because $from is optional, handler developers should take care and check $from to make sure it is not undefined before attempting to dereference it.
In addition to registering custom transition by name, developers can specify a handler to use in the case where a transition name is specified and does not exist within the $.mobile.transitionHanlders dictionary. Within jQuery Mobile, the default handler for unknown transition types is the $.mobile.css3Transition() handler. This handler always assumes that the transition name is to be used as a CSS class to be placed on the $to and $from elements. To change the default handler, simply set $.mobile.defaultTransitionHandler to you function handler:
$.mobile.defaultTransitionHandler = myTransitionHandler;
The changes to make all this necessary are as follows:
- Created $.mobile.noneTransitionHandler which is the default transitionHandler for the framework that simply adds and removes the page active class on the $from and $to pages with no animations.
- Moved class based transition code into a new plugin jquery.mobile.transition.js file. This plugin, when present, overrides the noneTransitionHandler as the defaultTranstionHandler for the framework so that CSS3 animation transitions are available.
- Removed code related to the setting/removal of the ui-mobile-viewport-perspective class. The css3TransitionHandler plugin takes care of automatically placing a "viewport-<transition name>" class on the viewport (body) element. This allows any other transition to specify properties on the viewport that are necessary to accomplish the transition.
- changed the CSS class ui-mobile-viewport-perspective to viewport-flip to match code changes. This makes it more apparent that setting -webkit-perspective is only used with the flip transition.
- Updated js/index.php, Makefile and build.xml to include the new jquery.mobile.transition.js file.
The expected prototype for a transitionHandler is as follows:
function handler(name, reverse, $to, $from)
The name parameter is the name of the transition as specified by @data-transition attribute, reverse is a boolean that is false for a normal transition, and true for a reverse transition. The $to param is a jQuery collection containing the page that is being transitioned "to", and $from is an optional collection that tells us what page we are transitioning "from". Because $from is optional, handler developers should take care and check $from to make sure it is not undefined before attempting to dereference it.
In addition to registering custom transition by name, developers can specify a handler to use in the case where a transition name is specified and does not exist within the $.mobile.transitionHanlders dictionary. Within jQuery Mobile, the default handler for unknown transition types is the $.mobile.css3Transition() handler. This handler always assumes that the transition name is to be used as a CSS class to be placed on the $to and $from elements. To change the default handler, simply set $.mobile.defaultTransitionHandler to you function handler:
$.mobile.defaultTransitionHandler = myTransitionHandler;
The changes to make all this necessary are as follows:
- Created $.mobile.noneTransitionHandler which is the default transitionHandler for the framework that simply adds and removes the page active class on the $from and $to pages with no animations.
- Moved class based transition code into a new plugin jquery.mobile.transition.js file. This plugin, when present, overrides the noneTransitionHandler as the defaultTranstionHandler for the framework so that CSS3 animation transitions are available.
- Removed code related to the setting/removal of the ui-mobile-viewport-perspective class. The css3TransitionHandler plugin takes care of automatically placing a "viewport-<transition name>" class on the viewport (body) element. This allows any other transition to specify properties on the viewport that are necessary to accomplish the transition.
- changed the CSS class ui-mobile-viewport-perspective to viewport-flip to match code changes. This makes it more apparent that setting -webkit-perspective is only used with the flip transition.
- Updated js/index.php, Makefile and build.xml to include the new jquery.mobile.transition.js file.
Removed the return false in the vclick handler of collapsible and replaced it with a preventDefault(). The only reason we were returning false was to stopPropagation() so that the vclick handler in navigation.js didn't place a ui-btn-active on it.
- Check for existence of the bindings object before attempting to use it. Apparently jQuery core strips off any data bindings of an element before calling teardown on it to remove special event handlers.
- When we switched to virtual mouse events, I just did a straight translation of the code that existed which basically did the collapse/expand on mouseup. In order to factor in scrolling, I needed to move that code into a vclick handler and stopPropagation() and preventDefault() to make sure the button doesn't activate.
- algorithmic optimization of listview.filter
- functional optimization by supporting data-filtertext attribute
includes patch from mathieucarbou: f58631d07d
- Modified vmouse code so that it uses $.data() instead of $().data() which is significantly faster.
- Modified the navigation and buttonMarkup code so they stop using live(). The vmouse code triggers several events during the touch events, which in turn causes the underlying event code to call $.closest() with the selector used during the live() call to figure out if the event should be handled. This turns out to be very expensive, so instead, we now just bind directly to the document, and walk the DOM manually to figure out if we should handle it. This is much faster since we are avoid triggering multiple nested function calls.
Needed to modify _itemApply() to look for the first image that is the first child of its parent. I may need to tweak this at a later point because the selector is still too general.
* 'master' of github.com:eddiemonge/jquery-mobile:
Fix for issue 1446 - Can't drag slider in 1.0a4.1 (Android 2.1)
Modified _createSubPages() to reduce the number of property lookups and function calls per iteration.
Fix for Issue 1424 - Adding items to listviews on a4.1 is too slow
made sure a couple of variables are locally scoped. Fixes#1403
moved previous strip query tests to tests for cleanHash
removed stripQuery helper to reduce confusion and complexity as striping the query param from a url is much more complex than a hash as it was originally intended for
tests for nested pages/query params
added handling for identical query param href/action on the same page
query param href/actions require absolute path prefixes when no relative path information is contained in the hash
tests for handling query params in makeAbsolute path helper, moved path helper tests to helper test file
handle relative query param links and forms Fixes#1160
removed duplicate current page check in favor of fixing the off by one bug
- Don't bind and unbind our touch listeners dynamically. This gets Android 2.1 into a strange state where it stops dispatching touch events. Instead, we now register our touchmove, touchend and scroll listeners at the same time we register our permanent touchstart listener, we then block and unblock processing in our touch listeners via a flag.
- Some optimizations to speed things up:
- Modified _itemApply() to make use of item.children() and filters. Also got rid of some unused code.
- Convert .each() in refresh() to a loop.
- Cache some $list.jqmData() values so we don't do it for each list item.
* 'master' of https://github.com/jquery/jquery-mobile:
[astounding] fixed css that locked ie in the navigation unit tests. tagged so I can show my kids some day
Fix for issues:
set version to 1.0a4.1
wrapped the else if/else in an else to prevent an unnecessary dom walk until we have to make it.
To ensure focus and scrollTo don't conflict (when possible), I set the focus order on page show to 1) previously clicked item if revisiting that page 2) page title 3) first focusable item in the page. Fixes#1342
1333 - Delay when scrolling over list when data-theme="d"
1368 - Listview refresh performance on a4
1407 - Bad scroll performance since A4 on iPhone 3G
Removed the checking for window.pageX/pageY in the vmouse touch callbacks. Accessing pageX/pageY causes the browser to flush its rendering queue.
- set active state on all button vclick events
- cancelled vclick on slider switch handles so it's not too sticky.
- removed addClass in navigation.js as the first change handles it there.
- Modified createVirtualEvent to use changedTouches if touches doesn't exist.
- Also filed issue 1373 about the fact that we really need to be tracking touch identifiers in the vmouse code.
- Third party click handlers never called.
- Touch and click target mismatches due markup changes before the click events are generated. (What looks like a double click event)
For vclicks dispatched via touchend, calling preventDefault causes mouse clicks to be suppressed. This is why the 3rd party onclick handlers weren't getting triggered. For vclicks dispatched by a real mouse click this isn't a problem.
The fix basically removes the preventDefault() call from the live("vclick") handler and places it in a real live("click") handler. This allows the mouse event to get dispatched and trigger 3rd party click handlers, and still call preventDefault to prevent the link from being followed.
- This was a regression introduced by 20dce2ce. Added check for undefined newActiveIndex so we can tell the difference between the URL not being found, and a zero index.
- Modified the button markup behavior so that it uses the virtual mouse events and adds the ui-btn-active class on vmousedown, and then removes it on vmousemove or vmouseup.
- Looks like the "Intelligent Guess" default behavior of the $.ajax() method in jQuery 1.5.1 guesses wrong when attempting to load an HTML file via a file:// URL. It's guessing that it is an XML document, so it ends up passing in the DOM document node to our success callback, instead of the expected HTML as text (responseText), so our callback code does not behave correctly. We can get around this by simply specifying dataType:"html" at the time we make a request.
https://github.com/jquery/jquery-mobile/issues/issue/1036
The css styles the select menu with a width of 80% with a max-width of
350px. This fix checks if width of select menu is less than max-width.
If that is the case the select menu is centered on screen. If not it
checks if the rigth or left side of the select menu are outside the
viewport and if so moves the select menu inside the viewport with a 30px
tolerance.
- Added support for dispatching virtual events from touch based events.
- Now we copy over the x/y values from original events on to the virtual ones.
- We still need to figure out how to cancel the mouse events that fire after the touchend, and do some clean up in the cases where a scroll happens which prevents some mouse/touch events from being generated, like on Blackberry OS 6.
- Wait for the "silentscroll" event before setting focus. This avoids the "feature" where the browser will automatically offset rendering of a container to make sure whatever has focus is visible.
- jquery.mobile.core.js no longer creates pages from every page and dialog in the DOM automatically at domready. Instead, pages are created as they are referenced via changePage, which can speed up pageload in multi-page documents, and means local "dialogs" referenced via data-rel="dialog" no longer need a data-role="dialog" attribute when served.
- in changePage, "from" is now allowed to be undefined. This simplifies the logic involved in showing the first page, which never had a "from" page, and previously needed a custom pageChange workaround to accommodate that.
- The pageshow event is no longer used as a callback for returning false and preventing the $.mobile.activePage from being set to the newly shown page. In other words, a page always becomes $.mobile.activePage once its shown now (the only reason this was optional before was because of a dialog restriction that's no longer true)
- the hashchange event logic for showing a particular page is now greatly simplified. It either shows the page referenced in location.hash, or if there's no hash it changes to the first page in the dom. This means every pageshow (including the first one) now uses pageChange internally.
- the hashchange event listener is no longer disabled when ajaxEnabled == false. Doing this before prevented local non-ajax page navigation from working properly. To disable hashchange listening, use $.mobile.urlHistory.listeningEnabled. We might consider defining (or moving) this on the $.mobile hash later as well for easier access.
- The internal var $.mobile.startPage is now $.mobile.firstPage, because it's not necessarily the page you started on, but merely a reference to the first "page" in the dom.
- Back buttons are auto-added to every page after the first one you first visit (this includes generated pages, such as those in a multipage document or nested listviews). Keep in mind that a "back" button does not take the place of a standard "home" link, and when building an app with jQuery Mobile, it's good to make use of both (particularly on deep-linked pages). Fixes#908
- Added code to enhanceControls() that sets the autocorrect and autocomplete attributes on all inputs of type="text" to "off". This basically disables the use of autocorrection on iOS.
- Modified the code in enhanceControls() to cache the form controls query to reduce the number of times we search for controls in the current page.
If data-url is set on a page div when it returns from the server, it's value will be used to replace the url in the hash, and as the base url for future requests if it adds additional segments (such as a trailing slash). This will enable developers to work around the limitation of directory links requiring a trailing slash, and will also allow developers to specify a new url after a redirect occurs (such as after a login). Fixes#867
- Modified silentScroll() to trigger a "silentscroll" event. This was necessary because programatically scrolling the window does not generate "scroll" events.
- Got rid of the hideAfterDelay() function that was not used.
- Added startShowTimer() and clearShowTimer() functions.
- Added event handlers for "resize" and "silentscroll" events. This causes headers/footers to be positioned properly as "scroll" and "orientationchange" events cause the visual viewport to resize.
Issues this fix causes:
- On some Android platforms, clicking in textfields/textareas trigger a "resize" event. This causes the footer to show up in the minimized visual viewport, right above the keyboard.
In the process, some other small changes should be noted:
urlStack is now urlHistory, a hash of methods and properties used for history stack management (stack, activeIndex, getActive, getPrev, getNext, addNew, clearForward, and listening Enabled). All these are documented inline and exposed on $.mobile.urlHistory (I'm not sure these will be publicly documented, but just exposed internally for plugins for now).
$.changePage has two argument changes: the "back" argument is now called "reverse"; this results in no change from an end-user standpoint, but reflects the fact that it only reverses the direction of a transition without affecting the internal history stack, and second, a new argument at the end defines whether changePage was called from a hashChange which makes that url open to history menu guessing.
This makes our include model match the include model on the CDN, and allows devs to make use of mobileinit for debugging some of the samples since that must be set up after jquery.js, but before jquery-mobile.
- Fixed baseTagTest() in jquery.mobile.support.js, so that it uses any pre-existing base tag for testing. This fixes the bug on Webkit (Safari) where the relative paths for links were being resolved/expressed with the document path instead of the original base path.
- Modified the base code in jquery.mobile.navigation.js so that it uses the initial path of a pre-existing base tag, instead of always using the document path. This means that a document with a URL such as:
http://foo.com/a/b/c#docs/pages/index.html
That uses a base tag like:
<base href="http://foo.com/bar/">
Will resolve properly:
http://foo.com/bar/docs/pages/index.html
so the mobile page gets loaded properly.
- Reduced the path.get() function down to a couple of regexp replace() calls.
- We were firing off our fake orientationchange event before the viewport meta tag is injected. This causes us to get the default document width for the device which is much wider than the actual device-width. We now fire off the event after the dom ready event fires.
470 - Multiple Footers when using data-position=fixed and data-id=[someid]
773 - The fixHeaderFooter pagebeforeshow live function is not triggered for the initial page shown
- Removed the findStickyFooter() function.
- Reworked the logic in the pagebeforeshow live function. We now add a ui-sticky-footer class to the sticky footer element. This will guarantee that we find the sticky footer if it already exists. We may at some point want to consider the use of ids on the sticky footers so that we don't have to crawl the entire document.
- Moved the live pagebeforeshow and pageshow calls outside of the DOMReady function so that they get registered as soon as the plugin is loaded. This guarantees that they will be triggered when the core plugin's DOMReady function fires.
- This fix makes issue/pull-request 765 obsolete.
This is just a quick check in to the main index.html of the test site to make sure things work. We still need to do a sweep through *ALL* html files and make sure we are including a trailing slash in the themes/default path.
Added triggers for mousedown and mouse up in the delayed case because some of hte jqm components register handlers on those events to set the component states.
Note that the focus() trigger is commented out temporarily. It seems to cause the content within the scrollview clip to scroll to the point where item being focused sits in the flow .. unfortunately this screws up the rendering because we are using CSS3 translate, so the item clicked on is out of view.
Modified sv-test-02.html so that the clone event sets the target property on the fake event.
Modified sv-test-02.html so that you can dynamically switch the scrolling method used. This will allow us to test the performance of different methods on the different platforms.
Modified scrollview.js so that you can specify @data-scroll-method="translate|position|scroll".
Added a couple of tests that will help us figure out what events need to be handled special to disable native view port scrolling, and what events are necessary for form elements to function properly.
https://github.com/jquery/jquery-mobile/pull/649
- Changed hideOnTouchEnabed to touchToggleEnabled.
- Fixed problem that would allow the toolbars to show on touchstop, if the starting state was "inline" to begin with.
- Moved the touchToggleEnabled checks in touchstart/touchstop so that they wrap the entire code in the function. We don't want to do any work if we don't need to.
- Removed the forced hide() call in touchstart.
Added the missing fadeout animation reference inthe fade.in transition rule.
The shift away from interal ID attribute usage also allows users to bind page events (pagecreate, pagebeforecreate) to a page div by its ID, which was a frequent cause of confusion when it didn't work as expected in former versions of the framework.
Seemingly unrelated: these commits allow you to specify data-role="dialog" in multipage and single page templates. In multipage templates, the role must be on the page (a link with data-rel alone will not work in multi-page). This addresses issue number 464, but may need further testing for obscure scenarios.
Fixes#477 (Pages are not enhanced when linking to a filename without a path)
Fixes#493 (Click the same link twice -> blank page)
Fixes#513 (closing dialog + returning to the same dialog)
Fixes#550 (changePage() not updating hash for internal pages - breaks )
Fixes#464 (Dialogs don't work within multi-pages)
Fixes#633 (Recent change to prevent same-page requests breaks select menu close button)
Fixes#599 (Page ids & page specific events)
Fixes#634 (After a bad page request, base url is not reset to current path)
booya.
A workaround is still included to ensure the input's name/value is submitted along with the form when it's not a type=reset, as this is necessary for the button data to appear in the serialized form data.
Fixed a typo/bug in scrollview.js that was causing the paging bool to be set improperly.
Turned on scrollview paging in scrollview-direction.html.
Items still left to do:
- Code refactoring/cleanup.
- Modify the code so that scroll offsets are stored as positive values. This will make it easier for folks to understand.
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.
This version supports simulated scrolling via the CSS3 transform property by default, but also supports an option for positioning the old-fashioned way with top and left properties.
Still some code clean-up to do, but folks can start playing with it.
Some items/issues left to look into:
- Experiment with event delegation so we can implement nested scrollviews.
- Implement scroll direction locking.
- Decide whether to conditionally inject clip/view markup.
- Decide on final ui class names.
- Decide on how scrolling behavior is actually invoked. (data-* attribute or class)
- Decide on final set of notifications we'll need to fire off.
- Add an API so that scroll position can be adjusted after a resize/orientation change.
- Documentation that describes potential problems with performance, memory usage, etc, and workarounds.
If you don't currently have a webserver running locally, a 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.
An 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.
A full version and a minified version of the jQuery Mobile JavaScript and CSS files will be created
in a folder named "compiled". There is also now a Structure only css file so you can add your own theme on top of it.
Whenever this configuration becomes inconvenient, we can remove it, obviously it's not meant to stay!
How to build a self-contained version of the Docs/Demos
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>");
<p>jQuery Mobile is built upon standard, semantic HTML, allowing pages to be accessible to the broadest range of devices possible. For A-Grade browsers, many of the components in jQuery Mobile leverage techniques such as focus management, keyboard navigation, and HTML attributes specified in the W3C's <ahref="http://www.w3.org/TR/wai-aria/">WAI-ARIA</a> specification.</p>
@ -24,7 +31,33 @@
<p>While our accessibility implementation is currently a work in progress, we aim to provide a fully accessible suite of components for version 1.0.</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 platforms</strong> - iOS, Android, Blackberry, Palm WebOS, Nokia/Symbian, Windows Mobile, bada, MeeGo with baseline support for all devices that understand HTML</li>
<li><strong>Lightweight size</strong> (12k 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 deskstop 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>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>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>New events</strong> streamline the process of supporting touch, mouse, and cursor focus-based user input methods with a simple API. </li>
<li><strong>New plugins</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>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>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>jQuery’s mobile strategy can be summarized simply: Delivering top-of-the-line JavaScript in a unified User Interface that works across the most-used smartphone web browsers and tablet form factors.</p>
<h2>jQuery Mobile Overview</h2>
<p>jQuery’s mobile strategy can be summarized simply: A unified user interface system that works seamlessly across all popular mobile device platforms, built on the rock-solid jQuery and jQuery UI foundation. Focused on a lightweight codebase built on progressive enhancement with a flexible, easily themeable design.</p>
<p>The critical difference with our approach is the <ahref="platforms.html">wide variety of mobile platforms we’re targeting</a> with jQuery Mobile. We’ve been working hard at bringing jQuery support to all mobile browsers that are sufficiently-capable and have at least a nominal amount of market share. In this way, we’re treating mobile web browsers exactly how we treat desktop web browsers.</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>For the alpha release, the following devices have been tested and should have a fairly solid jQuery Mobile experience. That being said, there are still a fair amount of bugs and performance improvements to be tackled before the 1.0 release in January. </p>
<divclass="content-primary">
<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>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</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>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>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>
<p>Older versions of Blackberry, Nokia/Symbian, and Windows Mobile may work but we're still seeing JavaScript errors and rendering bugs that need to be tracked down. We don't yet have phones to test Windows Mobile 7, bada, or MeeGo but these will be added as soon as we can get devices.</p>
<p>Since jQuery Mobile is built on the jQuery core, all pages should also work great on most recent versions of desktop browsers too - Firefox, Chrome, Safari, Internet Explorer, Opera, etc.</p>
<p><ahref="http://jquerymobile.com/gbs/"rel="external"><strong>View supported browser matrix</strong> on jQuery Mobile</a></p>
<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 <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>Triggers when a horizontal drag of 30px or more (and less than 20px vertically) occurs within 1 second duration.</dd>
<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>
<li><code>scrollSupressionThreshold</code> (default: 10px) – More than this horizontal displacement, and we will suppress scrolling</li>
<li><code>durationThreshold</code> (default: 1000ms) – More time than this, and it isn’t a swipe</li>
<li><code>horizontalDistanceThreshold</code> (default: 30px) – Swipe horizontal displacement must be more than this.</li>
<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>
<dd>Triggers when a scroll begins. Note that iOS devices freeze DOM manipulation during scroll, queuing them to apply when the scroll finishes. We're currently investigating ways to allow DOM manipulations to apply before a scroll starts.</dd>
<dl>
</dl>
<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>
<pre>
<code>
$('div').live('pageshow',function(event, ui){
alert('This page was just hidden: '+ ui.prevPage);
<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('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>
</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>Triggered on the page being initialized, before initialization occurs.</dd>
<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>
</dd>
<dt><code>pagecreate</code></dt>
<dd>Triggered on the page being initialized, after initialization occurs.</dd>
</dl>
<p>Note that by binding to <code>pagebeforecreate</code> and returning <code>false</code>, you can prevent the page plugin from making its manipulations.</p>
<divclass="ui-body ui-body-e">
<p><strong>Note on Page IDs: </strong> Page elements in jQuery Mobile utilize the <code>ID</code> attribute for storing the location from which they came. When you place an <code>ID</code> attribute on a page that is brought into jQuery Mobile's single-page environment through Ajax, jQuery Mobile wraps that page with a new "page" <code>div</code> element, preserving any CSS references to your <code>ID</code>. However, this means that your <code>ID</code> attribute is no longer on the "page" element, so you must keep this in mind when binding to page events (<code>pagebeforecreate</code>, <code>pagecreate</code>, etc). To avoid issues, try using a class if possible. </p>
</div>
<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>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>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 <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>Anchor links with a data-rel attribute value, or pages with a data-role value, that match these selectors will not be trackable in history (they won't update the location.hash and won't be bookmarkable).</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 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 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>
<h3>Orientation Classes </h3>
<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 {
@ -35,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>
<p>jQuery Mobile provides a function that allows you to test whether a particular CSS Media Query applies. Simple call <code>$.mobile.media()</code> and pass a media type or query. If the browser supports that type or query, and it currently applies, the function will return true. If not, it'll return false.</p>
<pre>
<code>
//test for screen media type
$.mobile.media("screen");
//test a min-width media query
$.mobile.media("screen and (min-width: 480px)");
//test for iOS retina display
$.mobile.media("screen and (-webkit-min-device-pixel-ratio: 2)");
<dd>Programmatically change from one page to another. This method is used internally for transitions that occur as a result of clicking a link or submitting a form, when those features are enabled.</dd>
<dd>Programmatically change from one page to another. This method is used internally for the page loading and transitioning that occurs as a result of clicking a link or submitting a form, when those features are enabled.</dd>
<dd>
<dl>
<dt>Arguments</dt>
<dd><code>to</code>
<ul>
<li>String, url to transition to (<code>"about/us.html"</code>)</li>
<li>jQuery object (<code>$("#about")</code>)</li>
<li>Array specifying two page references [from,to] for transitioning from a known page. From is otherwise assumed to be the current page in view (or $.mobile.activePage ).</li>
<li>Object for sending form data. (<code>{to: url, data: serialized form data, type: "get" or "post"}</code></li>
</ul>
</dd>
<dt><code>·</code> Arguments</dt>
<dd><code>to</code> (<em>string or object</em>, required)
<ul>
<li>String: Absolute or relative URL. ("about/us.html")</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>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><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>
</ul>
</li>
</ul>
</li>
</ul>
</dd>
</dl>
</dd>
@ -48,51 +80,434 @@
<pre>
<code>
<strong>//transition to the "about us" page with a slideup transition</strong>
<dd>Load an external page, enhance its content, and insert it into the DOM. This method is called internally by the changePage() function when its first argument is a URL. This function does not affect the current active page so it can be used to load pages in the background. The function returns a deferred promise object that gets resolved after the page has been enhanced and inserted into the document.</dd>
<dd>
<dl>
<dt>Arguments:</dt>
<dd><code>Done</code> (<em>boolean</em>, defaults to false, meaning loading has started). True will hide the loading message.</dd>
<dt><code>·</code> Arguments</dt>
<dd><code>url</code> (<em>string or object</em>, required) A relative or absolute URL.</dd>
<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>
</ul>
</li>
</ul>
</dd>
</dl>
</dd>
<dd>Examples:
<pre>
<code>
<strong>//cue the page loader</strong>
$.mobile.pageLoading();
<strong>//load the "about us" page into the DOM</strong>
$.mobile.loadPage( "about/us.html" );
<strong>//hide the page loader</strong>
$.mobile.pageLoading( true );
<strong>//load a "search results" page, using data from a form with an ID of "search"" </strong>
<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>
<dd>
<dl>
<dt><code>·</code> Arguments</dt>
<dd><code>url</code> (<em>string</em>, required) A relative or absolute URL.</dd>
<dt><code>·</code> Return Value</dt>
<dd>
<p>This function returns an object that contains the various components of the URL as strings. The properties on the object mimic the browser's location object:</p>
<dl>
<dt><code>hash</code></dt>
<dd>The fragment conponent of the URL, including the leading '#' character.</dd>
<dt><code>host</code></dt>
<dd>The host and port number of the URL.</dd>
<dt><code>hostname</code></dt>
<dd>The name of the host within the URL.</dd>
<dt><code>href</code></dt>
<dd>The original URL that was parsed.</dd>
<dt><code>pathname</code></dt>
<dd>The path of the file or directory referenced by the URL.</dd>
<dt><code>port</code></dt>
<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>
<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>
<dl>
<dt><code>authority</code></dt>
<dd>The username, password, and host components of the URL</dd>
<dt><code>directory</code></dt>
<dd>The directory component of the pathname, minus any filename.</dd>
<dt><code>domain</code></dt>
<dd>The protocol and authority components of the URL.</dd>
<dt><code>filename</code></dt>
<dd>The filename within the pathname component, minus the directory.</dd>
<dt><code>hrefNoHash</code></dt>
<dd>The original URL minus the fragment (hash) components.</dd>
<dt><code>hrefNoSearch</code></dt>
<dd>The original URL minus the query (search) and fragment (hash) components.</dd>
<dt><code>password</code></dt>
<dd>The password contained within the authority component.</dd>
<dt><code>username</code></dt>
<dd>The username contained within the authority component.</dd>
</dl>
</dd>
</dl>
</dd>
<dd>Examples:
<pre>
<code>
<strong>// Parsing the Url below results an object that is returned with the
<dd>Add width breakpoints to the min/max width classes that are added to the HTML element.</dd>
<dd>
<dl>
<dt>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>
<p>Every layout and widget in jQuery Mobile is designed around a new object-oriented CSS framework that makes it possible to apply a complete unified visual design Theme to sites and applications. The theming system is similar to the ThemeRoller system in jQuery UI, but adds a few important improvements:</p>
@ -29,6 +34,9 @@
<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>
@ -45,14 +53,14 @@
<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>
<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>
@ -60,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>
<p>Learn more about <ahref="../content/content-themes.html">content theming</a>.</p>
@ -148,52 +157,52 @@
<p>This default behavior makes it easy to ripple a theme change through a page by setting a theme swatch on a parent because you know the buttons will maintain the same relative visual weight across themes. Since form elements use the button styles, they will also adapt to their parent container too. </p>
<p>If you want to add visual emphasis to a button and help it stand out visually from its parent toolbar, an alternate swatch color can be set by adding a <code>data-theme="a"</code> to the anchor. Once an alternate swatch color is set on a button in the markup, the framework won't override that color if the parent theme is changed, because you made a conscious decision to set it.</p>
<p>If you want to add visual emphasis to a button and help it stand out visually from its parent toolbar, an alternate swatch color can be set by adding a <code>data-theme="a"</code> to the anchor. Once an alternate swatch color is set on a button in the markup, the framework won't override that color if the parent theme is changed, because you made a conscious decision to set it.</p>
<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>Occasionally, you may want to visually group a set of buttons together to form a single block that looks contained like a navigation component. To get this effect, wrap a set of buttons in a container with the <code>data-role="controlgroup"</code> attribute — the framework will create a vertical button group, remove all margins and drop shadows between the buttons, and only round the first and last buttons of the set to create the effect that they are grouped together. </p>
<divclass="content-primary">
<p>Occasionally, you may want to visually group a set of buttons together to form a single block that looks contained like a navigation component. To get this effect, wrap a set of buttons in a container with the <code> data-role="controlgroup"</code> attribute — the framework will create a vertical button group, remove all margins and drop shadows between the buttons, and only round the first and last buttons of the set to create the effect that they are grouped together. </p>
<p>The jQuery Mobile framework includes a selected set of icons most often needed for mobile apps. To minimize download size, jQuery Mobile includes a single white icon sprite, and automatically adds a semi-transparent black circle behind the icon to ensure that it has good contrast on any background color.</p>
<p>An icon can be added to a button by adding a <code>data-icon</code> attribute on the anchor specifying the icon to display. For example, the following markup:</p>
<p>An icon can be added to a button by adding a <code>data-icon</code> attribute on the anchor specifying the icon to display. For example, the following markup:</p>
<p>This default may be overridden using the <code>data-iconpos</code> attribute to set the icon to the right, above (top) or below (bottom) the text. For example, the markup:</p>
<p>This default may be overridden using the <code>data-iconpos</code> attribute to set the icon to the right, above (top) or below (bottom) the text. For example, the markup:</p>
<p>You can also create an icon-only button, by setting the <code>data-iconpos</code> attribute to <code>notext</code>. The button plugin will hide the text on-screen, but add it as a <code>title</code> attribute on the link to provide context for screen readers and devices that support tooltips. For example, replacing <code>data-iconpos="right"</code> on the previous example with <code>data-iconpos="notext"</code>:</p>
<p>You can also create an icon-only button, by setting the <code>data-iconpos</code> attribute to <code>notext</code>. The button plugin will hide the text on-screen, but add it as a <code>title</code> attribute on the link to provide context for screen readers and devices that support tooltips. For example, replacing <code>data-iconpos="right"</code> on the previous example with <code>data-iconpos="notext"</code>:</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>By default, all buttons in the body content are styled as block-level element so they fill the width of the screen:</p>
<ahref="index.html"data-role="button">Button</a>
<p>However, if you want a more compact button that is only as wide as the text and icons inside, add the <code>data-inline="true"</code> attribute to the button:</p>
<p>However, if you want a more compact button that is only as wide as the text and icons inside, add the <code>data-inline="true"</code> attribute to the button:</p>
<p>If you have multiple buttons that should sit side-by-side on the same line, wrap the buttons in a container that has a <code>data-inline="true"</code> attribute. This will style the buttons to be the width of their content and float the buttons so they sit on the same line. </p>
<p>If you have multiple buttons that should sit side-by-side on the same line, add the <code>data-inline="true"</code> attribute to each button. This will style the buttons to be the width of their content and float the buttons so they sit on the same line. </p>
<p>If you want buttons to sit side-by-side but stretch to fill the width of the screen, you can use the <ahref="../content/content-grids.html">content column grids</a> to put normal full-width buttons into 2- or 3-columns.</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="../themes/index.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>