Skip to content

N
nexpie-grafana-theme
Commit 816b611e by Shavonn Brown Committed by GitHub
Options

Plugins docs (#21826) 

* mostly minor edits while reading

* Update docs/sources/plugins/developing/development.md

* Update docs/sources/plugins/developing/apps.md

* Update docs/sources/plugins/developing/development.md

* Update docs/sources/plugins/developing/development.md

* Update docs/sources/plugins/developing/development.md

* Update docs/sources/plugins/developing/development.md

* Update docs/sources/plugins/developing/development.md

* notes updates

* Update docs/sources/plugins/developing/development.md

Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* update to ref tutorials

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>
parent 643735f5
Showing with 33 additions and 33 deletions
docs/sources/plugins/developing/apps.md
......@@ -10,7 +10,7 @@ weight = 4
# Grafana Apps
App plugins are a new kind of grafana plugin that can bundle data source and panel plugins within one package. It also enable the plugin author to create custom pages within grafana. The custom pages enable the plugin author to include things like documentation, sign up forms or controlling other services using HTTP requests.
App plugins are a Grafana plugin that can bundle data source and panel plugins within one package. They also enable the plugin author to create custom pages within Grafana. The custom pages enable the plugin author to include things like documentation, sign-up forms, or to control other services with HTTP requests.
Data source and panel plugins will show up like normal plugins. The app pages will be available in the main menu.
......@@ -56,4 +56,3 @@ If possible a link to a dashboard or custom page should be shown after enabling
> Our goal is not to have a very extensive documentation but rather have actual
> code that people can look at. An example implementation of an app can be found
> in this [example app repo](https://github.com/grafana/simple-app-plugin)
docs/sources/plugins/developing/code-styleguide.md
......@@ -43,8 +43,8 @@ Minimal plugin.json:
"info": {
"description": "Clock panel for grafana",
"author": {
"name": "Raintank Inc.",
"url": "http://raintank.io"
"name": "Grafana Labs",
"url": "https://grafana.com"
},
"keywords": ["clock", "panel"],
"version": "1.0.0",
......@@ -60,7 +60,7 @@ Minimal plugin.json:
### README.md
The README.md file is rendered both on Grafana.net and in the plugins section in Grafana. The only difference from how GitHub renders markdown is that html is not allowed.
The README.md file is rendered both in the grafana.com plugins page, and within the Grafana application. The only difference from how GitHub renders markdown is that html is not allowed.
## File and Directory Structure Conventions
......
docs/sources/plugins/developing/datasources.md
......@@ -17,8 +17,12 @@ time series data so that any grafana panel can then show it.
## Data source development
> Our goal is not to have a very extensive documentation but rather have actual
> code that people can look at. An example implementation of a data source can be
> found in this [example data source repo](https://github.com/grafana/simple-json-datasource)
> code that people can look at. Example implementations of a data source can be
> found in these repos:
> - [simple-json-datasource](https://github.com/grafana/simple-json-datasource)
> - [simple-datasource](https://github.com/grafana/simple-datasource)
> - [simple-json-backend-datasource](https://github.com/grafana/simple-json-backend-datasource)
To interact with the rest of grafana the plugins module file can export 4 different components.
......@@ -169,7 +173,6 @@ Expected result from datasource.annotationQuery:
]
```
## QueryCtrl
A JavaScript class that will be instantiated and treated as an Angular controller when the user edits metrics in a panel. This class has to inherit from the `app/plugins/sdk.QueryCtrl` class.
......
docs/sources/plugins/developing/defaults-and-editor-mode.md
......@@ -19,10 +19,10 @@ We define fields to be saved in Grafana by creating values on the panel object o
{
"id": 4,
"title": "Clock",
...
...
"rows": [
{
...
...
"panels": [
{
"bgColor": "rgb(132, 151, 130)",
......
docs/sources/plugins/developing/development.md
......@@ -18,7 +18,7 @@ Grafana already has a strong community of contributors and plugin developers. By
1. [Set up Grafana](https://github.com/grafana/grafana/blob/master/contribute/developer-guide.md)
2. Clone an example plugin into ```/var/lib/grafana/plugins``` or `data/plugins` (relative to grafana git repo if you're running development version from source dir)
3. Use one of our example plugins as starting point
3. Use one of our example plugins as a starting point
Example plugins
......@@ -28,21 +28,17 @@ Example plugins
- [Clock panel](https://github.com/grafana/clock-panel)
- [Pie chart panel](https://github.com/grafana/piechart-panel)
There are two blog posts about authoring a plugin that might also be of interest to any plugin authors.
You might also be interested in the available tutorials around authoring a plugin.
- [Timing is Everything. Writing the Clock Panel Plugin for Grafana](https://grafana.com/blog/2016/04/08/timing-is-everything.-writing-the-clock-panel-plugin-for-grafana-3.0/)
- [Timing is Everything. Editor Mode in Grafana for the Clock Panel Plugin](https://grafana.com/blog/2016/04/15/timing-is-everything.-editor-mode-in-grafana-3.0-for-the-clock-panel-plugin/).
- [Grafana Tutorials](https://grafana.com/tutorials/)
## What languages?
Since everything turns into javascript it's up to you to choose which language you want. That said it's probably a good idea to choose es6 or typescript since
we use es6 classes in Grafana. So it's easier to get inspiration from the Grafana repo if you choose one of those languages.
Since everything turns into JavaScript, it's up to you to choose which language you want. That said, it's probably a good idea to choose es6 or TypeScript, because we use es6 classes in Grafana. So it's easier to get inspiration from the Grafana repo if you choose one of those languages.
## Buildscript
You can use any build system you like that support systemjs. All the built content should end up in a folder named ```dist``` and committed to the repository.
By committing the dist folder the person who installs your plugin does not have to run any buildscript.
All our example plugins have build scripted configured.
You can use any build system that supports systemjs. All the built content should end up in a folder named ```dist``` and be committed to the repository. By committing the dist folder, the person who installs your plugin does not have to run any build script. All of our example plugins have a build script configured.
## Keep your plugin up to date
......@@ -100,11 +96,11 @@ There are three ways that you can start developing a Grafana plugin.
2. Install Grafana and place your plugin in the plugins directory which is set in your [config file](/installation/configuration). By default this is `/var/lib/grafana/plugins` on Linux systems.
3. Place your plugin directory anywhere you like and specify it grafana.ini.
We encourage people to setup the full Grafana environment so that you can get inspiration from the rest of grafana code base.
We encourage people to set up the full Grafana environment so that you can get inspiration from the rest of the Grafana code base.
When Grafana starts it will scan the plugin folders and mount every folder that contains a plugin.json file unless
the folder contains a subfolder named dist. In that case grafana will mount the dist folder instead.
This makes it possible to have both built and src content in the same plugin git repo.
When Grafana starts, it scans the plugin folders and mounts every folder that contains a plugin.json file unless
the folder contains a subfolder named dist. In that case, Grafana mounts the dist folder instead.
This makes it possible to have both built and src content in the same plugin Git repo.
## Grafana Events
......@@ -120,12 +116,12 @@ If a panel receives data and hooks into the `data-received` event then it should
## Examples
We currently have three different examples that you can fork/download to get started developing your grafana plugin.
We have three different examples that you can fork/download to get started developing your Grafana plugin.
- [simple-json-datasource](https://github.com/grafana/simple-json-datasource) (small data source plugin for querying json data from backends)
- [example-app](https://github.com/grafana/example-app)
- [simple-app-plugin](https://github.com/grafana/simple-app-plugin)
- [clock-panel](https://github.com/grafana/clock-panel)
- [singlestat-panel](https://github.com/grafana/grafana/blob/master/public/app/plugins/panel/singlestat/module.ts)
- [singlestat-panel](https://github.com/grafana/grafana/tree/master/public/app/plugins/panel/singlestat)
- [piechart-panel](https://github.com/grafana/piechart-panel)
## Other Articles
......
docs/sources/plugins/developing/panels.md
......@@ -32,5 +32,5 @@ In this case, make sure the template has a single `<div>...</div>` root. The pl
### Examples
- [clock-panel](https://github.com/grafana/clock-panel)
- [singlestat-panel](https://github.com/grafana/grafana/blob/master/public/app/plugins/panel/singlestat/module.ts)
- [singlestat-panel](https://github.com/grafana/grafana/tree/master/public/app/plugins/panel/singlestat)
docs/sources/plugins/developing/plugin-review-guidelines.md
......@@ -57,7 +57,7 @@ A minimal `plugin.json` file:
}
```
- The convention for the plugin id is [github username/org]-[plugin name]-[datasource|app|panel] and it has to be unique. Although if org and plugin name are the same then [plugin name]-[datasource|app|panel] is also valid. The org **cannot** be `grafana` unless it is a plugin created by the Grafana core team.
- The convention for the plugin id is **[grafana.com username/org]-[plugin name]-[datasource|app|panel]** and it has to be unique. The org **cannot** be `grafana` unless it is a plugin created by the Grafana core team.
Examples:
......@@ -66,6 +66,7 @@ A minimal `plugin.json` file:
- alexanderzobnin-zabbix-app
- hawkular-datasource
- The `type` field should be either `datasource` `app` or `panel`.
- The `version` field should be in the form: x.x.x e.g. `1.0.0` or `0.4.1`.
......@@ -151,24 +152,26 @@ A basic guide for data sources can be found [here](http://docs.grafana.org/plugi
- The `testDatasource` function should make a query to the data source that will also test that the authentication details are correct. This is so the data source is correctly configured when the user tries to write a query in a new dashboard.
#### Password Security
If possible, any passwords or secrets should be be saved in the `secureJsonData` blob. To encrypt sensitive data, the Grafana server's proxy feature must be used. The Grafana server has support for token authentication (OAuth) and HTTP Header authentication. If the calls have to be sent directly from the browser to a third-party API then this will not be possible and sensitive data will not be encrypted.
If possible, any passwords or secrets should be be saved in the `secureJsonData` blob. To encrypt sensitive data, the Grafana server's proxy feature must be used. The Grafana server has support for token authentication (OAuth) and HTTP Header authentication. If the calls have to be sent directly from the browser to a third-party API, this will not be possible and sensitive data will not be encrypted.
Read more here about how [authentication for data sources]({{< relref "auth-for-datasources.md" >}}) works.
If using the proxy feature then the Config page should use the `secureJsonData` blob like this:
If using the proxy feature, the Config page should use the `secureJsonData` blob like this:
- good: `<input type="password" class="gf-form-input" ng-model='ctrl.current.secureJsonData.password' placeholder="password"></input>`
- bad: `<input type="password" class="gf-form-input" ng-model='ctrl.current.password' placeholder="password"></input>`
### Query Editor
Each query editor is unique and can have a unique style. It should be adapted to what the users of the data source are used to.
- Should use the Grafana CSS `gf-form` classes.
- Should be neat and tidy. Labels and fields in columns should be aligned and should be the same width if possible.
- The data source should be able to handle when a user toggles a query (by clicking on the eye icon) and not execute the query. This is done by checking the `hide` property - an [example](https://github.com/grafana/grafana/blob/master/public/app/plugins/datasource/postgres/datasource.ts#L35-L38).
- The data source should be able to handle when a user toggles a query (by clicking on the eye icon) and not execute the query. This is done by checking the `hide` property - an [example](https://github.com/grafana/grafana/blob/e75840737e81f70b6d169df21eca86a624d4bdc4/public/app/plugins/datasource/postgres/datasource.ts#L73).
- Should not execute queries if fields in the Query Editor are empty and the query will throw an exception (defensive programming).
- Should handle errors. There are two main ways to do this:
- use the notification system in Grafana to show a toaster popup with the error message. Example [here](https://github.com/alexanderzobnin/grafana-zabbix/blob/fdbbba2fb03f5f2a4b3b0715415e09d5a4cf6cde/src/panel-triggers/triggers_panel_ctrl.js#L467-L471).
......
docs/sources/plugins/installation.md
......@@ -12,11 +12,10 @@ Grafana supports data source, panel, and app plugins. Having panels as plugins m
1. In a web browser, navigate to the official [Grafana Plugins page](https://grafana.com/plugins) and find a plugin that you want to install.
2. Click the plugin, and then click the **Installation** tab.
3. In the **For** field, select the organization that contains the Grafana instance you want to install the plugin on.
## Install plugin on Hosted Grafana
On the Installation tab, click the name of the Hosted Grafana instance that you want to install the plugin on.
On the Installation tab, in the **For** field, click the name of the Hosted Grafana instance that you want to install the plugin on.
Grafana handles the plugin installation automatically.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment