-
Notifications
You must be signed in to change notification settings - Fork 2.4k
1.4 Upgrade Guide
This guide will assist you with upgrading from jQuery Mobile 1.3 to 1.4. It also prepares you for 1.5 by informing you about deprecated features. See the changelog for a list of all changes and new features.
In previous versions A-grade support was based on if a browser supports media queries and added Internet Explorer 7 and 8. As from 1.4 we also test for pseudo element support, because we use :after for icons. This means Internet Explorer 7 and Blackberry OS 5 are now C-grade.
The default theme has been replaced and the new theme has two swatches, A (light) and B (dark). To keep using similar colors as the previous default theme you have to change the value you set for option theme (data-theme="*"):
- Light: C and D → A
- Dark: A → B
The blue and yellow swatches didn't return in the new default theme. You can use the ThemeRoller to create a complete custom theme or to add swatches to the default theme.
For convenience we updated the 1.3 default theme to 1.4 and added it as "classic" theme to the demos.
Be aware of changes in the default values (see "Option theme" below) before upgrading your theme.
When upgrading to 1.4 you have to replace your custom theme file. Compared to previous versions there are two new styles that you have to specify:
- Page theme - Pages used to get the
ui-body-*class - Active and focus state for each swatch - This used to be one global style
When you we using custom CSS to override styles that are defined in the theme CSS you might have to change your selectors to take the following into account:
- We now use pseudo classes for button hover (
:hover) and down (:active) state - The level of specificity of many selectors has been increased due to a switch from JS to CSS for theme inheritance
The easiest way to upgrade your 1.3 custom theme is by uploading it in the ThemeRoller. Please note that because gradients are no longer part of the default theme, they can't be set with the ThemeRoller anymore either. You can still use gradients, but you have to manually copy the background-image settings from your current theme into your 1.4 theme CSS file.
We changed the default for option theme in some widgets. The general rule is now that all themeable components inherit the theme swatch from their container. This is done via CSS. If there is no container for which a theme has been specified, the page theme will be used. This now defaults to theme A. Because widgets don’t have a default theme specified anymore, you must set option theme if you use widgets outside a page.
Changes in the defaults:
- Page: C → A
- Loader: E → A
- Header and Footer toolbars: A → inherit
- Listview dividers: B → inherit
- Listview count bubbles: C → inherit
- Panels: C → inherit
Example: If you are using the default theme and don’t set a theme for the page and the header inside that page:
- The page was using theme swatch C (light) and will now use theme swatch A (light) - No changes needed.
- The header was using theme swatch A (dark) and will now inherit theme swatch A (light) from the page - You have to set the header to theme B (dark) to keep the same style.
Button styled elements used to get enhanced by the buttonMarkup method, which generated the ui-btn-inner and ui-btn-text elements. In 1.4 those inner elements are no longer generated and there are no calls to buttonMarkup() from other widgets anymore.
To style anchor or button elements as jQuery Mobile buttons add the applicable classes to your markup, instead of data- attributes. data-role="button" can be omitted as well.
See Classes in the API documentation for an overview and Button markup in the demos for examples.
Only use the Button widget, and data- attributes, for input buttons. The widget generates a wrapper which is needed for icons.
If you are using custom icons you have to change the selector in your icon background-image rules because we now use the :after pseudo element instead of generating a span with the icon class. See the icon demo page for an example.
The alt (black instead of white) and nodisc (no background disc) icon classes have been renamed. Make the following changes in your markup:
- ui-icon-alt → ui-alt-icon
- ui-icon-nodisc → ui-nodisc-icon
Icon shadow has been deprecated and in widgets that offer option iconShadow the default has been changed to false. If you want to keep using icon shadow (also in future versions) don’t set the option to true, but add class ui-shadow-icon to the button or its container.
Deprecated the $.mobile.changePage and $.mobile.loadPage. Use the change and load methods of the new Pagecontainer widget instead.
Many widgets (panel, popup, toolbar) can now be used outside/without a page (<div data-role="page">). However, when you use a widget outside a page you have to call the plugin yourself.
Example: If you use the same panel with a navmenu on all your pages you can put the markup outside the page and use $( ".myNavPanel" ).panel(); to call the plugin. There is no need to add the data-role="panel" attribute in your markup because that is used for auto initialization only.
Option initSelector has been removed from widgets because you don’t need to set this for every instance of the widget, but you can still configure it.
Example: If you want to initialize the listview plugin for all unordered lists instead of only the ones with data-role="listview":
$( document ).on( "mobileinit", function() {
$.mobile.listview.prototype.initSelector = "ul";
});
Note: Always bind handlers to the mobileinit event before jQuery Mobile JS is loaded!
.trigger( "create" ) has been deprecated. Use the new method .enhanceWithin() instead.
Example: If you dynamically add a collapsible with an ul with data-role="listview" inside, you could use .enhanceWithin() to initialize the listview plugin: $( "#mycollapsible" ).collapsible().enhanceWithin();
An option defaults has been added to the page widget. Set this to true to tell the framework that all widgets on the page use the default values for options that can be set with data- attributes. Retrieving option values from data- attributes will be skipped, which improves startup performance.
Most widgets now have an option enhanced. This allows you to write the markup yourself to improve performance. The default for the option is always false and like most options it is also exposed as data- attribute (data-enhanced). When you set it to true the widget won't do any DOM manipulation at all during enhancement, so you have to make sure all classes and DOM nodes are already present.
Widgets that don't have (yet) are: Listview, Selectmenu, Panel, Toolbar, Navbar, and Slider.
Example of using option enhanced with the button widget:
<form>
<div class="ui-input-btn ui-btn ui-icon-delete ui-btn-icon-left ui-corner-all ui-shadow">
Text
<input type="button" data-enhanced="true" value="Text">
</div>
</form>
Instead of adding data-rel="dialog" to the page anchor link, set page option dialog to true. You can do this by adding data-dialog="true" to the page that you want to be styled as dialog.
To use a pop transition for the dialog, you have to explicitly set the transition. Otherwise the default page transition (fade) will be used.
data-role="content" has been deprecated, add class ui-content and (if applicable) role="main" instead. Using data-theme for the content element has been deprecated as well. We don't recommend using a theme for the content, also not by adding a ui-body-* class, because there can be a gap between the bottom of the content and the bottom of the page.
Headers and footers are now using the new Toolbar widget. When you are using the "add back button" feature, all related data- attributes (data-add-back-btn, etc.) should be added to the toolbar element, instead of the page.
.trigger( "expand|collapse" ) no longer works. Use the new expand and collapse methods instead.
The content of a collapsible now inherits the theme from a parent container by default. Set contentTheme to false (data-content-theme="false") to have a collapsible without content theme.
data-role="fieldcontain" has been deprecated. Add class ui-field-contain instead.
When you are using custom CSS or JS with listviews you might have to update selectors that target list items or their contents. The widget no longer adds classes like ui-li, ui-li-desc, and ui-li-heading and there are no generated elements inside list items anymore.
The auto-detection of images in list items has been deprecated to improve performance and small 16x16 images at the left (ui-li-icon) has been deprecated as feature.
- When you use a thumbnail: Add class
ui-li-has-thumbto the list item. Note: The framework no longer adds classui-li-thumbto theimgelement. - When you want to use a smaller image: Do the same as described for thumbnails above and override the default width and height in your custom CSS.
- When you want an element other than
img(eg. a font icon) to be styled as thumbnail: Add classui-li-has-thumbto the list item and classui-li-thumbto the element.
The filter extension has been deprecated in favor of the new Filterable widget. Add the filter input, wrapped in a form with class ui-filterable, to your markup and add the data-input attribute to the list to specify which input should be used to filter the list items.
Example:
<form class="ui-filterable">
<input id="filter-input" data-type="search">
</form>
<ul data-role="listview" data-filter="true" data-input="#filter-input">
<li>List item 1</li>
<li>List item 2</li>
<li>List item 3</li>
</ul>
The Slider flip toggle switch has been deprecated. Use the new Flipswitch widget instead.