From 5cd8c16cbd0d3cbe13a100ec947252f2c2f0d246 Mon Sep 17 00:00:00 2001 From: Kevin Strider Date: Mon, 16 May 2022 04:22:34 -0700 Subject: [PATCH] intro.mdx (Creating Plugins - Building an Android Plugin) Summary: Restyle of page, including changes to spelling, grammar, links, and structure (where relevant). Reviewed By: aigoncharov Differential Revision: D36378263 fbshipit-source-id: 80a59bbb3386abc620a0fde848ccf8e96c287c6c --- docs/tutorial/android.mdx | 68 ++++++++++++++++----------------------- 1 file changed, 28 insertions(+), 40 deletions(-) diff --git a/docs/tutorial/android.mdx b/docs/tutorial/android.mdx index 2f93df28c..5daec0cc5 100644 --- a/docs/tutorial/android.mdx +++ b/docs/tutorial/android.mdx @@ -6,40 +6,35 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; Android Tutorial App -For the purpose of the tutorial, we will assume you already have an existing -Android application in which you have a feed or list of items. As the Flipper -team, we obviously concern ourselves mostly with sea mammals, so this is what -our app displays. The actual display logic is not what's interesting here, -but how we can make this data available in our Flipper desktop app. +For the purpose of the tutorial, it's assumed you already have an existing Android application in which you have a feed or list of items. -Part of what makes Flipper so useful is allowing users to inspect the -internals of their app. In this case, we'd like to see the specific -sea mammal data the app is handling, so let's write a plugin to make that -easy. +Part of what makes Flipper so useful is allowing users to inspect the internals of their app. This part of the tutorial is concerned with how to make data available to the Flipper desktop app, which, for the sake of this tutorial, is called 'Sea-mammals' (an app based on sea mammals). -You can find the source code of the project [on GitHub]( -https://github.com/facebook/flipper/tree/7dae5771d96ea76b75796d3b3a2c78746e581e3f/android/tutorial). +:::note +You can find the source code for this tutorial on [GitHub](https://github.com/facebook/flipper/tree/7dae5771d96ea76b75796d3b3a2c78746e581e3f/android/tutorial). +::: ## Creating a Plugin +
-[FB-Only] Depending the options selected during scaffolding (see intro), some of the following code might already have been generated by `scarf`. +[FB-Only] Depending the options selected during scaffolding (see the [introduction](intro.mdx) page), some of the following code might already have been generated by `scarf`.
+ -On Android, a Flipper plugin is a class that implements the -[`FlipperPlugin`](https://github.com/facebook/flipper/blob/main/android/src/main/java/com/facebook/flipper/core/FlipperPlugin.java) +On Android, a Flipper plugin is a class that implements the [FlipperPlugin](https://github.com/facebook/flipper/blob/main/android/src/main/java/com/facebook/flipper/core/FlipperPlugin.java) interface. -The interface is rather small and only comprises four methods: +The interface consists of the following four methods: -- `getId() -> String`: Specify a unique string so the JavaScript side knows where to talk to. This must match the name attribute in the `package.json` we will look into later in this tutorial. -- `onConnect(FlipperConnection)`: This method is called when the desktop app connects to the mobile client and is ready to receive or send data. -- `onDisconnect()`: We're sure you can figure this one out. -- `runInBackground() -> Boolean`: Unless this is true, only the currently selected plugin in the Flipper UI can communicate with the device. +- `getId() -> String` - specify a unique string so the JavaScript side knows where to talk to. This must match the name attribute in the `package.json`, which is examined later in this tutorial. +- `onConnect(FlipperConnection)` - this method is called when the desktop app connects to the mobile client and is ready to receive or send data. +- `onDisconnect()` - sets the connection to nil. +- `runInBackground() -> Boolean` - unless this is true, only the currently selected plugin in the Flipper UI can communicate with the device. -Let's implement these methods for our sealife app: +The following code shows the implementation of these methods for the Sea-mammals app: ```kotlin import com.facebook.flipper.core.FlipperConnection @@ -76,26 +71,20 @@ class SeaMammalFlipperPlugin : FlipperPlugin { ``` *See [SeaMammalFlipperPlugin.kt](https://github.com/facebook/flipper/blob/5afb148ffa9e267e5b24e0dfae198d1cf46cc396/android/tutorial/src/main/java/com/facebook/flipper/sample/tutorial/plugin/SeaMammalFlipperPlugin.kt)* -The two interesting bits here are `onConnect` and `newRow`. `newRow` sends a message -to the desktop app and is identified with the same name "newRow". +The two interesting items here are `onConnect` and `newRow`, which sends a message to the desktop app and is identified with the same name 'newRow'. -For our sample app, we're dealing with a static data source. However, in real -life, you will likely dynamically receive new data as the user interacts with -the app. So while we just send all the data we have at once in `onConnect`, -you would normally set up a listener here to instead call `newRow` as new data -arrives. +For the sea-mammals app, there is a static data source. However, in real life, you'll likely dynamically receive new data as the user interacts with the app. So, while in the Sea-mammals app, the data is sent all at once with `onConnect`, in real life, you'd set up a listener to call `newRow` as new data arrives. -You may have noticed that we don't just send random `Object`s over the wire but -use `FlipperObject`s instead. What are they? A `FlipperObject` works similar -to a JSON dictionary and has a limited set of supported types like strings, -integers and arrays. Before sending an object from your native app to the -desktop, you first need to break it down into `FlipperObject`-serializable parts. +You may have notices that rather than sending random `Object`s over the wire, `FlipperObject`s are used. +A `FlipperObject` works similar to a JSON dictionary and has a limited set of supported types like strings, integers and arrays. -## Registering your Plugin +:::note +Before sending an object from your native app to the desktop, you first need to break it down into `FlipperObject`-serializable parts. +::: -Now all you need to do is let Flipper know about your new plugin. You do this -by calling `addPlugin` on your `FlipperClient`, which is normally created -at application startup. +## Registering your plugin + +Now, all you need to do is let Flipper know about your new plugin. You do this by calling `addPlugin` on your `FlipperClient`, which is normally created at application startup. ```kotlin val flipperClient = AndroidFlipperClient.getInstance(this) @@ -105,8 +94,7 @@ flipperClient.start() ``` *See [`TutorialApplication.kt`](https://github.com/facebook/flipper/blob/5afb148ffa9e267e5b24e0dfae198d1cf46cc396/android/tutorial/src/main/java/com/facebook/flipper/sample/tutorial/TutorialApplication.kt)* -## What next +## Next step -When starting your application now, Flipper will tell the desktop application -about the plugin it supports, including "sea-mammals" and will look for a -corresponding JavaScript plugin by that name. Let's build that next. +When starting your application, Flipper tells the desktop application about the plugin it supports (including 'Sea-mammals') and looks for a corresponding JavaScript plugin by that name. +The next step is to [build that JavaScript plugin](javascript.mdx).