Twitter: raymondcamden


Address: Lafayette, LA, USA

Some examples of Android PhoneGap Config Settings

02-19-2013 21,713 views Mobile 6 Comments

One thing I don't really play a lot with are config.xml files on Android. The config.xml file is a powerful way to specify settings like icons, splash screens, and the like. You can find the high level docs for this feature here: Project Settings. A few days ago Simon MacDonald wrote up some details about new Android features and specifically called out another blog post by Joe Bowser about new config.xml settings for Android: What else is new in Cordova Android 2.4.0

I took this as an opportunity to really look at the Android-specific config.xml settings. You can see this list below (taken from the docs):

  1. useBrowserHistory (boolean, defaults to true) - set to false if you want to use the history shim that was used to work around the hashtag error present in Android 3.x prior to the history fix. (Note: This setting will be deprecated in April 2013)

  2. loadingDialog - Display a native loading dialog when loading the app. Format for the value is "Title, Message"

  3. loadingPageDialog - Display a native loading dialog when loading sub-pages. Format for the value is "Title, Message"

  4. errorUrl - Set the error page for your application. Should be located in your Android project in file://android_asset/www/

  5. backgroundColor - Set the background color for your application. Supports a four-byte hex value, with the first byte representing alpha value, and the following three bytes with standard RGB values. (i.e. 0x00000000 = Black)

  6. loadUrlTimeoutValue - How much time Cordova should wait before throwing a timeout error on the application.

  7. keepRunning (boolean, defaults to true) - Determines whether Cordova will keep running in the background or not

  8. splashscreen - The name of the file minus its extension in the res/drawable directory. If you have multiple assets, they all must share this common name in their respective directories.

Some of these made sense to me, and some made sense but I had never actually seen them in action. I played a bit with them and took some screen shots I thought I'd share with my readers.

loadingDialog

As the docs specify, you literally use a "Title, Message" format. Ie: <preference name="loadingDialog" value="Raymond, Was Here" />

And here it is in action...

loadingPageDialog

I assumed this would fire between page loads, but I never saw this actually display. Maybe it only shows up if a page takes more than N seconds to load. I'm just throwing this out there in case anyone can confirm it actually works.

errorUrl

The docs say it should be located in file://android_asset/www/. So I made a file, error.html, and tried this:

<preference name="errorUrl" value="error.html" />

But that doesn't work. You need to use a file-based URL. Maybe that's assumed by the docs, but it wasn't clear to me. This is what works:

<preference name="errorUrl" value="file:///android_asset/www/error.html" />

I mentioned to Simon that this setting seems a bit extreme. I mean, why would I link to and use the wrong URL, but certainly in a "real" application with some size in it this would be possible.

backgroundColor

Yep, works fine, but only if you don't forget the first value is alpha and accidentally leave it at 0. Here is an example:

<preference name="backgroundColor" value="0xff38c0f4" />

And the result:

splashscreen

I had two issues with this, both of which Joe helped me understand. First, why would you use this versus the gap:splash stuff you see documented at PhoneGap Build? Well, mainly because the gap:splash stuff is PhoneGap Build only. The splashscreen setting will work fine without Build. Secondly, you still have to get into the Java code to actually have this show up. Joe discusses this in a comment to me and it is relatively simple to implement. (And as he points out, soon we should able to skip editing the Java as well.)

6 Comments

  • maddom73 #
    Commented on 03-01-2013 at 5:38 PM
    Hi,
    I'm developing an android app using phonegap 2.4.0 and jquery mobile 1.3.0. I've got some problems to stream youtube videos: in fullscreen mode the app crashes. I use iframe to embed videos and I can't manage to find any good solutions around the web. Can you help me?
  • Commented on 03-02-2013 at 9:49 AM
    Nothing really comes to mind. You could try the InAppBrowser instead.
  • abhisek armasha #
    Commented on 05-01-2013 at 7:28 AM
    for videos I am using Open in new window..child browser.

    [Deleted by Raymond Camden]
  • Commented on 05-01-2013 at 8:39 AM
    Abhisek, in the future, please post a Gist or Pastebin link. I've edited your comment as it was 99% code.
  • Navjot Singh #
    Commented on 05-29-2013 at 2:37 AM
    Hi Raymond,

    This is a good article, with demo example(loadingDialog). But when i used it in my android config.xml file but doesn't work for me. I want to know that how can i call it in code or it's working by default.
  • Commented on 05-29-2013 at 9:06 AM
    Um, so, what? Not sure I understand you.

Post Reply

Please refrain from posting large blocks of code as a comment. Use Pastebin or Gists instead. Text wrapped in asterisks (*) will be bold and text wrapped in underscores (_) will be italicized.

Leave this field empty