Skip to content
This repository was archived by the owner on Oct 8, 2021. It is now read-only.

1.4 Upgrade Guide

Jump to bottom
Jasper de Groot edited this page Oct 10, 2013 · 6 revisions

Work in progress:

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

Supported platforms

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 (:before, :after) support. This means Internet Explorer 7 and Blackberry OS 5 are now C-grade.

Theming

Default theme

The default theme has been replaced and the new theme has two swatches, A (light) and B (dark). To keep using similar colors you have to change the value you set for option theme (data-theme=”*”):

  • theme C and D → A
  • theme A → B

If you were using the blue or yellow style from the B and E swatch you have to create a custom swatch for which you can use the ThemeRoller.

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 updating your theme settings.

Custom 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

Option theme

We also changed the default for option theme in some widgets. The general rule is now that all themeable components inherit the theme swatch from the closest container with a theme specified. If there is no other container with a theme setting, this will be from the page which now defaults to theme A. Because widgets don’t have a default theme specified anymore, you must set a theme if you use widgets outside a page.

Overview:

  • 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 a page and a 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.

Icons

When you are using custom icons you have to change the selector in your icon background-image rules, because in 1.4 we use the :after pseudo element instead of generating a span with the icon class. See the icon demo page.

The classes to have black instead of white and icons without background disc have been renamed.

  • 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 add set the option (data-iconshadow=”true”) but add class ui-shadow-icon to the button or its container.

Buttons

Button markup

Widgets

Initialization

Many widgets (panel, popup, toolbar) can now be used outside/without a page (<div data-role=”page”>). However, when 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();

Option enhanced

Clone this wiki locally