GitHub PullRequestReviewCommentEvent at 2014-01-10 12:57:50
Repository: jquerymobile.com
Actor: arschmitz
Payload: {"comment":{"url":"https://api.github.com/repos/jquery/jquerymobile.com/pulls/comments/8787374","id":8787374,"diff_hunk":"@@ -1,5 +1,457 @@\n <script>{\n-\t\"title\": \"jQuery Mobile 1.4 Upgrade Guide\"\n+        \"title\": \"jQuery Mobile 1.4 Upgrade Guide\",\n+        \"toc\": true\n }</script>\n \n-The 1.4 upgrade guide will be published here within a few days.\n+## Introduction\n+\n+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](http://jquerymobile.com/changelog/1.4.0/) for a list of all changes and new features. \n+\n+\n+## Supported platforms\n+\n+In previous versions A-grade support was based on whether 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.\n+\n+\n+## Theming\n+\n+### Default theme\n+\n+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 the option `theme` (`data-theme=\"*\"`).\n+\n+Examples:\n+\n+#### Light\n+\n+To have a widget using a light swatch set theme A instead of C or D.\n+\n+Old:\n+```\n+<ul data-role=\"listview\" data-theme=\"d\">\n+        <li>List item</li>\n+</ul>\n+```\n+\n+New:\n+```\n+<ul data-role=\"listview\" data-theme=\"a\">\n+        <li>List item</li>\n+</ul>\n+```\n+\n+#### Dark\n+\n+To have a widget using a dark swatch set theme B instead of A.\n+\n+Old:\n+```\n+<ul data-role=\"listview\" data-theme=\"a\">\n+        <li>List item</li>\n+</ul>\n+```\n+\n+New:\n+```\n+<ul data-role=\"listview\" data-theme=\"b\">\n+        <li>List item</li>\n+</ul>\n+```\n+\n+Be aware of changes in the default values (see [Option `theme`](#option-theme) below) before upgrading your theme.\n+\n+The blue and yellow swatches didn't return in the new default theme. You can use the [ThemeRoller](http://themeroller.jquerymobile.com) to create a complete custom theme or to add swatches to the default theme.\n+\n+For convenience we updated the 1.3 default theme to 1.4 and added it as [\"classic\" theme](http://demos.jquerymobile.com/1.4.0/theme-classic/) to the demos.\n+\n+### Custom theme\n+\n+When upgrading to 1.4 you have to replace your custom theme file. The easiest way to upgrade your 1.3 custom theme is by uploading it in the [ThemeRoller](http://themeroller.jquerymobile.com) and download it as 1.4 theme.\n+\n+#### Gradients\n+\n+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.\n+\n+Example:\n+\n+1.3 custom theme:\n+```\n+.ui-body-a,\n+.ui-overlay-a {\n+        border: 1px solid #111 /*{a-body-border}*/;\n+        background: #333 /*{a-body-background-color}*/;\n+        color: #fff /*{a-body-color}*/;\n+        text-shadow: 0 /*{a-body-shadow-x}*/ 1px /*{a-body-shadow-y}*/ 0 /*{a-body-shadow-radius}*/ #111 /*{a-body-shadow-color}*/;\n+        font-weight: normal;\n+        background-image: -webkit-gradient(linear, left top, left bottom, from( #444 /*{a-body-background-start}*/), to( #222 /*{a-body-background-end}*/)); /* Saf4+, Chrome */\n+        background-image: -webkit-linear-gradient( #444 /*{a-body-background-start}*/, #222 /*{a-body-background-end}*/); /* Chrome 10+, Saf5.1+ */\n+        background-image:    -moz-linear-gradient( #444 /*{a-body-background-start}*/, #222 /*{a-body-background-end}*/); /* FF3.6 */\n+        background-image:     -ms-linear-gradient( #444 /*{a-body-background-start}*/, #222 /*{a-body-background-end}*/); /* IE10 */\n+        background-image:      -o-linear-gradient( #444 /*{a-body-background-start}*/, #222 /*{a-body-background-end}*/); /* Opera 11.10+ */\n+        background-image:         linear-gradient( #444 /*{a-body-background-start}*/, #222 /*{a-body-background-end}*/);        \n+}\n+```\n+1.4 custom theme:\n+\n+```\n+.ui-body-a,\n+.ui-page-theme-a .ui-body-inherit,\n+html .ui-bar-a .ui-body-inherit,\n+html .ui-body-a .ui-body-inherit,\n+html body .ui-group-theme-a .ui-body-inherit,\n+html .ui-panel-page-container-a {\n+        background: #333 /*{a-body-background-color}*/;\n+        border-color: #111 /*{a-body-border}*/;\n+        color: #fff /*{a-body-color}*/;\n+        text-shadow: 0 /*{a-body-shadow-x}*/ 1px /*{a-body-shadow-y}*/ 0 /*{a-body-shadow-radius}*/ #111 /*{a-body-shadow-color}*/;\n+        /* Copied from 1.3 custom theme: */\n+        background-image: -webkit-gradient(linear, left top, left bottom, from( #444 ), to( #222 )); /* Saf4+, Chrome */\n+        background-image: -webkit-linear-gradient( #444, #222 ); /* Chrome 10+, Saf5.1+ */\n+        background-image:    -moz-linear-gradient( #444, #222 ); /* FF3.6 */\n+        background-image:     -ms-linear-gradient( #444, #222 ); /* IE10 */\n+        background-image:      -o-linear-gradient( #444, #222 ); /* Opera 11.10+ */\n+        background-image:         linear-gradient( #444, #222 );    \n+}\n+```\n+\n+#### New styles\n+\n+Compared to previous versions there are two new styles that you can specify in the theme CSS.\n+\n+##### Page style\n+\n+Pages get theme class `ui-page-theme-*`, where `*` is the value (a-z) of the option `theme`. This used to be `ui-body-*`. When you use the ThemeRoller to upgrade your 1.3 custom theme, it will initially use the same color for the page style as the one you specified for the body style. You can customize the colors to create contrast between the page and body styled elements like read-only list items and collapsible content.\n+\n+##### Active and focus style for each swatch\n+\n+The active and focus state used to use one global style, but they are now themeable. When you use the ThemeRoller to upgrade your 1.3 custom theme, it will initially use the 1.3 global active and focus color for all swatches. You can customize this for each swatch.\n+\n+\n+#### Override with custom CSS\n+\n+When you are using custom CSS to override styles that are defined in the theme CSS you might have to change your selectors to take the following changes into account:\n+\n+* We now use pseudo classes for button hover (`:hover`) and down (`:active`) state\n+* The level of [specificity](http://www.w3.org/TR/css3-selectors/#specificity) of many selectors has been increased due to a switch from JS to CSS for theme inheritance\n+\n+Example custom button hover style:\n+\n+Old:\n+```\n+/* Default: */\n+.ui-btn-hover-a {\n+        /* Button hover style */\n+}\n+\n+/* Override: */\n+.ui-mobile .ui-btn-hover-a {\n+        /* Custom button hover style */\n+}\n+```\n+\n+New:\n+```\n+/* Default: */\n+.ui-page-theme-a .ui-btn:hover,\n+html .ui-bar-a .ui-btn:hover,\n+html .ui-body-a .ui-btn:hover,\n+html body .ui-group-theme-a .ui-btn:hover,\n+html head + body .ui-btn.ui-btn-a:hover {\n+        /* Button hover style */\n+}\n+\n+/* Override: */\n+.ui-mobile .ui-btn.ui-btn-a:hover {\n+        /* Custom button hover style */\n+}\n+```\n+\n+\n+### Option `theme`\n+\n+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.\n+\n+Changes in the defaults:\n+\n+* Page: C → A\n+* Loader: E → A\n+* Header and Footer toolbars: A → inherit\n+* Listview dividers: B → inherit\n+* Listview count bubbles: C → inherit\n+* Panels: C → inherit\n+\n+Example: If you are using the default theme and don’t set a theme for the page and the header inside that page:\n+* The page was using theme swatch C (light) and will now use theme swatch A (light) - No changes needed.\n+* 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.\n+\n+\n+## Buttons\n+\n+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.\n+\n+Old:\n+```\n+/* Markup: */\n+<button>Button</button>\n+\n+/* After enhancement: */\n+<div data-corners=\"true\" data-shadow=\"true\" data-iconshadow=\"true\" data-wrapperels=\"span\" data-theme=\"c\" data-disabled=\"false\" class=\"ui-btn ui-shadow ui-btn-corner-all ui-btn-up-c\" aria-disabled=\"false\">\n+        <span class=\"ui-btn-inner\">\n+                <span class=\"ui-btn-text\">Button</span>\n+        </span>\n+        <button class=\"ui-btn-hidden\" data-disabled=\"false\">Button</button>\n+</div>\n+```\n+\n+New:\n+```\n+/* Markup: */\n+<button>Button</button>\n+\n+/* After enhancement: */\n+<button class=\"ui-btn ui-shadow ui-corner-all\">Button</button>\n+```\n+\n+To style anchor or button elements as jQuery Mobile buttons add the applicable classes to your markup, instead of `data-` attributes.\n+\n+* data-role=\"button\" → class=\"ui-btn\"\n+* data-theme=\"a\" → class=\"ui-btn-a\" (replace \"a\" by the actual theme swatch letter that you want to use)\n+* data-corners=\"true\" → class=\"ui-corner-all\"\n+* data-shadow=\"true\" → class=\"ui-shadow\"\n+* data-mini=\"true\" → class=\"ui-mini\"\n+* data-icon=\"home\" → class=\"ui-icon-home\" (replace \"home\" by the actual name of the icon that you want to use)\n+* data-iconpos=\"right\" → class=\"ui-btn-icon-right\" (replace \"right\" by the actual icon position that you want to use: right, left, top, or bottom)\n+* data-iconshadow=\"true\" → class=\"ui-shadow-icon\"\n+\n+Note that in cases where you didn't have to add the `data-` attribute because you used the default value, you do have to add the corresponding class.\n+\n+Old:\n+```\n+<a href=\"#\" data-role=\"button\" data-theme=\"b\" data-mini=\"true\" data-icon=\"grid\">Link button</a>\n+```\n+\n+New:\n+```\n+<a href=\"#\" class=\"ui-btn ui-corner-all ui-shadow ui-mini ui-btn-icon-right ui-icon-grid\">Link button</a>\n+```\n+\n+Only use the Button widget, and `data-` attributes, for `input` buttons. Input buttons don't have content so the widget generates a wrapper to make it possible to use the ```:after``` pseudo element for the icon.\n+\n+\n+## Icons\n+\n+### Pseudo elements\n+\n+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.\n+\n+Example:\n+```\n+.ui-icon-myicon:after {\n+    background-image: url(\"path/to/your-icon.png\");\n+    background-size: 18px 18px;\n+}\n+```\n+\n+### Alt and nodisc icons\n+\n+The alt (black instead of white) and nodisc (no background disc) icon classes have been renamed. Make the following changes in your markup:\n+\n+* `class=\"ui-icon-alt\"` → `class=\"ui-alt-icon\"`\n+* `class=\"ui-icon-nodisc\"` → `class=\"ui-nodisc-icon\"`\n+\n+Example:\n+\n+Old:\n+```\n+<ul data-role=\"listview\" class=\"ui-icon-alt ui-icon-nodisc\">\n+        <li>List item</li>\n+</ul>\n+```\n+\n+New:\n+```\n+<ul data-role=\"listview\" class=\"ui-alt-icon ui-nodisc-icon\">\n+        <li>List item</li>\n+</ul>\n+```\n+\n+### Icon shadow\n+\n+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.\n+\n+\n+## Navigation\n+\n+Deprecated the `$.mobile.changePage` and `$.mobile.loadPage`. Use the change and load methods of the new Pagecontainer widget instead.\n+\n+Old:\n+```\n+$.mobile.changePage( \"newpage.html\", { transition: \"slide\" });\n+```\n+\n+New:\n+```\n+$( \"body\" ).pagecontainer( \"change\", \"newpage.html\", { transition: \"slide\" });\n+```\n+\n+\n+## Widgets\n+\n+### Initialization\n+\n+#### Pagecreate instead of pageinit\n+\n+The `pageinit` event has been deprecated. Bind to `pagecreate` instead.\n+```\n+$( document ).on( \"pagecreate\", function() {\n+        ... do something when widgets are initialized ...\n+});\n+```\n+\n+#### Standalone widgets\n+\n+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.\n+\n+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.\n+\n+#### initSelector\n+\n+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.\n+\n+Example: If you want to initialize the listview plugin for all unordered lists instead of only the ones with `data-role=\"listview\"`:\n+```\n+$( document ).on( \"mobileinit\", function() {\n+$.mobile.listview.prototype.initSelector = \"ul\";\n+});\n+```\n+Note: Always bind handlers to the `mobileinit` event *before* jQuery Mobile JS is loaded!\n+\n+#### enhanceWithin\n+\n+`.trigger( \"create\" )` has been deprecated. Use the new method `.enhanceWithin()` instead.\n+\n+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();`\n+\n+\n+### Using defaults\n+\n+You can now add `data-defaults=\"true` to tell the widget to use the default values for all options. Retrieving option values from `data-` attributes will be skipped, which improves startup performance.\n+\n+Example:\n+```\n+<div data-role=\"collapsible\" data-defaults=\"true\">\n+  <h2>Header</h2>\n+  <p>Content.</p>\n+</div>\n+```\n+\n+\n+### Added `enhanced` option\n+\n+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.\n+\n+Widgets that *don't* have option `enhanced` (yet) are: Listview, Selectmenu, Panel, Toolbar, Navbar, and Slider.\n+\n+Example of using option `enhanced` with the button widget:\n+\n+Normal:\n+```\n+<form>\n+        <label for=\"myinput\">Button label:</label> \n+    <input type=\"button\" id=\"myinput\" data-icon=\"delete\" value=\"Button text\">\n+</form>\n+```\n+\n+Enhanced:\n+```\n+<form>\n+        <label for=\"myinput\">Button label:</label> \n+    <div class=\"ui-input-btn ui-btn ui-icon-delete ui-btn-icon-left ui-corner-all ui-shadow\">\n+        Button text\n+        <input type=\"button\" id=\"myinput\" data-enhanced=\"true\" value=\"Button text\">\n+    </div>\n+</form>\n+```\n+\n+## Page and Dialog\n+\n+### Deprecated Dialog widget, added page option `dialog`\n+\n+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.\n+\n+To use a pop transition for the dialog, you have to explicitly set the transition. Otherwise the default page transition (fade) will be used.\n+\n+```\n+<a href=\"#my-dialog-page\" data-transition=\"pop\">Open dialog page with pop transition</a>\n+```\n+\n+### Content\n+\n+`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.\n+\n+### Toolbars\n+\n+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.\n+\n+\n+## Collapsible\n+\n+.trigger( \"expand|collapse\" ) no longer works. Use the new expand and collapse methods instead.\n+\n+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.\n+\n+\n+## Field containers\n+\n+`data-role=\"fieldcontain\"` has been deprecated. Add class `ui-field-contain` instead.\n+\n+\n+## Listview\n+\n+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 the classes `ui-li`, `ui-li-heading`, and `ui-li-desc` and there are no generated elements inside list items anymore.\n+\n+### Images\n+\n+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.\n+\n+* When you use a thumbnail: Add class `ui-li-has-thumb` to the list item. Note: The framework no longer adds class `ui-li-thumb` to the `img` element. \n+* 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.\n+* When you want an element other than `img` (eg. a font icon) to be styled as thumbnail: Add class `ui-li-has-thumb` to the list item and class `ui-li-thumb` to the element.\n+\n+### Filter\n+\n+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.\n+\n+Example:\n+```\n+<form class=\"ui-filterable\">\n+    <input id=\"filter-input\" data-type=\"search\">\n+</form>\n+<ul data-role=\"listview\" data-filter=\"true\" data-input=\"#filter-input\">\n+    <li>List item 1</li>\n+    <li>List item 2</li>\n+    <li>List item 3</li>\n+</ul>\n+```\n+\n+## Panel\n+\n+The properties and values of option `classes` have been changed. The CSS has been updated to use the new default values as classnames in the selectors.\n+\n+* `pagePanel: \"ui-page-panel\"` (class was added to the page) → `pageContainer: \"ui-panel-page-container\"` (class added to the page container)\n+* `pagePanelOpen: \"ui-page-panel-open\"` → no longer used\n+\n+* `contentWrap: \"ui-panel-content-wrap\"` → `pageWrapper: \"ui-panel-wrapper\"`\n+* `contentFixedToolbar: \"ui-panel-content-fixed-toolbar\"` → `pageFixedToolbar: \"ui-panel-fixed-toolbar\"`\n+\n+* `contentWrapOpen: \"ui-panel-content-wrap-open\"` → `pageContentPrefix: \"ui-panel-page-content\"`\n+* `contentFixedToolbarOpen: \"ui-panel-content-fixed-toolbar-open\"` → `pageContentPrefix: \"ui-panel-page-content\"`\n+\n+* `contentWrapClosed: \"ui-panel-content-wrap-closed\"` → no longer used\n+* `contentFixedToolbarClosed: \"ui-panel-content-fixed-toolbar-closed\"` → no longer used\n+\n+Note: `pageContentPrefix: \"ui-panel-page-content\"` is also used as prefix for the display (reveal, overlay, push) and position (left, right) classes.\n+\n+\n+## Slider\n+\n+The Slider flip toggle switch has been deprecated. Use the new Flipswitch widget instead.","path":"pages/upgrade-guide/1.4.md","position":459,"original_position":459,"commit_id":"a7bb7200f3fb9c9c2ade8338fe0d3311740ab607","original_commit_id":"a7bb7200f3fb9c9c2ade8338fe0d3311740ab607","user":{"login":"arschmitz","id":462993,"avatar_url":"https://gravatar.com/avatar/c7ebb4bf8014513304378a9a4d025faa?d=https%3A%2F%2Fidenticons.github.com%2F9992d02e5580ef97339b014be71cd6b8.png&r=x","gravatar_id":"c7ebb4bf8014513304378a9a4d025faa","url":"https://api.github.com/users/arschmitz","html_url":"https://github.com/arschmitz","followers_url":"https://api.github.com/users/arschmitz/followers","following_url":"https://api.github.com/users/arschmitz/following{/other_user}","gists_url":"https://api.github.com/users/arschmitz/gists{/gist_id}","starred_url":"https://api.github.com/users/arschmitz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/arschmitz/subscriptions","organizations_url":"https://api.github.com/users/arschmitz/orgs","repos_url":"https://api.github.com/users/arschmitz/repos","events_url":"https://api.github.com/users/arschmitz/events{/privacy}","received_events_url":"https://api.github.com/users/arschmitz/received_events","type":"User","site_admin":false},"body":"need an example here of how to change their markup to continue to work","created_at":"2014-01-10T12:57:50Z","updated_at":"2014-01-10T12:57:50Z","html_url":"https://github.com/jquery/jquerymobile.com/pull/43#discussion_r8787374","pull_request_url":"https://api.github.com/repos/jquery/jquerymobile.com/pulls/43","_links":{"self":{"href":"https://api.github.com/repos/jquery/jquerymobile.com/pulls/comments/8787374"},"html":{"href":"https://github.com/jquery/jquerymobile.com/pull/43#discussion_r8787374"},"pull_request":{"href":"https://api.github.com/repos/jquery/jquerymobile.com/pulls/43"}}}}