Some examples of Android PhoneGap Config Settings

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):

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)
loadingDialog - Display a native loading dialog when loading the app. Format for the value is "Title, Message"
loadingPageDialog - Display a native loading dialog when loading sub-pages. Format for the value is "Title, Message"
errorUrl - Set the error page for your application. Should be located in your Android project in file://android_asset/www/
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)
loadUrlTimeoutValue - How much time Cordova should wait before throwing a timeout error on the application.
keepRunning (boolean, defaults to true) - Determines whether Cordova will keep running in the background or not
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:

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:

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:

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.)

Raymond Camden