jens/flipper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

create-plugin.mdx (Creating Plugins - Client Plugin API)

Browse Source 
Summary: Restyle of page, including changes to spelling, grammar, links, and structure (where relevant).

Reviewed By: aigoncharov

Differential Revision: D36626315

fbshipit-source-id: 735160f8d1f1365a8aab7fb1cd3e99b724025e3a
This commit is contained in:
Kevin Strider
2022-05-25 03:14:14 -07:00
committed by Facebook GitHub Bot
parent 669bc74acd
commit b8292ee62c
1 changed files with 28 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/extending/create-plugin.mdx
View File

@@ -9,12 +9,12 @@ import {FbInternalOnly, OssOnly} from 'internaldocs-fb-helpers';
## FlipperPlugin ## FlipperPlugin
The plugin implementation that runs on the (mobile) application side of things is called the _client plugin_ in Flipper terminology. The plugin implementation that runs on (mobile) applications is called the *client plugin* in Flipper terminology.
To build a client plugin, implement the `FlipperPlugin` interface. To build a client plugin, implement the `FlipperPlugin` interface.
The ID that is returned from your implementation needs to match the `name` defined in your JavaScript counterpart's `package.json`. The ID that is returned from your implementation needs to match the `name` defined in your JavaScript counterpart's `package.json`.
<Tabs defaultValue="android" values={[{label: 'Android', value: 'android'}, { label: 'iOS', value: 'ios'}, { label: 'C++', value: 'cpp'}, { label: 'React Native (JS)', value: 'rn' }, { label: 'React (JS)', value: 'js' }]}> <Tabs defaultValue="android" values={[{label: 'Android', value: 'android'}, { label: 'iOS', value: 'ios'}, { label: 'C++', value: 'cpp'}, { label: 'React Native (JS)', value: 'rn' }, { label: 'React (JS)', value: 'js' }]}>
<TabItem value="android"> <TabItem value="android">
@@ -77,11 +77,9 @@ public:
</TabItem> </TabItem>
<TabItem value="rn"> <TabItem value="rn">
<div class="warning"> :::warning
Using Flipper from JavaScript in React Native requires the package [react-native-flipper](https://www.npmjs.com/package/react-native-flipper) to be installed in the hosting application.
Please note that using Flipper from JavaScript in React Native requires the package [`react-native-flipper`](https://www.npmjs.com/package/react-native-flipper) to be installed in the hosting application. :::
</div>
```javascript ```javascript
import {addPlugin} from 'react-native-flipper'; import {addPlugin} from 'react-native-flipper';
@@ -101,14 +99,13 @@ addPlugin({
}, },
}); });
``` ```
</TabItem> </TabItem>
<TabItem value="js"> <TabItem value="js">
<div class="warning"> :::warning
Using Flipper from JavaScript in your browser requires the package [js-flipper](https://www.npmjs.com/package/js-flipper) to be installed in the hosting application.
Please note that using Flipper from JavaScript in your browser requires the package [`js-flipper`](https://www.npmjs.com/package/js-flipper) to be installed in the hosting application. :::
</div>
```javascript ```javascript
import {flipperClient} from 'js-flipper'; import {flipperClient} from 'js-flipper';
@@ -140,10 +137,10 @@ flipperClientPromise?.then((flipperClient) => {
}); });
}); });
``` ```
</TabItem> </TabItem>
</Tabs> </Tabs>
## Using FlipperConnection ## Using FlipperConnection
`onConnect` will be called when your plugin becomes active. This will provide a `FlipperConnection` allowing you to register receivers for desktop method calls and respond with data. `onConnect` will be called when your plugin becomes active. This will provide a `FlipperConnection` allowing you to register receivers for desktop method calls and respond with data.
@@ -272,7 +269,7 @@ flipperClient.addPlugin({
## Push data to the desktop ## Push data to the desktop
You don't have to wait for the desktop to request data though, you can also push data directly to the desktop. If the JS plugin subscribes to the same method, it will receive the data. You don't have to wait for the desktop to request data. You can also push data directly to the desktop. If the JS plugin subscribes to the same method, it will receive the data.
<Tabs defaultValue="android" values={[{label: 'Android', value: 'android'}, { label: 'iOS', value: 'ios'}, { label: 'C++', value: 'cpp'}, { label: 'React Native (JS)', value: 'rn' }, { label: 'React (JS)', value: 'js' }]}> <Tabs defaultValue="android" values={[{label: 'Android', value: 'android'}, { label: 'iOS', value: 'ios'}, { label: 'C++', value: 'cpp'}, { label: 'React Native (JS)', value: 'rn' }, { label: 'React (JS)', value: 'js' }]}>
<TabItem value="android"> <TabItem value="android">
@@ -338,27 +335,30 @@ flipperClient.addPlugin({
### Using a plugin instance to send data ### Using a plugin instance to send data
It is often useful to get an instance of a Flipper plugin to send data to it. Flipper makes this simple with built-in support. It is often useful to get an instance of a Flipper plugin to send data to it: Flipper makes this simple with built-in support.
<FbInternalOnly> <FbInternalOnly>
#### Dependency Injection (Android only) #### Dependency Injection (Android only)
The preferred method to obtain a plugin instance is to use dependency injection when available. The preferred method to obtain a plugin instance is to use dependency injection when available.
For apps like fb4a that use dependency injection, a Module should have already been created by the create-plugin script. For apps like fb4a that use dependency injection, a Module should have already been created by the 'create-plugin' script.
This module will define a Singleton instance of your plugin that gets added to the FlipperClient. This module will define a Singleton instance of your plugin that gets added to the FlipperClient.
You should use this instance of the plugin, by having it injected into your product code by the DI framework. You should use this instance of the plugin, by having it injected into your product code by the DI framework.
Alternatively, you can modify the plugin's injection module so that it injects a component into the FlipperPlugin. Alternatively, you can modify the plugin's injection module so that it injects a component into the FlipperPlugin.
</FbInternalOnly> </FbInternalOnly>
#### using FlipperClient to obtain a plugin instance #### using FlipperClient to obtain a plugin instance
Plugins should be treated as singleton instances as there can only be one `FlipperClient` and each `FlipperClient` can only have one instance of a certain plugin. The Flipper API makes this simple by offering a way to get the current client and query it for plugins. Plugins should be treated as singleton instances as there can only be one `FlipperClient` and each `FlipperClient` can only have one instance of a certain plugin. The Flipper API makes this simple by offering a way to get the current client and query it for plugins.
Plugins are identified by the string that their identifier method returns, in this example, "MyFlipperPlugin". Note that null checks may be required as plugins may not be initialized, for example in production builds. Plugins are identified by the string that their identifier method returns, in this example, 'MyFlipperPlugin'.
:::note
Null checks may be required as plugins may not be initialized, such as in production builds.
:::
<Tabs defaultValue="android" values={[{label: 'Android', value: 'android'}, { label: 'iOS', value: 'ios'}, { label: 'C++', value: 'cpp'}]}> <Tabs defaultValue="android" values={[{label: 'Android', value: 'android'}, { label: 'iOS', value: 'ios'}, { label: 'C++', value: 'cpp'}]}>
<TabItem value="android"> <TabItem value="android">
@@ -390,35 +390,30 @@ if (myPlugin) {
myPlugin->sendData(myData); myPlugin->sendData(myData);
} }
``` ```
</TabItem> </TabItem>
</Tabs> </Tabs>
In the above snippet, `sendData` is an example of a method that might be implemented by the Flipper plugin.
Here, `sendData` is an example of a method that might be implemented by the Flipper plugin.
### Bi-directional communication demo ### Bi-directional communication demo
An minimal communication demo for Android and iOS can be found in our Sample project: A minimal communication demo for Android and iOS can be found in the 'Sample' project:
* [Desktop implementation](https://github.com/facebook/flipper/blob/main/desktop/plugins/public/example/index.tsx) * [Desktop implementation](https://github.com/facebook/flipper/blob/main/desktop/plugins/public/example/index.tsx)
* [Android](https://github.com/facebook/flipper/blob/main/android/sample/src/debug/java/com/facebook/flipper/plugins/example/ExampleFlipperPlugin.java) / [iOS](https://github.com/facebook/flipper/tree/7bd4f80c2570bebb52af3cf49e45fc6130d6a473/iOS/Plugins/FlipperKitExamplePlugin/FlipperKitExamplePlugin) * [Android](https://github.com/facebook/flipper/blob/main/android/sample/src/debug/java/com/facebook/flipper/plugins/example/ExampleFlipperPlugin.java) / [iOS](https://github.com/facebook/flipper/tree/7bd4f80c2570bebb52af3cf49e45fc6130d6a473/iOS/Plugins/FlipperKitExamplePlugin/FlipperKitExamplePlugin)
For React Native and JavaScript we have a simple game of Tic Tac Toe: For React Native and JavaScript, there is a simple game of Tic Tac Toe:
* [Desktop implementation](https://github.com/facebook/flipper/blob/main/desktop/plugins/public/rn-tic-tac-toe/index.tsx) * [Desktop implementation](https://github.com/facebook/flipper/blob/main/desktop/plugins/public/rn-tic-tac-toe/index.tsx)
* [React Native implementation](https://github.com/facebook/flipper/tree/main/react-native/ReactNativeFlipperExample) / [JavaScript (React) implementation](https://github.com/facebook/flipper/tree/main/js/react-flipper-example) * [React Native implementation](https://github.com/facebook/flipper/tree/main/react-native/ReactNativeFlipperExample) / [JavaScript (React) implementation](https://github.com/facebook/flipper/tree/main/js/react-flipper-example)
## Background plugins
## Background Plugins In some cases, you may want to provide data to Flipper even when your plugin is not currently active. Returning true in `runInBackground()` results in `onConnect` being called as soon as Flipper connects, which enables you to use the connection at any time. For more detals, see the [Client Plugin Lifecycle](client-plugin-lifecycle.mdx). The advantage of this method is that the desktop plugin can process this data in the background and fire notifications. It also reduces the number of renders and time taken to display the data when the plugin becomes active.
In some cases you may want to provide data to Flipper even when your plugin is not currently active. Returning true in `runInBackground()` will result in `onConnect` being called as soon as Flipper connects, and allow you to use the connection at any time. See the [Client Plugin Lifecycle](client-plugin-lifecycle.mdx) for more details. :::warning
Please note that a background plugin could keep some data in memory until a Flipper connection is available, such as to keep statistics about the app startup process. However, a plugin shouldn't assume it will eventually get a connection, since this depends on whether the user has enabled the plugin on the Desktop side.
The benefit is that the desktop plugin can process this data in the background and fire notifications. It also reduces the number of renders and time taken to display the data when the plugin becomes active. It's important to make sure that unbounded amounts of data are not stored!
:::
<div class="warning">
Please note that a background plugin could keep some data in memory until a Flipper connection is available, for example to keep statistics about the app startup process.
However, a plugin shouldn't assume it will eventually get a connection, since this depends on whether the user has enabled the plugin on the Desktop side.
So make sure to not store unbounded amounts of data!
</div>