jQuery Mobile 1.5 Upgrade Guide

link Overview

This guide will assist in upgrading from jQuery Mobile 1.4.x to jQuery Mobile 1.5.x. All changes are listed below, organized by component, along with how to upgrade your code to work with jQuery Mobile 1.5.

link API Redesigns

jQuery Mobile 1.5 introduces API redesigns for Button, Checkboxradio, Controlgroup, Toolbar, Navbar, and Table.

1.5 maintains full compatibility with the 1.4 API by default. This is accomplished by rebuilding the 1.4 API on top of the 1.5 API. The default behavior for all 1.5 releases will be to simultaneously use the 1.4 and 1.5 APIs, deferring to the 1.4 API if there is a conflict. If you would like to load just the 1.5 API without the 1.4 API, you can set the $.mobileBackcompat flag to false.

1
2
3
 
<script src="jquery.js"></script>
<script>$.mobileBackCompat = false;</script>
<script src="jquery-mobile.js"></script>

This will prevent the initialization of the back-compat layer, allowing you to use the 1.5 API in cases where there is a conflict with the 1.4 API.

link Preparing for jQuery Mobile 1.5

The API redesigns deprecate a lot of functionality, which will be removed in 1.6. You don't have to wait for the 1.6 release in order to find out if your code will work when the 1.4 APIs are removed. You can use the $.mobileBackCompat flag to test this with any 1.5 release.

In addition to just disabling the backcompat layer all of the backcompat code is isolated in backcompat modules for each component and can be excluded by doing a custom build.

If you find a regression from the 1.4 API, please report it in the bug tracker. Even though the 1.4 API is deprecated, it's important for 1.5 releases not to regress so that users are encouraged to upgrade even if they're not ready to use the new APIs.

link General changes

Independent of changes to specific components, this release removes support for IE8 and Android 2.3, improves support for AMD, and improves the modularity of the library. The minimal jQuery version supported is now 1.9.x.

It is important to note that no workarounds for IE8 or Android 2.3 were removed in this release however these browsers are no longer tested other than to ensure the library parses. No new workarounds or bug fixes will be added for these browsers.

The following changes from jQuery UI 1.12 also affect jQuery Mobile as these components are a part of jQuery Mobile

link Core

link Removed .focus( delay )

(#9649) The deprecated .focus( delay ) method override has been removed. jQuery UI was using this only in our dialog widget, where we've replaced the delayed focus call with a timeout.

link Removed .zIndex()

(#9156) The deprecated .zIndex() method has been removed, in favor of the new .ui-front / appendTo logic used by all widgets that display an element on top of the page, like dialog and autocomplete.

This method was used by dialog, but because the dialog now has an appendTo option, this plugin method is no longer necessary. If you are using .zIndex(), or building a widget that must stack, check out our guide to create stacking elements with a ui-front class name and appendTo option.

link Added .labels()

(#12475) This release introduces a new jQuery plugin method. .labels() finds all label elements associated with the first selected element.

link Tabs

link Deprecated ui-tab class, replaced with ui-tabs-tab

(#12061) The tabs widget now adds the ui-tabs-tab class instead of the inconsistently named ui-tab to each tab element.

link Widget

(#7053) jQuery UI used to hardcode classes like .ui-corner-all in widgets. We removed the hardcoding and added the ability to customize the style-related classes based on the functional classes. For the dialog, droppable and tooltip widgets, we replaced options that were doing just that.

This also replaces the wrapperClass option in any widgets which had it. You can now use the classes option in the same way.

Here's an example using dialog:

1
2
3
4
5
6
 
$( "#popup" ).popup( {
    classes: {
        "ui-popup": "ui-corner-all awesome-fade-class",
        "ui-popup-close-button": null
    }
} );

link Boolean style options

jQuery Mobile had many boolean options on its widgets that simply toggled a class on the widget to change the display. corners and shadow are great examples of this.

Because of the changes to our markup structure, it is now very easy to do this in your markup or by using the classes option. Thus, all of these options are now deprecated. To toggle these effects simply use the classes option as demonstrated above.

link Theme

link Icons

In 1.4 we switched from using a span element for icons to using a :before or :after pseudo element so that icons could be added with just a class. We were very excited about this at the time but have since realized this causes many problems too. It is less performant, creates an awkward api, can't be target with JavaScript. So after careful consideration with the jQuery UI team, the Mobile team, a lot of reasearch, and the creation of a whole new project (The CSS Chassis Project), we have decided it is best to switch back to using spans for icons so that we dont have to worry about this any more :-). We understand the pain this causes in the upgrade process and apologize, but we felt this was the best approach moving forward for jQuery Mobile.

In addition to the change back to spans we have rethought the way icons are positioned in an effort to both simplify our markup and css and at the same time make it more flexible. Icons are also now no longer absolutely positioned. Icons are now placed inline in the text content of whereever you would like them to be. This means you can now add as many icons to an element as you want and place them anywhere you would like. This makes icons much more flexible in your designs.

To help you with some common positions that are a little more complicated than just inline we have also added a few icon helper classes. ui-widget-icon-block will make your icon centered and display block. This is useful for top an bottom icons. Since icons are now inline elements by default they will right, center, or left justify with your text content. To help with positioning an icon all the way left or right independant of the text we have also added the classes ui-widget-icon-floatbegining and ui-widget-icon-floatend.

You can see examples of the new and old markup for icons in the Button section below.

link Enhancer

In 1.4 auto-enhancment was handled by a combination of a widget registry in the same file as the page widget, a custom method in the helpers module, and an extension to the base widget factory.

We did a complete rethink of how auto-enhancment with jQuery should work and the new module is FAST. Depending on the number of elements needing methods called its actually faster than directly calling each as the selection from the DOM is done only once per call. To make this possible and to expand past just widgets we have decided to make two major changes.

First we have deprecated the ability to set a custom name space for data-attributes. jQuery mobile will now always use the ui name space on all data-attributes.

Old API:

1
 
<div data-role="page">

New API:

1
 
<div data-ui-role="page">

The second change is all widgets roles will now follow the pattern data-ui-role="method" where method can be any valid jQuery method. So things like all inputs with a type of text being automatically enhanced will no longer happen. You will need to add data-ui-role="textinput" to the input.

Old API:

1
2
 
<input type="text" id="awesome-input" name="awesome-input">
<input type="range" id="awesome-range" name="awesome-range">

New API:

1
2
 
<input type="text" data-ui-role="textinput" id="awesome-input" name="awesome-input">
<input type="number" data-ui-role="slider" id="awesome-range" name="awesome-range">

link Degrade Inputs

In 1.4 and prior versions to promote progressive enhancement we had certain input types "auto-degrade". A search to a text and a range to a number for example. The reason for this was to avoid the native html 5 control rendering so we can use the custom widget. There was one major problem with this which was that you can't just change the type attribute on an input in Internet Explorer. This means we needed to actually create a new element and replace it. This is a very destructive process because any data which was previously set or event listeners will be lost as the element has been replaced.

Starting in jQuery Mobile 1.5 this behivor is deprecated. You will now need to use the proper input type for the widget you are initalizeing. The only widgets which are affected by this change are textinput with a type of search and slider.

Old API:

1
2
 
<input type="search" id="awesome-input" name="awesome-input">
<input type="range" id="awesome-range" name="awesome-range">

New API:

1
2
 
<input type="text" data-ui-role="textinput" data-ui-type="search" id="awesome-input" name="awesome-input">
<input type="number" data-ui-role="slider" id="awesome-range" name="awesome-range">

link Keep Native

In 1.4 $.mobile.keepNative allowed you to set a selector which you could add to avoid auto-enhancment. Now that all auto initialization is explicit this option is no longer needed and will be deprecated. There is no replacment for this option other than to just not add a data-ui-role to elements you don't want enhanced.

link Button

link General Markup

As part of our efforts to share code and merge with jQuery UI the Button widget is now shared by jQuery UI and Mobile and the base widget lives in the jQuery UI Repository. jQuery Mobile adds a layer on top of the jQuery UI Button adding additional functionality and implementing the 1.4 API. As part of this all of the ui-btn* classes have been changed to ui-button* for consistency. You will see this change reflected in all of the examples below.

link Corners

The corners option has been deprecated in jQuery mobile 1.5. Instead use the classes option.

Old API:

1
 
<button data-corners="false">Button</button>

New API:

1
 
<button data-ui-role="button" data-ui-classes='{"ui-button": "ui-shadow"}'>Button</button>

or if you don't need to manage the button options with JS you can still do

1
 
<button class="ui-button ui-shadow">Button</button>

link Shadow

The shadow option has been deprecated in jQuery mobile 1.5. Instead use the classes option.

Old API:

1
 
<button data-shadow="false">Button</button>

New API:

1
 
<button data-ui-role="button" data-ui-classes='{"ui-button": "ui-corner-all"}'>Button</button>

or if you don't need to manage the button options with JS you can still do

1
 
<button class="ui-button ui-corner-all">Button</button>

link Mini

The Mini option has been deprecated in jQuery mobile 1.5. Instead use the classes option.

Old API:

1
 
<button data-mini="true">Button</button>

New API:

1
 
<button data-ui-role="button" data-ui-classes='{"ui-button": "ui-corner-all ui-shadow ui-mini"}'>Button</button>

or if you don't need to manage the button options with JS you can still do

1
 
<button class="ui-button ui-corner-all ui-shadow ui-mini">Button</button>

link Icon Position

The iconpos option from 1.4 has been renamed to iconPosition for ` 1.5.

Old API:

1
 
<button data-icon="gear" data-iconpos="top">Button</button>

New API:

1
 
<button data-ui-icon="ui-icon-gear" data-ui-icon-position="top">Button</button>

In addition the values of none and notext have been deprecated. To replace none simply don't add an icon. The no text value is now replaced by a new option showLabel.

Old API:

1
2
 
<button data-ui-icon="gear" data-ui-icon-position="none">Button</button>
<button data-ui-icon="gear" data-ui-icon-position="notext">Button</button>

New API:

1
2
 
<button data-ui-role="button">Button</button>
<button data-ui-icon="ui-icon-gear" data-ui-show-label="false">Button</button>

To accomodate efforts to improve the ability of our widgets to be used in RTL direction we have also renamed the left and right values to beginning and end respectively.

Old API:

1
2
 
<button data-ui-icon="gear" data-ui-iconpos="right">Button</button>
<button data-ui-icon="gear" data-ui-iconpos="left">Button</button>

New API:

1
2
 
<button data-ui-icon="ui-icon-gear" data-ui-icon-position="end">Button</button>
<button data-ui-icon="ui-icon-gear" data-ui-icon-position="beginning">Button</button>

Mentntioned in the icon section above icons are no longer absolutely positioned this means that in a full width button the icon will sit next to the text instead of flush left or right by default. To acheive a flush left or right icon simply add ui-widget-icon-floatend or ui-widget-icon-floatend to the icon using the classes option.

Old API:

1
2
 
<button data-ui-icon="gear" data-ui-icon-position="right">Button</button>
<button data-ui-icon="gear">Button</button>

New API:

1
2
 
<button data-ui-role="button" data-icon-position="end" data-ui-classes='{"ui-button-icon": "ui-widget-icon-floatend"}'>Button</button>
<button data-ui-role="button" data-icon-position="beginning" data-ui-classes='{"ui-button-icon": "ui-widget-icon-floatbeginning"}'>Button</button>

link Inline

The Inline option has been deprecated in jQuery mobile 1.5. Instead use the classes option.

Old API:

1
 
<button data-mini="true">Button</button>

New API:

1
 
<button data-ui-role="button" data-ui-classes='{"ui-button": "ui-corner-all ui-shadow ui-button-inline"}'>Button</button>

link Icon

In 1.4 the icon option accepted a string representing the name of an icon. In 1.5 this has been switched to being the class for an icon for increased flexibility with 3rd party icons.

Old API:

1
 
<button data-ui-icon="gear" data-ui-icon-position="right">Button</button>

New API:

1
 
<button data-ui-icon="ui-icon-gear" data-ui-icon-position="end">Button</button>