|
| 1 | ++++ |
| 2 | +title = "Plugin Review Guidelines" |
| 3 | +type = "docs" |
| 4 | +[menu.docs] |
| 5 | +name = "Plugin Review Guidelines" |
| 6 | +parent = "developing" |
| 7 | +weight = 2 |
| 8 | ++++ |
| 9 | + |
| 10 | +# Plugin Review Guidelines |
| 11 | + |
| 12 | +The Grafana team reviews all plugins that are published on Grafana.com. There are two areas we review, the metadata for the plugin and the plugin functionality. |
| 13 | + |
| 14 | +## Metadata |
| 15 | + |
| 16 | +The plugin metadata consists of a `plugin.json` file and the README.md file. These `plugin.json` file is used by Grafana to load the plugin and the README.md file is shown in the plugins section of Grafana and the plugins section of Grafana.com. |
| 17 | + |
| 18 | +### README.md |
| 19 | + |
| 20 | +The README.md file is shown on the plugins page in Grafana and the plugin page on Grafana.com. There are some differences between the GitHub markdown and the markdown allowed in Grafana/Grafana.com: |
| 21 | + |
| 22 | +- Cannot contain inline HTML. |
| 23 | +- Any image links should be absolute links. For example: https://raw.githubusercontent.com/grafana/azure-monitor-datasource/master/dist/img/grafana_cloud_install.png |
| 24 | + |
| 25 | +The README should: |
| 26 | + |
| 27 | +- describe the purpose of the plugin. |
| 28 | +- contain steps on how to get started. |
| 29 | + |
| 30 | +### Plugin.json |
| 31 | + |
| 32 | +The `plugin.json` file is the same concept as the `package.json` file for an npm package. When the Grafana server starts it will scan the plugin folders (all folders in the data/plugins subfolder) and load every folder that contains a `plugin.json` file unless the folder contains a subfolder named `dist`. In that case, the Grafana server will load the `dist` folder instead. |
| 33 | + |
| 34 | +A minimal `plugin.json` file: |
| 35 | + |
| 36 | +```json |
| 37 | +{ |
| 38 | + "type": "panel", |
| 39 | + "name": "Clock", |
| 40 | + "id": "yourorg-clock-panel", |
| 41 | + |
| 42 | + "info": { |
| 43 | + "description": "Clock panel for grafana", |
| 44 | + "author": { |
| 45 | + "name": "Author Name", |
| 46 | + "url": "http://yourwebsite.com" |
| 47 | + }, |
| 48 | + "keywords": ["clock", "panel"], |
| 49 | + "version": "1.0.0", |
| 50 | + "updated": "2018-03-24" |
| 51 | + }, |
| 52 | + |
| 53 | + "dependencies": { |
| 54 | + "grafanaVersion": "3.x.x", |
| 55 | + "plugins": [ ] |
| 56 | + } |
| 57 | +} |
| 58 | +``` |
| 59 | + |
| 60 | +- 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. |
| 61 | + |
| 62 | + Examples: |
| 63 | + |
| 64 | + - raintank-worldping-app |
| 65 | + - ryantxu-ajax-panel |
| 66 | + - alexanderzobnin-zabbix-app |
| 67 | + - hawkular-datasource |
| 68 | + |
| 69 | +- The `type` field should be either `datasource` `app` or `panel`. |
| 70 | +- The `version` field should be in the form: x.x.x e.g. `1.0.0` or `0.4.1`. |
| 71 | + |
| 72 | +The full file format for the `plugin.json` file is described [here](http://docs.grafana.org/plugins/developing/plugin.json/). |
| 73 | + |
| 74 | +## Plugin Language |
| 75 | + |
| 76 | +JavaScript, TypeScript, ES6 (or any other language) are all fine as long as the contents of the `dist` subdirectory are transpiled to JavaScript (ES5). |
| 77 | + |
| 78 | +## File and Directory Structure Conventions |
| 79 | + |
| 80 | +Here is a typical directory structure for a plugin. |
| 81 | + |
| 82 | +```bash |
| 83 | +johnnyb-awesome-datasource |
| 84 | +|-- dist |
| 85 | +|-- src |
| 86 | +| |-- img |
| 87 | +| | |-- logo.svg |
| 88 | +| |-- partials |
| 89 | +| | |-- annotations.editor.html |
| 90 | +| | |-- config.html |
| 91 | +| | |-- query.editor.html |
| 92 | +| |-- datasource.js |
| 93 | +| |-- module.js |
| 94 | +| |-- plugin.json |
| 95 | +| |-- query_ctrl.js |
| 96 | +|-- Gruntfile.js |
| 97 | +|-- LICENSE |
| 98 | +|-- package.json |
| 99 | +|-- README.md |
| 100 | +``` |
| 101 | + |
| 102 | +Most JavaScript projects have a build step. The generated JavaScript should be placed in the `dist` directory and the source code in the `src` directory. We recommend that the plugin.json file be placed in the src directory and then copied over to the dist directory when building. The `README.md` can be placed in the root or in the dist directory. |
| 103 | + |
| 104 | +Directories: |
| 105 | + |
| 106 | +- `src/` contains plugin source files. |
| 107 | +- `src/partials` contains html templates. |
| 108 | +- `src/img` contains plugin logos and other images. |
| 109 | +- `dist/` contains built content. |
| 110 | + |
| 111 | +## HTML and CSS |
| 112 | + |
| 113 | +For the HTML on editor tabs, we recommend using the inbuilt Grafana styles rather than defining your own. This makes plugins feel like a more natural part of Grafana. If done correctly, the html will also be responsive and adapt to smaller screens. The `gf-form` css classes should be used for labels and inputs. |
| 114 | + |
| 115 | +Below is a minimal example of an editor row with one form group and two fields, a dropdown and a text input: |
| 116 | + |
| 117 | +```html |
| 118 | +<div class="editor-row"> |
| 119 | + <div class="section gf-form-group"> |
| 120 | + <h5 class="section-heading">My Plugin Options</h5> |
| 121 | + <div class="gf-form"> |
| 122 | + <label class="gf-form-label width-10">Label1</label> |
| 123 | + <div class="gf-form-select-wrapper max-width-10"> |
| 124 | + <select class="input-small gf-form-input" ng-model="ctrl.panel.mySelectProperty" ng-options="t for t in ['option1', 'option2', 'option3']" ng-change="ctrl.onSelectChange()"></select> |
| 125 | + </div> |
| 126 | + <div class="gf-form"> |
| 127 | + <label class="gf-form-label width-10">Label2</label> |
| 128 | + <input type="text" class="input-small gf-form-input width-10" ng-model="ctrl.panel.myProperty" ng-change="ctrl.onFieldChange()" placeholder="suggestion for user" ng-model-onblur /> |
| 129 | + </div> |
| 130 | + </div> |
| 131 | + </div> |
| 132 | +</div> |
| 133 | +``` |
| 134 | + |
| 135 | +Use the `width-x` and `max-width-x` classes to control the width of your labels and input fields. Try to get labels and input fields to line up neatly by having the same width for all the labels in a group and the same width for all inputs in a group if possible. |
| 136 | + |
| 137 | +## Data Sources |
| 138 | + |
| 139 | +A basic guide for data sources can be found [here](http://docs.grafana.org/plugins/developing/datasources/). |
| 140 | + |
| 141 | +### Config Page Guidelines |
| 142 | + |
| 143 | +- It should be as easy as possible for a user to configure a url. If the data source is using the `datasource-http-settings` component, it should use the `suggest-url` attribute to suggest the default url or a url that is similar to what it should be (especially important if the url refers to a REST endpoint that is not common knowledge for most users e.g. `https://yourserver:4000/api/custom-endpoint`). |
| 144 | + |
| 145 | + ```html |
| 146 | + <datasource-http-settings |
| 147 | + current="ctrl.current" |
| 148 | + suggest-url="http://localhost:8080"> |
| 149 | + </datasource-http-settings> |
| 150 | + ``` |
| 151 | + |
| 152 | +- 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. |
| 153 | + |
| 154 | +#### Password Security |
| 155 | + |
| 156 | +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. |
| 157 | + |
| 158 | +Read more here about how [Authentication for Datasources]({{< relref "auth-for-datasources.md" >}}) works. |
| 159 | + |
| 160 | +If using the proxy feature then the Config page should use the `secureJsonData` blob like this: |
| 161 | + |
| 162 | + - good: `<input type="password" class="gf-form-input" ng-model='ctrl.current.secureJsonData.password' placeholder="password"></input>` |
| 163 | + - bad: `<input type="password" class="gf-form-input" ng-model='ctrl.current.password' placeholder="password"></input>` |
| 164 | + |
| 165 | +### Query Editor |
| 166 | + |
| 167 | +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. |
| 168 | + |
| 169 | +- Should use the Grafana CSS `gf-form` classes. |
| 170 | +- Should be neat and tidy. Labels and fields in columns should be aligned and should be the same width if possible. |
| 171 | +- The datasource 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). |
| 172 | +- Should not execute queries if fields in the Query Editor are empty and the query will throw an exception (defensive programming). |
| 173 | +- Should handle errors. There are two main ways to do this: |
| 174 | + - 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). |
| 175 | + - provide an error notification in the query editor like the MySQL/Postgres data sources do. Example code in the `query_ctrl` [here](https://github.com/grafana/azure-monitor-datasource/blob/b184d077f082a69f962120ef0d1f8296a0d46f03/src/query_ctrl.ts#L36-L51) and in the [html](https://github.com/grafana/azure-monitor-datasource/blob/b184d077f082a69f962120ef0d1f8296a0d46f03/src/partials/query.editor.html#L190-L193). |
0 commit comments