##

Demos

Menu Search

Note: this page has not been updated after 1.3

## Question:

# How do I need to configure PhoneGap/Cordova?

## Answer:

Since PhoneGap/Cordova is frequently used in conjunction with jQuery Mobile, we wanted to offer a few tips and recommendations to help you get started. PhoneGap is an HTML5 app platform that allows developers to author native applications with web technologies and get access to APIs and app stores. Applications are built as normal HTML pages and packaged up to run as a native application within a UIWebView or WebView (a chromeless browser, referred to hereafter as a webview).

## Overview

The initial application document is loaded by the PhoneGap application by a local file:// URL. This means that if you want to pull in pages from your company's remote server (phone home) you will have to refer to them with absolute URLs to your server. Because your document originates from a file:// URL, loading pages or assets from your remote server is considered a cross-domain request that can be blocked in certain scenarios.

Your ability to access cross-domain pages from within a Phone Gap jQuery Mobile application is controlled by two key things: `$.support.cors` and `$.mobile.allowCrossDomainPages`, and can also be influenced by the white list feature in later builds of PhoneGap.

## $.support.cors

In jQuery core, there is a $.support.cors boolean that indicates whether or not jQuery thinks the browser supports the W3C "Cross-Origin Resource Sharing" feature to support cross-domain requests.

Since jQuery Mobile relies on jQuery core's $.ajax() functionality, `$.support.cors` must be set to `true` to tell `$.ajax` to load cross-domain pages. We've heard reports that webviews on some platforms, like BlackBerry, support cross-domain loading, but that jQuery core incorrectly sets `$.support.cors` value to `false` which disables cross-domain $.ajax() requests and will cause the page or assets to fail to load.

## $.mobile.buttonMarkup.hoverDelay

If you find that the button down/hover state (lists, buttons, links etc) feels sluggish the `$.mobile.buttonMarkup.hoverDelay` setting might be of use. It will decrease the time between the touch event and the application of the relevant class but will also result in a higher chance that the same class will be applied even when the user is scrolling (eg, over a long list of links).

## $.mobile.allowCrossDomainPages

When jQuery Mobile attempts to load an external page, the request runs through the page container's `load()` method. This will only allow cross-domain requests if the `$.mobile.allowCrossDomainPages` configuration option is set to `true`. Because the jQuery Mobile framework tracks what page is being viewed within the browser's location hash, it is possible for a cross-site scripting (XSS) attack to occur if the XSS code in question can manipulate the hash and set it to a cross-domain URL of its choice. This is the main reason that the default setting for `$.mobile.allowCrossDomainPages` is set to `false`.

So in PhoneGap apps that must "phone home" by loading assets off a remote server, both the `$.support.cors` AND `$.mobile.allowCrossDomainPages` must be set to `true`. The `$.mobile.allowCrossDomainPages` option must be set before any cross-domain request is made so we recommend wrapping this in a `mobileinit` handler:

    $( document ).on( "mobileinit", function() {
        // Make your jQuery Mobile framework configuration changes here!

        $.mobile.allowCrossDomainPages = true;
    });

## $.mobile.phonegapNavigationEnabled

On Android PhoneGap has as special navigation helper in place to work around issues with Honeycomb `navigator.app.backHistory` that replaces `window.history.back`. For most jQuery Mobile applications it's unecessary to have knowledge or make use of this helper because the vanilla history object works fine for hashchange and replace state alterations of the embedded browser history. If and only if your PhoneGap application uses a full page refresh (eg, for form validation) and you wish to support the Android platform, please make sure to set `$.mobile.phonegapNavigationEnabled = true` either in a `mobileinit` call back or anywhere before user interaction take place with the page. This will replace calls to `window.history.back` with calls to PhoneGap's helper method thereby alleviating history navigation issues associated with full page refreshes on Android devices.

## PhoneGap White Listing

PhoneGap 1.0 introduced the idea of white-listing servers to which its internal webview is allowed to make cross-domain requests. You can find info about it here on the PhoneGap wiki.

However, not all platforms support this white-listing feature so check the PhoneGap documentation for details. Older versions of PhoneGap prior to 1.0 defaulted to allowing cross-domain requests to any server.

## More Tips and Tricks

Here are a few more tips that aren't specifically related to PhoneGap but are good to know:

We recommend disabling the pushState feature for installed apps because there are edge cases where this feature can cause unexpected navigation behavior and since URLs aren't visible in a webview, it's not worth keeping this active in these situations.

Use to following code to disable pushState. Because the mobileinit event is triggered immediately, you'll need to bind your event handler before jQuery Mobile is loaded.

    $(document).bind("mobileinit", function(){
    	$.mobile.pushStateEnabled = false;
    });

Android enforces a timeout when loading URLs in a webview which may be too short for your needs. You can change this timeout by editing a Java class generated by the Eclipse plugin for Android:

`super.setIntegerProperty("loadUrlTimeoutValue", 60000);`

Avoid underscores in files and folders because Phonegap may fail to load the contained files in Android. This is a known issue.

Try `animation-fill-mode` to reduce blinky transitions but beware that we're found that certain devices like the Nexus 7 run animations very slowly when this CSS property is in play. We recommend targeting this carefully and testing thoroughly to ensure that it doesn't impact smoothness. To see how to add this to your CSS, see this commit.

## Building UIWebView apps with jQuery Mobile

It's important to note that when creating a custom, non-PhoneGap, `UIWebView` control in an iOS application you must use the `loadRequest` method in preference to `loadData` for back button support. The snippet below is an example of loading `default.html` in your view controller.

    - (void)viewDidLoad
    {
        [super viewDidLoad];
        NSString *fullURL = [[NSBundle mainBundle] pathForResource:@"dialog" ofType:@"html"];
        NSURL *url = [NSURL fileURLWithPath:fullURL];
        NSURLRequest *requestObj = [NSURLRequest requestWithURL:url];
        [webView loadRequest:requestObj];
    }

- Home
- Introduction
- Buttons
- Button widget

- ### Checkboxradio widget click to expand contents

  - Checkboxes
  - Radio buttons

- ### Collapsible (set) widget click to expand contents

  - Collapsible
  - Dynamic collapsibles
  - Collapsible set

- ### Controlgroup widget click to expand contents

  - Controlgroup
  - Dynamic controlgroups
- Datepicker

- ### Events click to expand contents

  - Swipe list items
  - Swipe page navigation
- Filterable widget
- Flipswitch widget

- ### Forms click to expand contents

  - Forms
  - Hide labels
  - Field containers
  - Forms disabled
  - Forms gallery

- ### Grids click to expand contents

  - Grids
  - Buttons in grids
  - Custom responsive grids
- Grouping and dividing content

- ### Icons click to expand contents

  - Icons
  - Grunticon loader

- ### Listview widget click to expand contents

  - Listview
  - Listview autocomplete
  - Listview autocomplete remote data
  - Listview autodividers linkbar
  - Listview autodividers selector
  - Nested Listviews
  - Listview collapsible list items (flat)
  - Listview collapsible list items (indented)
  - Listview responsive grid
- Loader widget
- Navbar widget

- ### Navigation click to expand contents

  - Navigation
  - Linking pages
  - Hash processing demo
  - Page Navigation Events

- ### Pages click to expand contents

  - Pages
  - Single page
  - Multi-page template
  - Dialog page

- ### Panel widget click to expand contents

  - Panel
  - External panels
  - Fixed panels
  - Panels responsive
  - Custom panel style
  - Panel open on swipe
  - Panel external and internal

- ### Popup widget click to expand contents

  - Popup
  - Popup alignment
  - Popup arrow size
  - Dynamic popups
  - Popups with iframes
  - Popup image scaling
  - Popup outside multi-page
- Rangeslider widget
- Responsive Web Design

- ### Selectmenu widget click to expand contents

  - Selectmenu
  - Custom select menu
  - Custom select menu with filter

- ### Slider widget click to expand contents

  - Slider
  - Slider flip toggle switch
  - Slider tooltip

- ### Table widget click to expand contents

  - Table Column Toggle
  - Table Column Toggle demo
  - Table Column Toggle heading groups
  - Table Column Toggle options
  - Table Reflow
  - Table Reflow heading groups
  - Table Reflow stripes and strokes
  - Table Reflow custom styles
- Tabs widget
- Textinput widget

- ### Theming click to expand contents

  - Default theme
  - Classic theme

- ### Toolbar widget click to expand contents

  - Toolbar
  - Dynamic toolbars
  - External toolbars
  - Fixed toolbars
  - Fullscreen toolbars
  - Fixed external toolbars
  - Persistent toolbars
  - Ajax optimized toolbars
  - Form in toolbar
- Transitions

- ### 3rd party API demos click to expand contents

  - Backbone RequireJS
  - Google Maps geolocation
  - Google Maps list toggle

- Home
- Introduction
- Buttons
- Button widget

- ### Checkboxradio widget click to expand contents

  - Checkboxes
  - Radio buttons

- ### Collapsible (set) widget click to expand contents

  - Collapsible
  - Dynamic collapsibles
  - Collapsible set

- ### Controlgroup widget click to expand contents

  - Controlgroup
  - Dynamic controlgroups
- Datepicker

- ### Events click to expand contents

  - Swipe list items
  - Swipe page navigation
- Filterable widget
- Flipswitch widget

- ### Forms click to expand contents

  - Forms
  - Hide labels
  - Field containers
  - Forms disabled
  - Forms gallery

- ### Grids click to expand contents

  - Grids
  - Buttons in grids
  - Custom responsive grids
- Grouping and dividing content

- ### Icons click to expand contents

  - Icons
  - Grunticon loader

- ### Listview widget click to expand contents

  - Listview
  - Listview autocomplete
  - Listview autocomplete remote data
  - Listview autodividers linkbar
  - Listview autodividers selector
  - Nested Listviews
  - Listview collapsible list items (flat)
  - Listview collapsible list items (indented)
  - Listview responsive grid
- Loader widget
- Navbar widget

- ### Navigation click to expand contents

  - Navigation
  - Linking pages
  - Hash processing demo
  - Page Navigation Events

- ### Pages click to expand contents

  - Pages
  - Single page
  - Multi-page template
  - Dialog page

- ### Panel widget click to expand contents

  - Panel
  - External panels
  - Fixed panels
  - Panels responsive
  - Custom panel style
  - Panel open on swipe
  - Panel external and internal

- ### Popup widget click to expand contents

  - Popup
  - Popup alignment
  - Popup arrow size
  - Dynamic popups
  - Popups with iframes
  - Popup image scaling
  - Popup outside multi-page
- Rangeslider widget
- Responsive Web Design

- ### Selectmenu widget click to expand contents

  - Selectmenu
  - Custom select menu
  - Custom select menu with filter

- ### Slider widget click to expand contents

  - Slider
  - Slider flip toggle switch
  - Slider tooltip

- ### Table widget click to expand contents

  - Table Column Toggle
  - Table Column Toggle demo
  - Table Column Toggle heading groups
  - Table Column Toggle options
  - Table Reflow
  - Table Reflow heading groups
  - Table Reflow stripes and strokes
  - Table Reflow custom styles
- Tabs widget
- Textinput widget

- ### Theming click to expand contents

  - Default theme
  - Classic theme

- ### Toolbar widget click to expand contents

  - Toolbar
  - Dynamic toolbars
  - External toolbars
  - Fixed toolbars
  - Fullscreen toolbars
  - Fixed external toolbars
  - Persistent toolbars
  - Ajax optimized toolbars
  - Form in toolbar
- Transitions

- ### 3rd party API demos click to expand contents

  - Backbone RequireJS
  - Google Maps geolocation
  - Google Maps list toggle