The jQuery Mobile team is happy to announce the release of Beta 1. We’re proud of the refinements we’ve made to make jQuery Mobile faster, extensible and more compatible over the last 12 weeks and look forward to having more frequent releases as we work up to 1.0 in late summer. We’re planning on releasing a second Beta in about a month that will begin decoupling our code so you can include only the components you need, add greater extensibility to support dynamic JS-driven sites, and bring even broader device support.
Note that jQuery Mobile 1.0 will require jQuery core 1.6 as a baseline. Going forward, we’ll be supporting the two latest major versions of core but we’re starting with a cleaner baseline for launch. Here is a summary of what’s new and improved in Beta 1.
jQuery Mobile is a broadly compatible HTML5 library for building web sites and apps and we’re very proud of our commitment to universal accessibility through our broad support for all popular platforms. Since we added WP7 support in Alpha 4, we’ve added support for both Blackberry 5 devices and Opera Mini in Beta 1 which dramatically increases the reach of the framework. Opera Mini had 57.9 billion page views in April 2011 alone so it’s incredibly popular, especially internationally. Both of these platforms had issues with handling the Ajax-based navigation so they receive a B grade experience with all the enhancements except for Ajax navigation.
At this stage, jQuery Mobile works on the vast majority of all modern desktop, smartphone, tablet, and e-reader platforms. In addition, feature phones and older browsers are also supported because of our progressive enhancement approach. The only notable platform still in the works is Nokia’s Symbian S60 platform and we have this targeted for Beta 2.
Our graded support matrix was created over a year ago based on our goals as a project and since that time, we’ve been refining our grading system based on real-world device testing and the quickly evolving mobile landscape. To provide a quick summary of our browser support in Beta 1, we’ve created a simple A (full), B (full minus Ajax), C (basic) grade system with notes of the actual devices and versions we’ve been testing on in our lab.
The visual fidelity of the experience is highly dependent on CSS rendering capabilities of the device and platform so not all A grade experience will be pixel-perfect but that’s the nature of the web. We’ll be adding additional vendor-prefixed CSS rules to bring transitions, gradients and other visual improvements to non-WebKit browsers in future releases so look for even more added visual polish as we move towards 1.0.
A-grade – Full enhanced experience with Ajax-based animated page transitions.
- Apple iOS 3.2-5.0 beta: Tested on the original iPad (3.2 / 4.3), iPad 2 (4.3), original iPhone (3.1), iPhone 3 (3.2), 3GS (4.3), and 4 (4.3 / 5.0 beta)
- Android 2.1-2.3: Tested on the HTC Incredible (2.2), original Droid (2.2), Nook Color (2.2), HTC Aria (2.1), emulator (2.3). Functional on 1.5 & 1.6 but performance may be sluggish, tested on Google G1 (1.5)
- Windows Phone 7: Tested on the HTC 7 Surround
- Blackberry 6.0: Tested on the Torch 9800 and Style 9670
- Blackberry Playbook: Tested on PlayBook version 1.0.1 / 1.0.5
- Palm WebOS (1.4-2.0): Tested on the Palm Pixi (1.4), Pre (1.4), Pre 2 (2.0)
- Firebox Mobile (Beta): Tested on Android 2.2
- Opera Mobile 11.0: Tested on the iPhone 3GS and 4 (5.0/6.0), Android 2.2 (5.0/6.0), Windows Mobile 6.5 (5.0)
- Kindle 3: Tested on the built-in WebKit browser included in the Kindle 3 device
- Chrome Desktop 11-13 – Tested on OS X 10.6.7 and Windows 7
- Firefox Desktop 3.6-4.0 – Tested on OS X 10.6.7 and Windows 7
- Internet Explorer 7-9 – Tested on Windows XP, Vista and 7 (minor CSS issues)
- Opera Desktop 10-11 – Tested on OS X 10.6.7 and Windows 7
B-grade – Enhanced experience except without Ajax navigation features.
- Blackberry 5.0: Tested on the Storm 2 9550, Bold 9770
- Opera Mini (5.0-6.0) – Tested on iOS 3.2/4.3
- Windows Phone 6.5 – Tested on the HTC
C-grade – Basic, non-enhanced HTML experience that is still functional
- Blackberry4.x: Tested on the Curve 8330
- All older smartphone platforms and featurephones – Any device that doesn’t support media queries will receive the basic, C grade experience
Not Officially Supported – May work, but haven’t been thoroughly tested or debugged
- Nokia S60 – Targeted for Beta 2 release. A/B grade support will depend on results of device testing.
- Meego – Originally a target platform, but Nokia decision to relegate this platform to “experimental”, we are considering dropping support.
- Samsung Bada – The project doesn’t currently have test devices or emulators, but current support is known to be fairly good. Support level undecided for 1.0.
- Palm WebOS 3.0 – We’re hoping to get test devices from Palm soon to start testing but have heard that rendering is quite good in 3.0
KEY CHANGES
URL bar: Now hidden in iOS and Android
One of the most common requests is to make the page transitions smoother and less jumpy and we are working hard to improve this as we move towards 1.0. There are two major items affecting the perceived smoothness: hiding the URL bar consistently and scrolling to the correct page position between transitions.
We’re happy to report that in Beta, we are able to hide the URL bar in both iOS and Android which avoids the multiple re-draws seen when the URL bar pushed down the page content, then hid later in the transition. We do this by scrolling the page by 0 pixels in iOS and 1 pixel in Android to trick the browser into hiding the bar and target this with a bit of clever feature detection. Nothing is perfect so you still may see the URL appear randomly but this should overlay the URL bar over the content briefly before disappearing but shouldn’t cause a re-draw.
Note that to accomplish the URL hiding, we’re using our custom fastclick event. There’s a small possibility that this event may interfere with jQuery plugins that bind to click events on touch devices. In these situations, you may need to tweak your code to either bind to vclick events instead of click, or set the useFastClick global config option to tell the automated Ajax handling use an ordinary click events instead. Disabling this feature will introduce a slight delay in clicking links and the URL bar will not be hidden.
Transitions: Smoother, faster scroll
If you don’t scroll the page at all and click on a link, you should see a smooth page transition with no jumps or blinks in Beta 1. However, there will be two potential situations that cause a scroll and visible blink: scrolling back to the top of the current page before a transition, and scrolling back down to your previous scroll position if you return to a page. We’ve been doing a lot of work to try and reduce or eliminate the scroll position blink, especially the need to first scroll to the top of the page before starting a transition, but it’s a tricky issue to solve across all the devices we support. We’ve minimized the speed and amount of scroll jumps for Beta 1, but still have a ways to go and will be working on refinements for future releases.
Restoring your scroll position is an important usability feature and is the expected behavior on both the web and in apps but it does introduce a small blink as the browser scrolls the viewport to the correct position and re-renders the new view. One tweak we introduced in Beta 1 is a threshold value for how far down the user needs to scroll a page before we restore their scroll position. For example, if the user only scrolled a page 50 pixels before clicking a link, it’s not worth seeing a scroll re-draw to restore that position but if they scrolled 500 pixels, it’s a huge time-saver.
By default, this scroll threshold is calculated as half of the device’s screen height, but can be adjusted in the minScrollBack config option. To eliminate the threshold, set this option to “0”. To completely disable the scroll position restore feature, set this option to infinity but remember that this may make your app much less usable, despite the smoother transitions.
Navigation core: Decoupled for extensibility
We landed a big refactor the core Ajax navigation code to allow for better extensibility for developers that are manipulating pages dynamically and plan on adding a lot more hooks for Beta 2 to make this even more powerful. Until recently, the navigation code was largely implemented as a set of nested functions within the$.mobile.changePage() function which made the code very hard to follow and extend so for Beta 1, we decoupled the navigation core into separate internal functions. Partitioning the code this way makes it easier for us to identify key points for adding extensibility hooks and makes the code easier to follow:
loadPage()
- Responsible for loading a page into the DOM of a specific page container and enhancing it
changePage()
- Responsible for updating the internal bookkeeping for tracking what is the current page. This includes: managing the URL stack, managing the location hash, and kicking off transitions
transitionPages()
- Responsible for managing the transition between the current active page and the new page to be shown
Of these, loadPage() and changePage() methods are public. The changePage() method now takes 2 arguments: the first is required, the second is optional. The first argument accepts a URL or a jQuery collection containing a page element as its first argument. The 2nd argument is an options object that allows the caller to modify changePage behavior. The options that can be specified are as follows:
transition (String, defaults to transition specified by $.mobile.defaultPageTransition)reverse (Boolean, defaults to false)changeHash (Boolean, defaults to true)role (String, defaults to “page”)pageContainer (jQuery collection, defaults to $.mobile.pageContainer)type (String, defaults to “get”)data (Object or String, default is undefined)reloadPage (Boolean, default is false)showLoadMsg (Boolean, default is true)
URL handling: Coverage for all path types
There are a number of factors involved in loading files in jQuery Mobile. The framework essentially listens for normal link clicks and form submissions and requests them through Ajax which allows us to support page transitions as the user navigates a site. Path handling within jQuery mobile is one of the most complex parts of the framework because it needs to handle the wide array of paths that a browser may encounter and seamlessly resolve the page and all it’s dependencies (images, stylesheets, scripts, etc) and also needs to work well with file:// URLs for installed applications. In Beta 1, we now cover every possible URL path type and have added robust unit test coverage to ensure we avoid regressions moving forward. When upgrading to Beta 1, no changes are needed to take advantage of these URL handling improvements.
Dynamic base tag: More robust
The Ajax navigation system loads multiple “pages” into the DOM of the starting page. Each of these pages loaded in could live in completely different directories on the server so the paths of links, forms, images, scripts and styles of each page need to be dynamically set so everything “just works”. To do this, when the initial jQuery Mobile document is loaded, the navigation code checks for an existing base tag, and if one does not exist, the framework injects one and sets its @href to path for the current document. As of Beta 1, the base tag mangement is completely re-vamped to work correctly, even in edge-case scenarios. When upgrading to Beta 1, no changes are needed to take advantage of these base tag improvements.
Page transitions: Decoupled and extensible
We’ve pulled page transitions out into a separate plugin so they can be decoupled from the navigation plugin. As part of this re-work, we’ve introduced the ability for developers to create custom transitions created with pure CSS3, or in combination with JavaScript by adding extensibility hooks to the transition system.
Pinch-to-zoom: Now restored in demos
Before Beta 1, all our demos and docs had a viewport meta tag that set “minimum-scale=1, maximum-scale=1” which completely disabled the pinch- or double-tap-to-zoom feature in mobile browsers. We had done this originally because on iOS, there is a bug that will incorrectly scale the page when you change orientation. Here is the meta tag we used up through Alpha 4.1:
<meta name="viewport" content="width=device-width, minimum-scale=1, maximum-scale=1">
Disabling the native zoom features of the browser isn’t very user-friendly so we changed our meta tag in the demos and docs for Beta 1 to restore the ability to zoom the page. At this stage, we don’t think it’s worth disabling the user’s zoom feature to workaround an iOS bug that may be fixed in the near future. Since our demos are used as a template for many people so we want to set an example of the best practice for mobile web development. The new meta tag we use looks like this:
<meta name="viewport" content="width=device-width, initial-scale=1">
You will notice that in the Beta 1 demos & docs, you be able to pinch zoom the pages. You may also notice that the pages will zoom in when interacting with form elements on some browsers and this is normal with this viewport configuration. Since this meta tag is part of your page content, you are free to set these attributes to match the specific needs of your project so this isn’t a change to the library, just our demos.
Dynamic injected viewport meta tag: Support dropped
On a related topic, we deprecated injecting the viewport meta tag back in alpha 4 due to Windows Phone 7’s lack of support for dynamically injected viewport elements. In Beta 1, we removed the dynamic viewport support from the codebase in preparation for beta so if you haven’t switched to writing this tag into your markup, please do that now in preparation for Beta. If you page is zoomed out to a wide width when you upgrade, you’ll need to add a meta viewport tag to each page to control the zoom level. See the boilerplate template page in the docs for an example.
Automatic toolbar back button: Now off by default
In a blog post, we outlined the reasons why we felt the feature that automatically adds a back button to the header toolbar, while good for specific situations, wasn’t really necessary for most web sites and web apps because browsers and phones already have back buttons. The response in the comments and Twitter was overwhelmingly positive to moving in this direction so for Beta 1, we landed this change.
All this really means is that the auto-generated Back button feature is off by default. It’s not going anywhere because we understand that in fullscreen browser environments or installed apps, there isn’t browser chrome or a physical back button on all platforms so you’ll want to flip this switch on in those cases.
To activate auto generated back buttons on specific pages, simply add the data-add-back-btn="true" attribute on the page container and the magic will be back. To activate this globally, set the addBackBtn option in the page plugin to true. Here is an example of how to set this:
$(document).bind("mobileinit", function() {
$.mobile.page.prototype.options.addBackBtn = true;
});
Note: You must include this script before the jQuery Mobile library is referenced in the head of your page for this to work. The mobileinit event is triggered immediately upon execution, so you need to bind event handlers before jQuery Mobile is loaded. Learn more about setting global config options.
Responsive design helper classes: Now deprecated
We include a set of responsive design helper classes designed to make it easy to build a responsive design that adapts the layout for various screen widths. At the time, we went with a system of dynamically appended min- and max-width classes on the body that are updated on load, resize and orientation change events as a workaround for the limitation that Internet Explorer doesn’t support media queries.
Although this technique works, it adds script overhead that we’d like to avoid as we move towards 1.0. Within jQuery Mobile, we only use these classes for a single feature: the responsive label/form layouts. This week, we re-wrote the styles for the form elements to work without the helper classes by switching to standard media queries in our CSS. Since we use media queries sparingly right now, the only change you’ll see is that at wider screen widths, WP7 won’t switch to the layout with the label floated to the left of the form element.
We understand that many developers may be using these CSS classes so we’re going to leave this code in until for Beta 1 to give everyone time to migrate to other solutions. We will be removing these classes completely by 1.0. If you want to use media queries on Internet Explorer, we recommend adding in respond.js, a polyfill script written by team member Scott Jehl that adds media query support for IE. Post-1.0, we’re going to look into whether we should polyfill media queries as part of jQuery Mobile or continue to leave it as an optional file.
Experimental datepicker: Moved out of the official docs & repo
A while back, we took the jQuery UI datepicker and tweaked it to use the jQuery Mobile theme CSS classes as an experimental stopgap for people who really needed a datepicker. The issue with this component is it’s fairly heavy for mobile and the UI team is already re-factoring the datepicker from the ground-up so we wanted to shift this out of the official GitHub repo because it won’t be supported going forward. We will pull the new UI datepicker in once it’s finished, but that will be later this year. In the meantime, if you still want to use the experimental datepicker, it’s now available on Filament Group’s GitHub repo but note that it’s not being actively maintained. If anyone is interested in maintaining this plugin in the short-term, please let us know. You can also check out alternate jQuery datepickers like DateBox, a slick jQuery Mobile optimized date picker.
Beta 1 upgrade notes
Breaking Changes
- ajaxFormsEnabled and ajaxLinksEnabled are now gone (they were deprecated for a release or two). Use ajaxEnabled to globally set auto-ajax handling.
- Removed the dynamically-appended viewport Meta tag. Thish was deprecated in Alpha 4, and scheduled for removal in beta. jQM users must provide their own meta viewport tag in the head of jQM page markup.
Deprecations
- The signature for
changePage() has changed during this refactor you will need to update your custom code before upgrading. To ease the transition to the new signature in the short-term, we’ve added code to changePage() that maps any old signature calls to changePage() into a new call. This code will be removed before shipping 1.0.
$.mobile.pageLoading( done ) renamed to $.mobile.showPageLoadingMsg() and$.mobile.hidePageLoadingMsg(). Status: $.mobile.pageLoading( done ) is still in the codebase but will be removed soon. Do not use anymore.
Important Notes
- jQuery code that binds to live click events may have issues with the new URL hiding techniques because we bind to the fastclick event (touch + mouse click). In these situations, you may need to tweak your code to either bind to
vclick events instead of click, or set the useFastClick global config option to tell the automated Ajax handling use an ordinary click events instead. Disabling this feature will introduce a slight delay in clicking links and the URL bar will not be hidden.
- Auto back button additions to toolbar are now off by default. To turn auto backbuttons on, you can set the page plugin’s autoBackBtn option to true per page, or globally via its configuration prototype. You can also use the data-auto-back-btn attribute on a page div.
$.mobile.defaultTransition is now renamed to $.mobile.defaultPageTransition and $.mobile.defaultDialogTransition. This is likely not a breaking change since the old configuration property, $.mobile.defaultTransition, will just be ignored.
Change log
Added utility functions $.mobile.getDocumentBase() and $.mobile.getDocumentUrl() – developers can retrieve the original base and url used when loading the document.
Added themeFilter option for listviews (issue 1790) – Available as data attribute data-filter-theme on listviews with filters enabled. Thanks adamvaughan!
Added new throttledresize special event (issue 1848 and 1422) – This prevents browsers from running continuous callbacks on resize, which we use internally for orientationchange in browsers like IE. It still ensures that a held event will execute after the timeout, so logic that depends on the final conditions after a resize is complete will still execute properly. This improves performance noticeably.
Set page min-height using availHeight or availWidth – Rather than height to fine tune height to exclude browser chrome. Also, reset the active page height on throttledresize and pageshow, eliminating some duplicate calls.
Removing item from inset list doesn’t redo corners (issue 1654) – When adjusting the list items, the corner classes went’ being properly adjusted. Thanks siromega!
Remove active state from buttons when closing dialogs (issue 1839) – Buttons would retain the active state if clicked and the dialog was re-opened.
Radio buttons in nested listviews don’t work (issue 1489) – Tweaked selectors to fix this situation. Thanks bernharduw!
Fixed a bug in IE desktop – calling scrollTop before domready was trying to access the body element before it was present. Moved this logic to domready and all’s well.
No change event triggered on multiple select when first option was deselected (issue 1579) – Custom multiple select event fixes. Thanks wtw!
Top header (and back button) of a nested list doesn’t render correctly when parent list has a thumbnail (issue 1595) – Fixed so Back button doesn’t gets clipped when there is no title
Disabled select usability issues in iOS (issue 1816) – A disabled select could be opened in iOS, but not closed due to an inportant cursor rule in the CSS.
Dialog styling and hashchange nav improvements (issue 1826) – Style a dialog is data-role=’dialog” is set on page container and ensure that hash nav between dialogs works.
Forward page transition fix (issue 1833) – If hit the browser’s forward button in some cases, you would not see a transition.
Workaround for PhonegGap double slashes in URL – Adjusted the urlParserRE regexp to account for double slashes in the directory path to work around a PhoneGap 0.9.4.
Height issue for transitioning page (issue 1507) – Fixed the issue where buttons and other elements were sometimes showing up at 100% height during page transitions. Thanks Eddie Monge.
Allow checkboxes and radio buttons to be selected with the keyboard – The name says it all, thanks Shana Golden.
Fixed header/footer positioning in IE 7/8 – Desktop IE wasn’t reporting a scrollTop value for fixed headers/footers—’window’ is now provided as a fallback in the event that $(document).scrollTop() reports zero. Thanks Mat Marquis (wilto).
Select menus now work in Firefox Mobile (issue 1626) – Changed the hiding mechanism for invisible native selects so that they work in Firefox Mobile.
Removed the ajaxLinksEnabled and ajaxFormsEnabled settings – These were deprecated in a4 and scheduled for removal. Automated link and form ajax handling can still be globally disabled via the ajaxEnabled option.
Add new focus event to show the clear button on search textbox when an item is pasted directly without a key event to search text box. Thanks joshiabk
Listview filter speed improvements (issue 1477) – We made a number of changes to improve the responsiveness of the filtering mechanism which is especially helpful on longer lists. More tweaks planned for the future. Thanks nsaleh
Phonegap: Pages with data-ajax=”false” on form fail to load (issue 1580) – 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. Reworked the code to handle action and check to make sure we have an attribute and url string before attempting to use them.
Base tag regression fixed (issue 1508) – This change sets the base tag properly on page load and page changes, corresponding with the recent change to absolute path hash urls. Images and other assets will direct relative to the document in which they reside.
Can’t load file:// pages (issue 1578) – 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.
Grouped radio buttons with long labels don’t ellipsis (issue 1419) – Fixed grouped radio buttons with long labels so they wrap to multiple lines. Thanks gseguin!
Regex breaking Firefox >3.6 (issue 1514) – Tweaked regex to make Firefox happy. A quick bit of Date()-based benchmarking showed an improvement from ~4.5 seconds to 3ms in Firefox 3.6. The stock Android browser on my Galaxy Tab went from ~3.6 seconds to 1ms. Thanks MaxThrax
Radiobuttons can’t be selected once they are selected, then de-selected (issue 1532) – Fixed by using jQuery attr accessor instead of expando to guarantee consistent values.
Regex breaking Firefox >3.6 (issue 1514) – Fixed by 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). Thanks Paul Nicholls!
Fixed base tag support (issue 1508) – This change sets the base tag properly on page load and page changes, corresponding with the recent change to absolute path hash urls. Images and other assets will direct relative to the document in which they reside.
Can’t load file:// pages (issue 1578) – Fixed a regression that 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.
Tops of pages clipped after returning from a dialog (issue 1461)
If you had scrolled down on a page, opened a dialog, then closed it, the page height was getting clipped off in iOS due to the timing of when we were placing focus back on the page. Solution: Delayed the setting of focus till after the scroll position is restored.
Active class not being removed correctly – If a link had an null or “#” value for the href, the active class wasn’t being removed. Modified the vclick handler code in navgation.js so that it doesn’t place the ui-btn-active class on any links meant for interactivity. Removed the return false in the vclick handler of collapsible and replaced it with a preventDefault().
Errors when trying to delete DOM elements (issue 1492) – Thanks @brukhabtu
Collapsible block prevents page scrolling on iPhone 4 (issue 1157) – Fixed events that prevented scrolling when interacting with collapsibles
Bad scroll performance since A4 on iPhone 3G (issue 1407) – Touch event tweaks for smoother scrolling on older iOS devices
Adding items to listviews on a4.1 is too slow (issue 1424) – Optimizations to listview rendering code
Download
We provide CDN-hosted versions of jQuery Mobile for you to include into your site. These are already minified and compressed – and host the image files as well. It’ll likely be the fastest way to include jQuery Mobile in your site.
CDN-Hosted JavaScript:
CDN-Hosted CSS:
Copy-and-Paste Snippet for CDN-hosted files (recommended):
<link rel="stylesheet" href="http://code.jquery.com/mobile/1.0b1/jquery.mobile-1.0b1.min.css" />
<script src="http://code.jquery.com/jquery-1.6.1.min.js"></script>
<script src="http://code.jquery.com/mobile/1.0b1/jquery.mobile-1.0b1.min.js"></script>
If you want to host the files yourself you can download a zip of all the files:
ZIP File:
We’re completing final testing now for a release of Beta 2 early next week. We’re really excited about all the improvements and bug fixes we’ve landed in the last month and can’t wait for this to be released. We’ll keep everyone updated on Twitter as we get closer to the release.
We’ve been trying a number of different ideas internally on how to add in more traditional API-style docs to the demos & docs site and have a proposed solution that essentially adds a simple tab strip to all the plugin detail pages where we can document the options, methods and events that a more technical developer might need. We’ve tried to strike a balance between presenting the simpler, markup-based approach that a designer may need and the more advanced script-driven details that a developer requires.
O’Reilly has just posted a digital early release version of their forthcoming book “jQuery Mobile: Up and Running” by Maximiliano Firtman. It’s well-written and covers Beta 1 code so it’s really up-to-date for a book. Here’s the description from O’Reilly:
If you’re looking for a spinner-style date and time picker that works with jQuery Mobile, check out the new mobiscroll plugin. It has a really slick looking interface and is built to be easily themeable (though I don’t believe it uses the jQuery Mobiel theme framework). This widget supports selecting dates, times and seems easily configurable for custom picker situations. It works with both touch input and mouse/scrollwheel input. Best of all, it is tested in iOS4, Android 2.2, Android 2.3, Chrome, Safari, and Firefox. Check out the project homepage, documentation and demo pages to learn more or download a zip of the code to give it a try.
