Docs: Add guide for data source plugin default variables and links#2488
Docs: Add guide for data source plugin default variables and links#2488
Conversation
Adds documentation for the new getDefaultVariables and getDefaultLinks methods on DataSourceApi, available in Grafana 13.0+. Includes code examples and explains how to implement these features, plus their runtime behavior and user-facing constraints. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
|
Hello! 👋 This repository uses Auto for releasing packages using PR labels. ✨ This PR can be merged. It will not be considered when calculating future versions of the npm packages and will not appear in the changelogs. |
mckn
changed the title
mckn
added
type/docs
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for two new methods (getDefaultVariables and getDefaultLinks) on the DataSourceApi interface available in Grafana 13.0+. The documentation enables data source plugin developers to register default variables and dashboard links that automatically load onto dashboards using their data source.
Changes:
- Added new documentation file explaining how to implement
getDefaultVariablesandgetDefaultLinksmethods - Included code examples following the established
class extends DataSourceApipattern - Added sidebar entry for the new documentation page
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docusaurus/website/sidebars.ts | Added sidebar entry for the new documentation page, positioned logically after the related "add-support-for-variables" guide |
| docusaurus/docs/how-to-guides/data-source-plugins/add-default-variables-and-links.md | New comprehensive guide with code examples, key behaviors explanation, and types reference for implementing default variables and links in data source plugins |
docusaurus/docs/how-to-guides/data-source-plugins/add-default-variables-and-links.md
Outdated
Show resolved
Hide resolved
docusaurus/docs/how-to-guides/data-source-plugins/add-default-variables-and-links.md
Outdated
Show resolved
Hide resolved
docusaurus/docs/how-to-guides/data-source-plugins/add-default-variables-and-links.md
Outdated
Show resolved
Hide resolved
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
| | **buildMode** | `string` | The build mode of the plugin. This field is set automatically at build time, so it should not be provided manually.<br/> | | | ||
| | **builtIn** | `boolean` | [internal only] Indicates whether the plugin is developed and shipped as part of Grafana. Also known as a 'core plugin'.<br/> | | | ||
| | **category** | `string` | Plugin category used on the Add data source page.<br/>Possible values are: `"tsdb"`, `"logging"`, `"cloud"`, `"tracing"`, `"profiling"`, `"sql"`, `"enterprise"`, `"iot"`, `"other"`<br/> | | | ||
| | **category** | `string` | Plugin category used on the Add new connection page. Can be one from the list: "tsdb", "logging", "cloud", "tracing", "profiling", "sql", "enterprise", "iot", "other", empty string or custom string<br/> | | |
There was a problem hiding this comment.
This isn't true, at least not yet...
There was a problem hiding this comment.
That file is auto-generated when you call npm -w website run prebuild. I'm not sure what change caused this. Let me see if I can find it.
There was a problem hiding this comment.
It is from this PR: grafana/grafana#117898
|
|
||
| :::note | ||
|
|
||
| This feature is available from Grafana 13.0. |
There was a problem hiding this comment.
If we wanna merge this in advance of G13 it might be nice to point devs to the nightly builds so they can play around with it in advance? 🤔
| import { DataSourceApi, DataSourceInstanceSettings } from '@grafana/data'; | ||
| import { VariableKind, DashboardLink } from '@grafana/schema/apis/dashboard.grafana.app/v2'; |
There was a problem hiding this comment.
Which versions of the @grafana npm dependencies are required to use these features / types?
There was a problem hiding this comment.
Ah, sorry - it is 12.4.0 I believe. I will update this information.
| ## Types reference | ||
|
|
||
| Both methods use types from the `@grafana/schema` package: | ||
|
|
||
| ```ts | ||
| import { VariableKind, DashboardLink } from '@grafana/schema/apis/dashboard.grafana.app/v2'; | ||
| ``` | ||
|
|
||
| `VariableKind` is a union type that supports several variable kinds including `CustomVariable`, `QueryVariable`, `DatasourceVariable`, `IntervalVariable`, `TextVariable`, `ConstantVariable`, and others. Each kind has a `spec` object with properties specific to that variable type. | ||
|
|
||
| `DashboardLink` defines a dashboard link with properties such as `title`, `url`, `type`, `icon`, `targetBlank`, and `placement`. |
There was a problem hiding this comment.
nit: I'm not sure how much benefit I see in this. If the dev is dropping the code snippets in their IDE I'd expect them to option+click on the types to see the entire interface.
What this PR does / why we need it
Adds comprehensive documentation for the new
getDefaultVariablesandgetDefaultLinksmethods on theDataSourceApiinterface, available in Grafana 13.0+. This guide explains how data source plugin developers can register default variables and dashboard links that are automatically loaded onto any dashboard using their data source.The documentation includes code examples, explains the key behaviors (runtime loading, URL sync, read-only constraints), and provides type references for developers implementing these features.
Related to: grafana/grafana#109108
Which issue(s) this PR fixes
Fixes #
Special notes for your reviewer
This documentation follows the established patterns and conventions in the data-source-plugins how-to guide directory, including consistent code example formatting with the
class extends DataSourceApipattern.