Styling Cordova 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 Cordova 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.

images/iphonex/iPhoneX_perspective.png

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 Cordova apps on the iPhone X and this article describes the steps required to make that happen.

images/iphonex/sbar_overlays_app_iPhoneX.png
images/iphonex/iPhoneX_sensor_array.png

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

IMPORTANT: Your Cordova application must include the Status Bar plugin, you MUST use 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 Cordova app that looks great on an iPhone 6 is going to be letterboxed in the WebView of a Cordova app. Here's a photo of the Project Punch List App on the iPhone 6 and the iPhone X

images/iphonex/iPhone6_X_composite.png
Cordova 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 Cordova 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 Cordova App Builder genie. You only need to supply 1 image, the portrait image. It should be 2732 px x 2732 px and center weighted.

images/iphonex/set_phonegap_image_options.png
Generate storyboard launch images

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

images/iphonex/PhoneGap_cli_version.png
Set the Cordova 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 Cordova app make sure to select Generate Cordova Asset Files when rebuilding your app within the Cordova App Builder. Assuming you are using a current release, the viewport-fit=cover property will be automatically added to the viewport meta tag.

images/iphonex/gen_asset_files.png
If upgrading a previous app, make sure to generate Cordova asset files
images/iphonex/viewport_tag.png
Viewport meta tag must include viewport-fit=cover
images/iphonex/sbar_ppl_2.png
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.

images/iphonex/localCSS.png
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.

images/iphonex/onPhoneGapReady.png
onPhoneGapReady event, set the status bar properties
images/iphonex/resizePanel.png
The JavaScript resizePanel function
images/iphonex/sbar_ppl_3.png
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

images/iphonex/sbar_iphonex_overlay_sbar_on_black_text_800.png
iPhone X Status Bar Overlays The WebView, Black Text

iPhone X Status Bar Overlays The WebView, White Text

images/iphonex/sbar_iphonex_overlay_sbar_on_white_text_800.png
iPhone X Status Bar Overlays The WebView, White Text

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

images/iphonex/sbar_iphonex_overlay_off_sbar_on_red_bg_black_text_800.png
iPhone X Status Bar Does Not Overlay The WebView, Background Set To Red, Black Text

iPhone X Status Bar Off

images/iphonex/sbar_iphonex_overlay_sbar_off_800.png
iPhone X Status Bar Off

iPhone X Landscape Mode

images/iphonex/sbar_iphonex_landscape_mode_800.png
iPhone X Landscape Mode