Migration Guide v2.8

This article provides information to assist users in migrating Trigger.IO Forge apps from v2.7.x of the platform to v2.8.x.

Early Access Beta Release

Welcome to the early access release of Forge platform v2.8.

This guide is a work in progress and will be continuously updated as we move closer to the final v2.8 release in Q4 2019.

Please join us on the Forge 2.8 Community Forum Topic if you have any questions around the update process or run into any difficulties!

Introduction

If your application is currently built against v2.7.x of the Forge platform it is important that you migrate to v2.8.x so that your application will continue to run on the latest Android "Q" and iOS 13 releases.

The full changelog for this release can be found in the Release Notes.

The major changes you need to be aware of are:

  1. UIWebView is no longer supported and has been replaced by WKWebview.
  2. iOS core.ios.adjust_content_insets has been deprecated in favor of using viewport-fit=auto | cover directly from CSS
  3. Android core.android.adjust_content_insets has been renamed to core.android.viewport_fit = auto | cover until we can support it directly from CSS.
  4. The httpd module has been integrated directly into ForgeCore.
  5. Modules that need to be updated to the latest versions are:
    • bolts 1.9.0
    • parse 3.1
    • file 2.24
    • capture 2.24
    • media 2.7
    • urlhandler 2.2
    • oauth 1.0
    • permissions 2.1
    • tabs 3.1
  6. The following modules have been deprecated and are no longer supported:
    • camera
    • kumulos
    • httpd (moved into ForgeCore)
    • tribr_multi_image_select (renamed to gallery)

Let's take a detailed look at the steps needed to update your app for Forge Platform v2.8:

Step 0: Install Xcode 11

Step 1: update to v2.8

Edit your app's src/config.json file and set:

platform_version: "v2.8.0"

Step 2: update modules

Edit your app's src/config.json file and, for the modules you use, update as follows:

httpd

  • remove the module configuration (the httpd module is now built into the Forge runtime by default)
  • (optional) overriding the default port (44300) can now be performed by setting core.general.httpd.port
  • (optional) remove any https://localhost/* or http://localhost/* patterns from core.general.trusted_urls

bolts

  • update to "version": "1.9.0"

parse

  • update to "version": "3.1"

file

  • update to "version": "2.24"

capture

  • update to "version": "2.24"

media

  • update to "version": "2.7"

urlhandler

  • update to "version": "2.2"

oauth

  • update to "version": "1.0"

permissions

  • update to "version": "2.1"

share

  • update to "version": "1.3"

tabs

  • update to "version": "3.1"
  • iOS has switched from UIWebView to WKWebView which means you may want to spend some time testing to make sure your content still renders and behaves the same way.

tribr_multi_image_select

  • Rename this module to gallery
  • Update to "version": "2.0"

Step 3: update deprecated flags, config fields and methods:

src/config.json flags

  • Remove ios_force_wkwebview as it is no longer supported.
  • Remove ios_disable_iphone_xr_running_ios12_1_2_tabbar_bug_workaround as it is no longer supported.
  • Rename any usages of migrate_web_storage_for_webview to ios_migrate_web_storage_for_webview

javascript methods

  • forge.layout.setContentInsetAdjustmentBehavior is no longer supported.

Step 4: (optional) update safe area inset support

Previous versions of Forge used the core.android.adjust_content_insets and core.ios.adjust_content_insets configuration fields to control layout behaviour for apps running on devices with a notched display.

These configuration fields have now been deprecated as we move closer to being able to support standard HTML/CSS behaviours.

iOS

On iOS we've done away with them entirely and are finally able to fully support standard HTML/CSS setups such as:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta name="viewport" content="viewport-fit=cover">
        <style type="text/css">
            body {
                padding-top: env(safe-area-inset-top);
                padding-left: env(safe-area-inset-left);
                padding-bottom: env(safe-area-inset-bottom);
                padding-right: env(safe-area-inset-right);
            }
        </style>
        ...

Android

The Android WebView unfortunately still does not expose the internal WebKit API's required to override the safe-area-inset-* CSS properties.

Until we are able to fully support these, we have to "fake it" by moving the viewport tag to src/config.json and using CSS var variables instead of env environment variables.

The equivalent setup to the iOS code would therefore be:

src/config.json

"core" {
    "android" {
        "viewport_fit": "auto"
    }
}

html/css

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta name="viewport" content="viewport-fit=cover">
        <style type="text/css">
            body {
                padding-top: var(--safe-area-inset-top);
                padding-left: var(--safe-area-inset-left);
                padding-bottom: var(--safe-area-inset-bottom);
                padding-right: var(--safe-area-inset-right);
            }
        </style>
        ...

Important: You may run into a conflict between the env vs the var rules if you are targeting both iOS and Android from the same CSS.


One workaround is to set the ios_also_set_css_safe_area_inset_env_as_var flag which will also allow you to use the Android var variables on iOS.


src/config.json file:


flags {
    "ios_also_set_css_safe_area_inset_env_as_var": true
}


html/css files:


body {
    padding-top: var(--safe-area-inset-top);
    padding-left: var(--safe-area-inset-left);
    padding-bottom: var(--safe-area-inset-bottom);
    padding-right: var(--safe-area-inset-right);
}