opensource/grafana
1
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-07-31 05:43:00 +08:00
Code Issues Packages Projects Releases Wiki Activity

Plugins doc review chunk 2 (#67691)

Browse Source 
* Doc style edit for 7 topics

Signed-off-by: Joe Perez <joseph.perez@grafana.com>

* Proofread topics

Signed-off-by: Joe Perez <joseph.perez@grafana.com>

* Prettier

Signed-off-by: Joe Perez <joseph.perez@grafana.com>

* Doc fix

Signed-off-by: Joe Perez <joseph.perez@grafana.com>

* Update docs/sources/developers/plugins/add-query-editor-help.md

Co-authored-by: Jack Westbrook <jack.westbrook@gmail.com>

* Doc fixes

Signed-off-by: Joe Perez <joseph.perez@grafana.com>

* Changes from doc review

Signed-off-by: Joe Perez <joseph.perez@grafana.com>

* Incorporate review feedback

Signed-off-by: Joe Perez <joseph.perez@grafana.com>

* More fixes

Signed-off-by: Joe Perez <joseph.perez@grafana.com>

* More doc fixes

Signed-off-by: Joe Perez <joseph.perez@grafana.com>

---------

Signed-off-by: Joe Perez <joseph.perez@grafana.com>
Co-authored-by: Jack Westbrook <jack.westbrook@gmail.com>
This commit is contained in:
Joseph Perez
2023-05-12 11:33:49 -07:00
committed by GitHub
parent 8dee5d3364
commit 49a18bc8e2
7 changed files with 248 additions and 212 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/sources/developers/plugins/add-support-for-variables.md
View File

@ -4,11 +4,9 @@ title: Add support for variables in plugins
# Add support for variables in plugins
Variables are placeholders for values, and can be used to create things like templated queries and dashboard or panel links. For more information on variables, refer to [Templates and variables]({{< relref "../../dashboards/variables/" >}}).
Variables are placeholders for values, and you can use them to create templated queries, and dashboard or panel links. For more information on variables, refer to [Templates and variables]({{< relref "../../dashboards/variables/" >}}).
This guide explains how to leverage template variables in your panel plugins and data source plugins.
We'll see how you can turn a string like this:
In this guide, you'll see how you can turn a query string like this:
```sql
SELECT * FROM services WHERE id = "$service"
@ -24,9 +22,9 @@ Grafana provides a couple of helper functions to interpolate variables in a stri
## Interpolate variables in panel plugins
For panels, the `replaceVariables` function is available in the PanelProps.
For panels, the `replaceVariables` function is available in the `PanelProps`.
Add `replaceVariables` to the argument list, and pass it a user-defined template string.
Add `replaceVariables` to the argument list, and pass a user-defined template string to it:
```ts
export function SimplePanel({ options, data, width, height, replaceVariables }: Props) {
@ -38,15 +36,15 @@ export function SimplePanel({ options, data, width, height, replaceVariables }:
## Interpolate variables in data source plugins
For data sources, you need to use the getTemplateSrv, which returns an instance of TemplateSrv.
For data sources, you need to use the `getTemplateSrv`, which returns an instance of `TemplateSrv`.
1. Import `getTemplateSrv` from the `runtime` package.
1. Import `getTemplateSrv` from the `runtime` package:
```ts
import { getTemplateSrv } from '@grafana/runtime';
```
1. In your `query` method, call the `replace` method with a user-defined template string.
1. In your `query` method, call the `replace` method with a user-defined template string:
```ts
async query(options: DataQueryRequest<MyQuery>): Promise<DataQueryResponse> {
@ -60,9 +58,9 @@ For data sources, you need to use the getTemplateSrv, which returns an instance
## Format multi-value variables
When a user selects multiple values for variable, the value of the interpolated variable depends on the [variable format]({{< relref "../../dashboards/variables/variable-syntax/#advanced-variable-format-options" >}}).
When a user selects multiple values for a variable, the value of the interpolated variable depends on the [variable format]({{< relref "../../dashboards/variables/variable-syntax/#advanced-variable-format-options" >}}).
A data source can define the default format option when no format is specified by adding a third argument to the interpolation function.
A data source plugin can define the default format option when no format is specified by adding a third argument to the interpolation function.
Let's change the SQL query to use CSV format by default:
@ -84,8 +82,8 @@ Not only can you read the value of a variable, you can also update the variable
The following example shows how to update a variable called `service`.
- `query` contains the query parameters you want to update. Query parameters controlling variables are prefixed with `var-`.
- `replace: true` tells Grafana to update the current URL state, rather than creating a new history entry.
- `query` contains the query parameters you want to update. The query parameters that control variables are prefixed with `var-`.
- `replace: true` tells Grafana to update the current URL state rather than creating a new history entry.
```ts
import { locationService } from '@grafana/runtime';
@ -99,9 +97,9 @@ locationService.partial({ 'var-service': 'billing' }, true);
## Add support for query variables to your data source
[Query variables]({{< relref "../../dashboards/variables/add-template-variables/#add-a-query-variable" >}}) is a type of variable that allows you to query a data source for the values. By adding support for query variables to your data source plugin, users can create dynamic dashboards based on data from your data source.
A [query variable]({{< relref "../../dashboards/variables/add-template-variables/#add-a-query-variable" >}}) is a type of variable that allows you to query a data source for the values. By adding support for query variables to your data source plugin, users can create dynamic dashboards based on data from your data source.
Let's start by defining a query model for the variable query.
Let's start by defining a query model for the variable query:
```ts
export interface MyVariableQuery {
@ -110,7 +108,7 @@ export interface MyVariableQuery {
}
```
For a data source to support query variables, you must override the `metricFindQuery` in your `DataSourceApi` class. `metricFindQuery` returns an array of `MetricFindValue` which has a single property, `text`:
For a data source to support query variables, override the `metricFindQuery` in your `DataSourceApi` class. The `metricFindQuery` function returns an array of `MetricFindValue` which has a single property, `text`:
```ts
async metricFindQuery(query: MyVariableQuery, options?: any) {
@ -124,15 +122,15 @@ async metricFindQuery(query: MyVariableQuery, options?: any) {
}
```
> **Note:** By default, Grafana provides a default query model and editor for simple text queries. If that's all you need, then you can leave the query type as `string`.
>
> ```ts
> async metricFindQuery(query: string, options?: any)
> ```
> **Note:** By default, Grafana provides a basic query model and editor for simple text queries. If that's all you need, then leave the query type as `string`:
```ts
async metricFindQuery(query: string, options?: any)
```
Let's create a custom query editor to allow the user to edit the query model.
1. Create a `VariableQueryEditor` component.
1. Create a `VariableQueryEditor` component:
```ts
import React, { useState } from 'react';
@ -185,9 +183,9 @@ Let's create a custom query editor to allow the user to edit the query model.
Grafana saves the query model whenever one of the text fields loses focus (`onBlur`) and then previews the values returned by `metricFindQuery`.
The second argument to `onChange` allows you to set a text representation of the query which will appear next to the name of the variable in the variables list.
The second argument to `onChange` allows you to set a text representation of the query that will appear next to the name of the variable in the variables list.
1. Finally, configure your plugin to use the query editor.
1. Configure your plugin to use the query editor:
```ts
import { VariableQueryEditor } from './VariableQueryEditor';