From 57d41c29247d70c8062f1ee2efe23c2841c924ef Mon Sep 17 00:00:00 2001 From: xster Date: Tue, 19 Nov 2019 18:15:18 -0800 Subject: [PATCH] Add an add-to-app landing page (#3265) --- src/_data/sidenav.yml | 2 + .../android/add-flutter-fragment.md | 38 ++++---- .../development/add-to-app/android/index.md | 4 + src/docs/development/add-to-app/index.md | 93 ++++++++++++++++++- src/docs/development/add-to-app/ios/index.md | 4 + 5 files changed, 120 insertions(+), 21 deletions(-) create mode 100644 src/docs/development/add-to-app/android/index.md create mode 100644 src/docs/development/add-to-app/ios/index.md diff --git a/src/_data/sidenav.yml b/src/_data/sidenav.yml index e6116c1b37..5a5a1bcb90 100644 --- a/src/_data/sidenav.yml +++ b/src/_data/sidenav.yml @@ -147,6 +147,8 @@ - title: Add Flutter to existing app permalink: /docs/development/add-to-app children: + - title: Introduction + permalink: /docs/development/add-to-app - title: Adding to an Android app permalink: /docs/development/add-to-app/android children: diff --git a/src/docs/development/add-to-app/android/add-flutter-fragment.md b/src/docs/development/add-to-app/android/add-flutter-fragment.md index 54f1456348..5cbe06463a 100644 --- a/src/docs/development/add-to-app/android/add-flutter-fragment.md +++ b/src/docs/development/add-to-app/android/add-flutter-fragment.md @@ -64,11 +64,11 @@ public class MyActivity extends FragmentActivity { super.onCreate(savedInstanceState); // Inflate a layout that has a container for your FlutterFragment. For - // this example, assume that a FrameLayout exists with an ID of + // this example, assume that a FrameLayout exists with an ID of // R.id.fragment_container. setContentView(R.layout.my_activity_layout); - // Get a reference to the Activity's FragmentManager to add a new + // Get a reference to the Activity's FragmentManager to add a new // FlutterFragment, or find an existing one. FragmentManager fragmentManager = getSupportFragmentManager(); @@ -80,12 +80,12 @@ public class MyActivity extends FragmentActivity { // Create and attach a FlutterFragment if one does not yet exist. if (flutterFragment == null) { flutterFragment = FlutterFragment.createDefault(); - + fragmentManager .beginTransaction() .add( - R.id.fragment_container, - flutterFragment, + R.id.fragment_container, + flutterFragment, TAG_FLUTTER_FRAGMENT ) .commit(); @@ -96,9 +96,9 @@ public class MyActivity extends FragmentActivity { The above code is sufficient to render a Flutter UI that begins with a call to your `main()` Dart entrypoint, an initial Flutter route of `/`, and a new -`FlutterEngine`. However, this code is not sufficient to achieve all expected -Flutter behavior. Flutter depends on various OS signals that need to be -forwarded from your host `Activity` to `FlutterFragment`. These calls are shown +`FlutterEngine`. However, this code is not sufficient to achieve all expected +Flutter behavior. Flutter depends on various OS signals that need to be +forwarded from your host `Activity` to `FlutterFragment`. These calls are shown below: ```java @@ -121,13 +121,13 @@ public class MyActivity extends FragmentActivity { @Override public void onRequestPermissionsResult( - int requestCode, - @NonNull String[] permissions, + int requestCode, + @NonNull String[] permissions, @NonNull int[] grantResults ) { flutterFragment.onRequestPermissionsResult( - requestCode, - permissions, + requestCode, + permissions, grantResults ); } @@ -306,7 +306,7 @@ For this reason, Flutter supports translucency in a `FlutterFragment`. below and above your Flutter experience, then you must specify a `RenderMode` of `texture`. See the previous section titled "Control `FlutterFragment`'s render mode" for information on controlling the - `RenderMode`. + `RenderMode`. {{site.alert.end}} To enable transparency for a `FlutterFragment`, build it with the following @@ -331,8 +331,8 @@ would be reasonable for a `Fragment` to control system chrome like Android's status bar, navigation bar, and orientation. {% asset -development/add-to-app/android/add-flutter-fragment/add-flutter-fragment_fullscreen.png -class="mw-100" alt="Fullscreen Flutter" %} + development/add-to-app/android/add-flutter-fragment/add-flutter-fragment_fullscreen.png + class="mw-100" alt="Fullscreen Flutter" %} In other apps, `Fragment`s are used to represent only a portion of a UI. A `FlutterFragment` might be used to implement the inside of a drawer, or a video @@ -341,13 +341,13 @@ player, or a single card. In these situations, it would be inappropriate for the pieces within the same `Window`. {% asset -development/add-to-app/android/add-flutter-fragment/add-flutter-fragment_partial-ui.png -class="mw-100" alt="Flutter as Partial UI" %} + development/add-to-app/android/add-flutter-fragment/add-flutter-fragment_partial-ui.png + class="mw-100" alt="Flutter as Partial UI" %} `FlutterFragment` comes with a concept that helps differentiate between the case where a `FlutterFragment` should be able to control its host `Activity`, and the cases where a `FlutterFragment` should only affect its own behavior. To prevent -a `FlutterFragment` from exposing its `Activity` to Flutter plugins, and to +a `FlutterFragment` from exposing its `Activity` to Flutter plugins, and to prevent Flutter from controlling the `Activity`'s system UI, use the `shouldAttachEngineToActivity()` method in `FlutterFragment`'s `Builder` as shown below. @@ -370,6 +370,6 @@ value is `true`, which allows Flutter and Flutter plugins to interact with the surrounding `Activity`. {{site.alert.note}} - Some plugins may expect or require an `Activity` reference. Ensure that none + Some plugins may expect or require an `Activity` reference. Ensure that none of your plugins require an `Activity` before disabling access. {{site.alert.end}} \ No newline at end of file diff --git a/src/docs/development/add-to-app/android/index.md b/src/docs/development/add-to-app/android/index.md new file mode 100644 index 0000000000..a18424a682 --- /dev/null +++ b/src/docs/development/add-to-app/android/index.md @@ -0,0 +1,4 @@ +--- +layout: toc +title: Adding Flutter to Android +--- diff --git a/src/docs/development/add-to-app/index.md b/src/docs/development/add-to-app/index.md index 2760376633..96fa34a536 100644 --- a/src/docs/development/add-to-app/index.md +++ b/src/docs/development/add-to-app/index.md @@ -1,4 +1,93 @@ --- -layout: toc -title: Add to existing app +title: Add Flutter to existing app +description: Adding Flutter as a library to an existing Android or iOS app. --- + +## Add-to-app + +It's sometimes not practical to rewrite your entire application in Flutter all +at once. For those situations, Flutter can be integrated into your existing +application in a piecemeal fashion as a library or module. That module can then +be imported into your Android or iOS (currently supported platforms) app to +render a part of your app's UI in Flutter. Or just to run shared Dart logic. + +In a few steps, you can also bring the productivity and the expressiveness of +Flutter into your own app. + +TODO(xster): add steps overview videos. + +As of Flutter release v1.12, add-to-app is supported for basic scenarios with +the _**following limitations**_: + +- One fullscreen Flutter instance at a time. Running multiple Flutter instances +or in partial screen views may have undefined behaviors. +- Using Flutter in background mode is still WIP. +- Packing a Flutter library into another sharable library or packing multiple +Flutter libraries into an application is not currently supported + +## Supported features + +### Add to Android applications + +- Auto-build and import the Flutter module by adding a Flutter SDK hook to + your Gradle script; or +- Build your Flutter module into a generic [Android AAR](https://developer.android.com/studio/projects/android-library) +- Android Studio Android/Flutter co-editing and module creation/import wizard +- Java and Kotlin host apps supported + +### Add to iOS applications +- Auto-build and import the Flutter module by adding a Flutter SDK hook to + your CocoaPods and to your Xcode build phase; or +- Build your Flutter module into a generic [iOS Framework](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html) +- Objective-C and Swift host apps supported + +### Android and iOS +- Flutter modules can use [Flutter plugins](https://pub.dev/flutter) to interact + with the platform +- Flutter modules support Stateful Hot Reload by using `flutter attach` from + IDEs or the command line to connect to an app containing Flutter + +See our [add-to-app GitHub Samples repository](https://github.com/flutter/samples/tree/master/experimental/add_to_app) +for sample projects in Android and iOS that import a Flutter module for UI. + +## Get started + +To get started, see our project integration guide for + +
+ +
+
+ Android +
+
+ + +
+
+ iOS +
+
+ +
+ +## API usage + +Once Flutter has been integrated into your project, see our API usage guides for + +
+ +
+
+ Android +
+
+ + +
+
+ iOS +
+
+ +
diff --git a/src/docs/development/add-to-app/ios/index.md b/src/docs/development/add-to-app/ios/index.md new file mode 100644 index 0000000000..622fbfa545 --- /dev/null +++ b/src/docs/development/add-to-app/ios/index.md @@ -0,0 +1,4 @@ +--- +layout: toc +title: Adding Flutter to iOS +---