Take Complete Control of the iOS Status Bar with PhoneGap Build



·

The status bar is the little horizontal bar at the top of an iDevice that displays network connectivity, time, battery and so on. By default a Sencha Touch application packaged with PhoneGap Build will just inherit the native behaviour of the iOS status bar. In the most recent iOS updates the default behaviour of the status bar changed, which would cause it to overlay our applications rather than being separated from the application entirely. This caused a problem where Sencha Touch was not taking this change into account and if we were to have a toolbar with buttons at the top of the application, the status bar elements would overlay parts of our interface.

The community quickly provided a few workarounds to this, my favourite being to include the following code:

if (Ext.os.is.iOS && Ext.os.version.major >= 7) {
Ext.select(".x-toolbar").applyStyles("height: 62px; padding-top: 15px;");
}

My apologies to the creator of this fix, I like to give credit but I can’t track down who I got this from.

This code uses Sencha Touch’s ‘Ext.os‘ to see if it is being run on an iOS device with an iOS version of 7 or later. If it is then we take the status bar change into account by applying some padding to the top of the toolbar.

In some circumstances, we may not necessarily like this default behaviour of the status bar. Perhaps you want your application to occupy the entire screen or want the the status bar to be a certain colour and be separate to your application (in this case, it wouldn’t be necessary to include the fix above). I’m going to walk through a few examples of how to control the status bar by using the StatusBar plugin for PhoneGap Build.

Getting Started

First we will have to make the plugin available to use within our project. To do this, simply add the following line to your config.xml file:

<gap:plugin name="com.phonegap.plugin.statusbar" version="1.1.0" />

There’s quite a few methods that we have access to after including this, here’s a summary of what we can do:

StatusBar.overlaysWebView – can not be used with PhoneGap Build

Can be set to true or false and controls whether or not the statusbar overlays the WebView:

StatusBar.overlaysWebView(true);

StatusBar.styleDefault

Uses the default style which is dark text on a light background:

StatusBar.styleDefault()

StatusBar.styleLightContent

The opposite of the above, uses light text on a dark backround:

StatusBar.styleLightContent()

StatusBar.styleBlackTranslucent
Also uses light text but makes the status bar overlay the content and is somewhat see through:

StatusBar.styleBlackTranslucent

StatusBar.styleBlackOpaque
A solid black background with white text:

StatusBar.styleBlackOpaque()

StatusBar.backgroundColorByName
Can be used only when overlaysWebView is set to false. You can set the background color by:

StatusBar.backgroundColorByName("red")

with any of the following colors:

black, darkGray, lightGray, white, gray, red, green, blue, cyan, yellow, magenta, orange, purple, brown, clear

StatusBar.backgroundColorByHexString

Same as above but allows the use of a hex string:

StatusBar.backgroundColorByHexString("#cecece");

StatusBar.hide

Hides the status bar:

StatusBar.hide()

StatusBar.show:

Shows the status bar

StatusBar.show()

An example

Let’s say you want to have the status bar hidden during the application startup (whilst the splash screen is showing) but then display a purple status bar that has white text and is separated from the application. To do this we would start by including the following in the config.xml to hide the status bar entirely:

    <gap:config-file platform="ios" parent="UIStatusBarHidden">
        <true/>
    </gap:config-file>

    <gap:config-file platform="ios" parent="UIViewControllerBasedStatusBarAppearance">
        <false/>
    </gap:config-file>

Now in our applications launch() function, or the equivalent ‘deviceReady’ function if you are not using Sencha Touch, we place some additional code to display the status bar again and change the styling:

StatusBar.show();
StatusBar.overlaysWebView(false);
StatusBar.styleLightContent();
StatusBar.backgroundColorByHexString("#1f1e2e");

As you can see we’re telling it to show the status bar again, not overlay the web view, change the text to white by specifying “light content” and then changing the background color to the specified hex value.

A Strange Quirk With InAppBrowser

If you’re using the Inappbrowser plugin and trying to implement the example above you are going to run into some trouble. After you launch the in app browser from within your application and then close it, your status bar will disappear! Since we’re using PhoneGap Build we can’t do much about editing the plugin directly (although there is a fix that is available for this is you’re maintaining a local PhoneGap project). At this stage I haven’t managed to find a way to work around this, so if you have any ideas post them in the comments below!

What to watch next...