Styling PhoneGap Apps for the iPhone X

Description

With the release of the iPhone X, Apple introduced some significant changes to the footprint of the iPhone. One can safely speculate that future iPhones and possibly iPads will inherit many of the iPhone X design principles so it's prudent to understand how to properly use the iPhoneX display and to update your PhoneGap iOS apps to take advantage of it's new layout.

 The iPhone X Display

On the iPhone X, the display covers the entire surface area and precisely follows the curves of the design, all the way to the rounded corners.

There is no longer a physical Home button, it is now a single bar displayed at the bottom of the screen. In the image below, taken from the native iOS Yahoo Weather app, notice the transparent status bar and how it overlays the main view port. Also take notice of the white Home button bar at the bottom of the screen and the rounded corners instead of the squared off corners used on earlier iPhones.

There is a lot to consider to get the styling right for your Alpha Anywhere iOS PhoneGap apps on the iPhone X and this article describes the steps required to make that happen.

The "notch" incorporates the camera and sensor array which intersects the traditional status bar.

IMPORTANT: Your PhoneGap application must include the Status Bar plugin, you MUST use PhoneGap CLI-8.0.0 or CLI-7.x.x with Build type 2 and you MUST generate Storyboard launch images to implement the iPhone X styling.

 Default styling, a letterboxed app

A PhoneGap app that looks great on an iPhone 6 is going to be letterboxed in the WebView of a PhoneGap app. Here's a photo of the Project Punch List App on the iPhone 6 and the iPhone X

PhoneGap App displayed on an iPhone 6 and iPhone X with standard styling

 Display The App Full Screen on the iPhone X

There are a number of steps required to properly display a PhoneGap app on an iPhone X. Step 1 is to bring the app full screen.

Use a Storyboard for the launch image (splashscreen): To fill the iPhone X screen, you must create your launch image with a storyboard. This option is set in the PhoneGap App Builder genie. You only need to supply 1 image, the portrait image. It should be 2732 px x 2732 px and center weighted.

Generate storyboard launch images

Use PhoneGap cli-8.0.0: Storyboards are best supported in PhoneGap version cli-8.0.0. You can also use any of the PhoneGap cli-7.x.x versions but you MUST specify build type 2

Set the PhoneGap version to cli-8.0.0

Add viewport-fit=cover value to the viewport meta tag: As of late April 2018, this meta tag is added by default. If you are updating a previously built PhoneGap app make sure to select Generate PhoneGap Asset Files when rebuilding your app within the PhoneGap App Builder. Assuming you are using a current release, the viewport-fit=cover property will be automatically added to the viewport meta tag.

If upgrading a previous app, make sure to generate PhoneGap asset files
Viewport meta tag must include viewport-fit=cover
iPhone X with viewport meta tag set to viewport-fit=cover

Much better, now the app will fill the iPhone X screen however, the status bar and the footer margin need adjustment. The white opaque status bar with dark text is not consistent with the dark app design and the panel card footer overcomes the display area while the button in the footer rests behind the home button.

 Add Required Padding To Top And Bottom Containers

When Apple released iOS 11, support was added for a new env() CSS function and four new WebKit variables (safe-area-inset-left, -right, -top, -bottom) were added to define the "safe area" perimeters on the iPhone X. This means you don't have to guess at the required padding to accommodate the status bar at the top or the home button at the bottom of the screen. If your app supports landscape mode, you also have to be concerned with the left and right padding because the iPhone X "notch" could be on the left or right side, depending upon how the user is holding the device.

Listed below are the CSS classes that have been added to the components local CSS definition. These classes could be added to the component Panel Card header or footer but in the case of the Project Punch List app, both classes were added to the Panel Navigator.

In the code below, @supports(padding: max(0px) determines if the WebView supports the new CSS max function, which returns the max value of the included parameters. If max() is supported then the left and right padding will be the max value of 10px or env(safe-area-inset-left, -right). This allows you to specify some padding if it's required for your app.

Local CSS for iPhone X styling

 Styling the Status Bar With The Status Bar Plugin

For the Project Punch List app, the status bar is set to not overlay the WebView, it will appear positioned above the WebView. The status bar background is set to dark with light text. This is set in the client side onPhoneGapReady event. Once the status bar is properly configured, a resizePanel() function is called. The resizePanel() function is also called in the onOrientationChange event. You can explore all of this code in the UX iPhoneXStyling template described later in this document.

onPhoneGapReady event, set the status bar properties
The JavaScript resizePanel function
iPhone X with status bar properties and padding set

 The iPhoneXStyling UX Template

A new UX template has been included in Alpha Anywhere that includes styling for the iPhoneX and demonstrates the numerous settings of the Status Bar Plugin.

Make sure to look at the components Local CSS definition and the JavaScript functions to gain a thorough understanding of the components styling and functionality.

iPhone X Status Bar Overlays The WebView, Black Text

iPhone X Status Bar Overlays The WebView, Black Text

iPhone X Status Bar Overlays The WebView, White Text

iPhone X Status Bar Overlays The WebView, White Text

iPhone X Status Bar Does Not Overlay The WebView, Background Set To Red, Black Text

iPhone X Status Bar Does Not Overlay The WebView, Background Set To Red, Black Text

iPhone X Status Bar Off

iPhone X Status Bar Off

iPhone X Landscape Mode

iPhone X Landscape Mode