mirror of
https://github.com/grafana/grafana.git
synced 2025-02-13 09:05:45 -06:00
Docs: Plugins doc review chunk 3 (#68159)
* Initial commit Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Minor fix Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Review changes Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Doc fixes Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Minor fix Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Update docs/sources/developers/plugins/cross-plugin-linking.md Co-authored-by: Matt Dodson <47385188+MattDodsonEnglish@users.noreply.github.com> * Update docs/sources/developers/plugins/development-with-local-grafana.md Co-authored-by: Matt Dodson <47385188+MattDodsonEnglish@users.noreply.github.com> * Update docs/sources/developers/plugins/cross-plugin-linking.md Co-authored-by: Matt Dodson <47385188+MattDodsonEnglish@users.noreply.github.com> * Update docs/sources/developers/plugins/cross-plugin-linking.md Co-authored-by: Matt Dodson <47385188+MattDodsonEnglish@users.noreply.github.com> * Update docs/sources/developers/plugins/development-with-local-grafana.md Co-authored-by: Matt Dodson <47385188+MattDodsonEnglish@users.noreply.github.com> * Incorporating review feedback Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Update docs/sources/developers/plugins/development-with-local-grafana.md Co-authored-by: Matt Dodson <47385188+MattDodsonEnglish@users.noreply.github.com> * Test commit Signed-off-by: Joe Perez <joseph.perez@grafana.com> --------- Signed-off-by: Joe Perez <joseph.perez@grafana.com> Co-authored-by: Matt Dodson <47385188+MattDodsonEnglish@users.noreply.github.com>
This commit is contained in:
Joseph Perez
GitHub
parent
753c9c262c
commit
d68079e927
@ -1,21 +1,25 @@
|
||||
---
|
||||
title: Cross plugin links
|
||||
title: Work with cross-plugin links
|
||||
description: Learn how to add plugin links to a Grafana app plugin
|
||||
---
|
||||
|
||||
# Cross plugin links
|
||||
# Work with cross-plugin links
|
||||
|
||||
Using the Plugin extensions API, App plugins can register extension points of their own to display other plugins links. This cross-plugin linking creates a more immersive user experience for installed plugins.
|
||||
With the Plugins extension API, app plugins can register extension points of their own to display other plugins links. This is called _cross-plugin linking_, and you can use it to create more immersive user experiences with installed plugins.
|
||||
|
||||
## Available extension points within plugins
|
||||
|
||||
An extension point is a location in another plugins UI where your plugin can insert links. All extension point ids within plugins should follow the naming convention `plugins/<plugin-id>/<extension-point-id>`.
|
||||
An extension point is a location in another plugin's UI where your plugin can insert links. All extension point IDs within plugins should follow the naming convention `plugins/<plugin-id>/<extension-point-id>`.
|
||||
|
||||
## How to create an extension point within a plugin
|
||||
|
||||
The `getPluginExtensions` method in `@grafana/runtime` can be used to create an extension point within your plugin. An extension point is a way of specifying where in the plugin UI other plugins links are rendered. `getPluginExtensions` takes an object consisting of the `extensionPointId`, which must begin `plugin/<pluginId>`, and any contextual information you would like to provide. It returns a list of `extensionLinks` that your program can loop over.
|
||||
Use the `getPluginExtensions` method in `@grafana/runtime` to create an extension point within your plugin. An extension point is a way to specify where in the plugin UI other plugins links are rendered.
|
||||
|
||||
_Note: Creating a extension point in a plugin creates a public interface for other plugins to interact with. Changes to the extension point id or the context it passes could break any plugin that attempts to register a link inside your plugin._
|
||||
{{% admonition type="note" %}}
|
||||
Creating an extension point in a plugin creates a public interface for other plugins to interact with. Changes to the extension point ID or its context could break any plugin that attempts to register a link inside your plugin.
|
||||
{{% /admonition %}}
|
||||
|
||||
The `getPluginExtensions` method takes an object consisting of the `extensionPointId`, which must begin `plugin/<pluginId>`, and any contextual information that you want to provide. The `getPluginExtensions` method returns a list of `extensionLinks` that your program can loop over:
|
||||
|
||||
```typescript
|
||||
import { getPluginExtensions } from '@grafana/runtime';
|
||||
@ -52,13 +56,13 @@ function AppExtensionPointExample() {
|
||||
}
|
||||
```
|
||||
|
||||
In the above example, we created a component that renders `<LinkButton />` components for all link extensions other plugins registered for the `plugin/another-app-plugin/menu` extension point id. We pass the context as the second parameter to `getPluginExtensions`, which will use `Object.freeze` to make the context immutable before passing it to other plugins.
|
||||
The preceding example shows a component that renders `<LinkButton />` components for all link extensions that other plugins registered for the `plugin/another-app-plugin/menu` extension point ID. The context is passed as the second parameter to `getPluginExtensions`, which uses `Object.freeze` to make the context immutable before passing it to other plugins.
|
||||
|
||||
## How to insert links into another plugin
|
||||
## Insert links into another plugin
|
||||
|
||||
Create links for other plugins in the same way you would [extend the Grafana application UI]({{< relref "./extend-the-grafana-ui-with-links" >}}) with a link. Rather than specify a `grafana/...` extension point, specify the plugin extension point `plugin/<pluginId>/<extensionPointId>` instead. Given the example above, use a plugin link such as the following.
|
||||
Create links for other plugins in the same way you [extend the Grafana application UI]({{< relref "./extend-the-grafana-ui-with-links" >}}) with a link. Don't specify a `grafana/...` extension point. Instead, specify the plugin extension point `plugin/<pluginId>/<extensionPointId>`.
|
||||
|
||||
### Link example
|
||||
Given the preceding example, use a plugin link such as the following:
|
||||
|
||||
```typescript
|
||||
new AppPlugin().configureExtensionLink({
|
||||
|
||||
@ -1,12 +1,17 @@
|
||||
---
|
||||
title: Custom panel option editors
|
||||
title: Build a custom panel option editor
|
||||
---
|
||||
|
||||
# Custom panel option editors
|
||||
# Build a custom panel option editor
|
||||
|
||||
The Grafana plugin platform comes with a range of editors that allow your users to customize a panel. The standard editors cover the most common types of options, such as text input and boolean switches. If you don't find the editor you're looking for, you can build your own. In this guide, you'll learn how to build your own panel option editor.
|
||||
The Grafana plugin platform comes with a range of editors that allow your users to customize a panel. The standard editors cover the most common types of options, such as text input and boolean switches. If you don't find the editor you're looking for, you can build your own.
|
||||
|
||||
The simplest editor is a React component that accepts two props: `value` and `onChange`. `value` contains the current value of the option, and `onChange` updates it.
|
||||
## Panel option editor basics
|
||||
|
||||
The simplest editor is a React component that accepts two props:
|
||||
|
||||
- **`value`**: the current value of the option
|
||||
- **`onChange`**: updates the option's value
|
||||
|
||||
The editor in the example below lets the user toggle a boolean value by clicking a button:
|
||||
|
||||
@ -22,7 +27,7 @@ export const SimpleEditor = ({ value, onChange }: StandardEditorProps<boolean>)
|
||||
};
|
||||
```
|
||||
|
||||
To use a custom panel option editor, use the `addCustomEditor` on the `OptionsUIBuilder` object in your `module.ts` file. Configure the editor to use by setting the `editor` property to the `SimpleEditor` component.
|
||||
To use a custom panel option editor, use the `addCustomEditor` on the `OptionsUIBuilder` object in your `module.ts` file and set the `editor` property to the name of your custom editor component.
|
||||
|
||||
**module.ts**
|
||||
|
||||
@ -39,9 +44,9 @@ export const plugin = new PanelPlugin<SimpleOptions>(SimplePanel).setPanelOption
|
||||
|
||||
## Add settings to your panel option editor
|
||||
|
||||
If you're using your custom editor to configure multiple options, you might want to be able to customize it. Add settings to your editor by setting the second template variable of `StandardEditorProps` to an interface that contains the settings you want to be able to configure.
|
||||
You can use your custom editor to customize multiple possible settings. To add settings to your editor, set the second template variable of `StandardEditorProps` to an interface that contains the settings you want to configure. Access the editor settings through the `item` prop.
|
||||
|
||||
You can access the editor settings through the `item` prop. Here's an example of an editor that populates a drop-down with a range of numbers. The range is defined by the `from` and `to` properties in the `Settings` interface.
|
||||
Here's an example of an editor that populates a drop-down with a range of numbers. The `Settings` interface defines the range of the `from` and `to` properties.
|
||||
|
||||
**SimpleEditor.tsx**
|
||||
|
||||
@ -71,7 +76,7 @@ export const SimpleEditor = ({ item, value, onChange }: Props) => {
|
||||
};
|
||||
```
|
||||
|
||||
You can now configure the editor for each option, by configuring the `settings` property in the call to `addCustomEditor`.
|
||||
You can now configure the editor for each option by configuring the `settings` property to call `addCustomEditor`:
|
||||
|
||||
```ts
|
||||
export const plugin = new PanelPlugin<SimpleOptions>(SimplePanel).setPanelOptions((builder) => {
|
||||
@ -90,9 +95,7 @@ export const plugin = new PanelPlugin<SimpleOptions>(SimplePanel).setPanelOption
|
||||
|
||||
## Use query results in your panel option editor
|
||||
|
||||
Option editors can access the results from the last query. This lets you update your editor dynamically, based on the data returned by the data source.
|
||||
|
||||
> **Note:** This feature was introduced in 7.0.3. Anyone using an older version of Grafana will see an error when using your plugin.
|
||||
Option editors can access the results from the last query. This lets you update your editor dynamically based on the data returned by the data source.
|
||||
|
||||
The editor context is available through the `context` prop. The data frames returned by the data source are available under `context.data`.
|
||||
|
||||
@ -116,5 +119,3 @@ export const SimpleEditor = ({ item, value, onChange, context }: StandardEditorP
|
||||
return <Select options={options} value={value} onChange={(selectableValue) => onChange(selectableValue.value)} />;
|
||||
};
|
||||
```
|
||||
|
||||
Have you built a custom editor that you think would be useful to other plugin developers? Consider contributing it as a standard editor!
|
||||
|
||||
@ -1,24 +1,24 @@
|
||||
---
|
||||
title: Development with local Grafana
|
||||
title: Develop with a local environment
|
||||
---
|
||||
|
||||
# Development with local Grafana
|
||||
# Develop with a local environment
|
||||
|
||||
This guide allows you to setup a development environment where you run Grafana and your plugin locally. With this, you will be able to see your changes as you add them.
|
||||
Follow the steps in this guide to set up a development environment where you run Grafana and your plugin locally. With this setup, you can see your changes as you add them.
|
||||
|
||||
## Run Grafana in your host
|
||||
|
||||
If you have git, Go and the required version of NodeJS in your system, you can clone and run Grafana locally:
|
||||
To clone and run Grafana locally:
|
||||
|
||||
1. Download and set up Grafana. You can find instructions on how to do it in the [developer-guide](https://github.com/grafana/grafana/blob/HEAD/contribute/developer-guide.md).
|
||||
1. Download and set up Grafana. Refer to the [developer-guide](https://github.com/grafana/grafana/blob/HEAD/contribute/developer-guide.md).
|
||||
|
||||
2. Grafana will look for plugins, by default, on its `data/plugins` directory. You can create a symbolic link to your plugin repository to detect new changes:
|
||||
2. Grafana looks for plugins, by default, in its `data/plugins` directory. You can create a symbolic link to your plugin repository to detect new changes:
|
||||
|
||||
```bash
|
||||
ln -s <plugin-path>/dist data/plugins/<plugin-name>
|
||||
```
|
||||
|
||||
3. (Optional) If the step above doesn't work for you (e.g. you are running on Windows), you can also modify the default path in the Grafana configuration (that can be found at `conf/custom.ini`) and point to the directory with your plugin:
|
||||
3. Optional: If the preceding step doesn't work for you (for example, if you are running on Windows), then modify the default path in the Grafana configuration. Find the default path at `conf/custom.ini`) and point it to your plugin's directory:
|
||||
|
||||
```ini
|
||||
[paths]
|
||||
@ -27,9 +27,11 @@ If you have git, Go and the required version of NodeJS in your system, you can c
|
||||
|
||||
## Run Grafana with docker-compose
|
||||
|
||||
Another possibility is to run Grafana with docker-compose so it runs in a container. For doing so, create the docker-compose file in your plugin directory:
|
||||
Another option is to run Grafana with docker-compose so that it runs in a container. To do so, create the `docker-compose` file in your plugin directory.
|
||||
|
||||
**NOTE**: Some plugins already include a docker-compose file so you can skip this step.
|
||||
{{% admonition type="note" %}}
|
||||
If your plugin already includes a docker-compose file, then skip this step.
|
||||
{{% /admonition %}}
|
||||
|
||||
```yaml
|
||||
version: '3.7'
|
||||
@ -41,7 +43,7 @@ services:
|
||||
ports:
|
||||
- 3000:3000/tcp
|
||||
volumes:
|
||||
# Use your plugin folder (e.g. redshift-datasource)
|
||||
# Use your plugin folder (for example, redshift-datasource)
|
||||
- ./dist:/var/lib/grafana/plugins/<plugin-folder>
|
||||
- ./provisioning:/etc/grafana/provisioning
|
||||
environment:
|
||||
@ -51,9 +53,9 @@ services:
|
||||
- GF_DEFAULT_APP_MODE=development
|
||||
```
|
||||
|
||||
## Run your plugin
|
||||
## Run your plugin in development mode
|
||||
|
||||
Finally start your plugin in development mode. Go to your plugin root directory and follow these steps:
|
||||
Finally, start your plugin in development mode. Go to your plugin's root directory and follow these steps:
|
||||
|
||||
1. Build your plugin backend and start the frontend in watch mode:
|
||||
|
||||
@ -62,9 +64,9 @@ Finally start your plugin in development mode. Go to your plugin root directory
|
||||
yarn watch
|
||||
```
|
||||
|
||||
2. Start Grafana backend and frontend:
|
||||
2. Start the Grafana backend and frontend:
|
||||
|
||||
2.1 For a local copy of Grafana, go to the directory with Grafana source code and run:
|
||||
1. For a local copy of Grafana, go to the directory with Grafana source code and run:
|
||||
|
||||
```bash
|
||||
make run
|
||||
@ -74,25 +76,29 @@ Finally start your plugin in development mode. Go to your plugin root directory
|
||||
yarn start
|
||||
```
|
||||
|
||||
2.2 Or with docker-compose, in your plugin directory, run:
|
||||
2. Or, with docker-compose, in your plugin directory, run:
|
||||
|
||||
```bash
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
After this, you should be able to see your plugin listed in Grafana and test your changes. Note that any change in the fronted will require you to refresh your browser while changes in the backend may require to rebuild your plugin binaries and reload the plugin (`mage && mage reloadPlugin` for local development or `docker-compose up` again if you are using docker-compose).
|
||||
After this, you should be able to see your plugin listed in Grafana, and then you can test your changes.
|
||||
|
||||
If you make a change in the frontend, you must refresh your browser. However, changes in the backend may require that you rebuild your plugin binaries and reload the plugin (`mage && mage reloadPlugin` for local development, or run `docker-compose up` again if you are using docker-compose).
|
||||
|
||||
## Run your backend plugin with a debugger
|
||||
|
||||
> Note: The following method only works with a local Grafana instance and currently doesn't work with Docker.
|
||||
{{% admonition type="note" %}}
|
||||
The following method only works with a local Grafana instance and currently doesn't work with Docker.
|
||||
{{% /admonition %}}
|
||||
|
||||
You can run a backend plugin and attach a debugger to it, which allows you to set breakpoints and debug your backend plugin directly from your IDE of choice.
|
||||
Running a backend plugin with a debugger is supported in Visual Studio Code and GoLand out of the box, but it can also work with any other IDE or debugger.
|
||||
|
||||
We support Visual Studio Code and GoLand out of the box, but this feature can also work with any other IDE or debugger.
|
||||
You can run a backend plugin and attach a debugger to it, which allows you to set breakpoints and debug your backend plugin directly from your IDE of choice:
|
||||
|
||||
1. Go to your plugin's folder.
|
||||
|
||||
1. Check your `go.mod` and make sure `grafana-plugin-sdk-go` is at least on `v0.156.0`
|
||||
1. Check your `go.mod` to make sure `grafana-plugin-sdk-go` are at least on `v0.156.0`
|
||||
- If not, update it to the latest version:
|
||||
```
|
||||
go get -u github.com/grafana/grafana-plugin-sdk-go
|
||||
@ -127,9 +133,9 @@ Now that your plugin is ready to run, follow the instructions bellow for your ID
|
||||
```
|
||||
|
||||
1. Press `F5` to run your plugin in debug mode.
|
||||
1. Start Grafana, if it's not already running.
|
||||
1. If Grafana isn't already running, run it.
|
||||
|
||||
> If you re-run the configuration, Grafana will automatically reload the plugin.
|
||||
> If you re-run the configuration, Grafana automatically reloads the plugin.
|
||||
|
||||
### GoLand
|
||||
|
||||
@ -141,30 +147,32 @@ Now that your plugin is ready to run, follow the instructions bellow for your ID
|
||||
|
||||
1. Run the config (with or without the debugger).
|
||||
|
||||
1. Start Grafana, if it's not already running.
|
||||
1. If Grafana isn't already running, run it.
|
||||
|
||||
> If you re-run the configuration, Grafana will automatically reload the plugin.
|
||||
{{% admonition type="note" %}}
|
||||
If you re-run the configuration, Grafana automatically reloads the plugin.
|
||||
{{% /admonition %}}
|
||||
|
||||
### Other IDEs
|
||||
|
||||
Configure your code editor to run the following steps:
|
||||
|
||||
1. Build the executable with debug flags.
|
||||
1. Build the executable file with debug flags.
|
||||
```
|
||||
mage build:debug
|
||||
```
|
||||
1. Run the plugin's executable (inside `dist`) with `-standalone -debug` flags.
|
||||
1. Run the plugin's executable file (inside `dist`) with `-standalone -debug` flags.
|
||||
```
|
||||
./gpx_xyz_linux_amd64 -standalone -debug
|
||||
```
|
||||
1. Attach a debugger to the process.
|
||||
|
||||
Then, you can start Grafana, if it's not already running.
|
||||
1. If Grafana isn't already running, run it.
|
||||
|
||||
> If you re-run the configuration, Grafana will automatically reload the plugin.
|
||||
> If you re-run the configuration, Grafana automatically reloads the plugin.
|
||||
|
||||
### Notes
|
||||
|
||||
- All logs are printed in the plugin's `stdout` rather than in Grafana logs.
|
||||
- If the backend plugin doesn't serve requests after turning off debug mode, you can force reset the standalone mode. To do so, delete the files `dist/standalone.txt` and `dist/pid.txt` alongside the executable file, and then restart Grafana.
|
||||
- We currently do not support debugging backend plugins running inside Docker.
|
||||
- If the backend plugin doesn't serve requests after you turn off debug mode, you can force a reset to the standalone mode. To do so, delete the files `dist/standalone.txt`, `dist/pid.txt`, and the executable file, and then restart Grafana.
|
||||
- Grafana doesn't support debugging backend plugins running inside Docker. But this is a [planned enhancement](https://github.com/grafana/grafana-plugin-sdk-go/issues/685).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user