Docs for developing plugins (#7475)

* docs(plugins): new developing plugins section

Creates new section called Developing Plugins in
the plugin section of the docs.

1. Some changes to the Development guide page
2. Converted defaults/editor mode blog post
to new page
3. Converted snapshots blog post to new page
4. Adds new code styleguide page
5. Updates to apps and datasources pages
6. Adds plugin.json schema

* docs(links): fixes broken links

Fixes broken links to other pages as
well as broken image links.

docs/sources/administration/cli.md

@@ -10,8 +10,7 @@ weight = 8
 
 # Grafana CLI
 
-Grafana cli is a small executable that is bundled with grafana server and is suppose to be
-executed on the same machine as grafana runs.
+Grafana cli is a small executable that is bundled with grafana server and is suppose to be executed on the same machine as grafana runs.
 
 ## Plugins
 

docs/sources/alerting/metrics.md

@@ -13,7 +13,7 @@ weight = 2
 
 > Alerting is only available in Grafana v4.0 and above.
 
-The alert engine publish some internal metrics about itself. You can read more about how Grafana published [interal metrics](/installation/configuration/#metrics)
+The alert engine publishes some internal metrics about itself. You can read more about how Grafana published [internal metrics](/installation/configuration/#metrics).
 
 Description | Type | Metric name
 ---------- | ----------- | ----------

docs/sources/features/datasources/index.md

@@ -9,13 +9,16 @@ weight = 5
 +++
 
 # Data Source Overview
+
 Grafana supports many different storage backends for your time series data (Data Source). Each Data Source has a specific Query Editor that is customized for the features and capabilities that the particular Data Source exposes.
 
 
 ## Querying
+
 The query language and capabilities of each Data Source are obviously very different. You can combine data from multiple Data Sources onto a single Dashboard, but each Panel is tied to a specific Data Source that belongs to a particular Organization.
 
 ## Supported Data Sources
+
 The following datasources are officially supported:
 
 * [Graphite]({{< relref "graphite.md" >}})

docs/sources/features/datasources/prometheus.md

@@ -16,7 +16,8 @@ weight = 2
 Grafana includes support for Prometheus Datasources. While the process of adding the datasource is similar to adding a Graphite or OpenTSDB datasource type, Prometheus does have a few different options for building queries.
 
 ## Adding the data source to Grafana
-![](/img/v2/add_Prometheus.png)
+
+![](/img/docs/v2/add_Prometheus.png)
 
 1. Open the side menu by clicking the the Grafana icon in the top header.
 2. In the side menu under the `Dashboards` link you should find a link named `Data Sources`.
@@ -49,6 +50,7 @@ For details on Prometheus metric queries check out the Prometheus documentation
 - [Query Metrics - Prometheus documentation](http://prometheus.io/docs/querying/basics/).
 
 ## Templated queries
+
 Prometheus Datasource Plugin provides the following functions in `Variables values query` field in Templating Editor to query `metric names` and `labels names` on the Prometheus server.
 
 Name | Description
@@ -65,8 +67,8 @@ For details of `metric names` & `label names`, and `label values`, please refer
 You can create a template variable in Grafana and have that variable filled with values from any Prometheus metric exploration query.
 You can then use this variable in your Prometheus metric queries.
 
-For example you can have a variable that contains all values for label `hostname` if you specify a query like this
-in the templating edit view.
+For example you can have a variable that contains all values for label `hostname` if you specify a query like this in the templating edit view.
+
 ```sql
 label_values(hostname)
 ```
@@ -78,4 +80,4 @@ You can also use raw queries & regular expressions to extract anything you might
 When the `Include All` option or `Multi-Value` option is enabled, Grafana converts the labels from plain text to a regex compatible string.
 Which means you have to use `=~` instead of `=` in your Prometheus queries. For example `ALERTS{instance=~$instance}` instead of `ALERTS{instance=$instance}`.
 
-![](/img/v2/prometheus_templating.png)
+![](/img/docs/v2/prometheus_templating.png)

docs/sources/guides/basic_concepts.md

@@ -14,6 +14,7 @@ parent = "guides"
 This document is a “bottom up” introduction to basic concepts in Grafana, and can be used as a starting point to get familiar with core features.
 
 ### Data Source
+
 Grafana supports many different storage backends for your time series data (Data Source). Each Data Source has a specific Query Editor that is customized for the features and capabilities that the particular Data Source exposes.
 
 The following datasources are officially supported: [Graphite]({{< relref "features/datasources/graphite.md" >}}), [InfluxDB]({{< relref "features/datasources/influxdb.md" >}}), [OpenTSDB]({{< relref "features/datasources/opentsdb.md" >}}), [Prometheus]({{< relref "features/datasources/prometheus.md" >}}), [Elasticsearch]({{< relref "features/datasources/elasticsearch.md" >}}), [CloudWatch]({{< relref "features/datasources/cloudwatch.md" >}}).
@@ -21,6 +22,7 @@ The following datasources are officially supported: [Graphite]({{< relref "featu
 The query language and capabilities of each Data Source are obviously very different. You can combine data from multiple Data Sources onto a single Dashboard, but each Panel is tied to a specific Data Source that belongs to a particular Organization.
 
 ### Organization
+
 Grafana supports multiple organizations in order to support a wide variety of deployment models, including using a single Grafana instance to provide service to multiple potentially untrusted Organizations.
 
 In many cases, Grafana will be deployed with a single Organization.
@@ -34,6 +36,7 @@ All Dashboards are owned by a particular Organization.
 For more details on the user model for Grafana, please refer to [Admin](/reference/admin/)
 
 ### User
+
 A User is a named account in Grafana. A user can belong to one or more Organizations, and can be assigned different levels of privileges through roles.
 
 Grafana supports a wide variety of internal and external ways for Users to authenticate themselves. These include from its own integrated database, from an external SQL server, or from an external LDAP server.

docs/sources/guides/getting_started.md

@@ -10,12 +10,15 @@ parent = "guides"
 +++
 
 # Getting started
-This guide will help you get started and acquainted with Grafana. It assumes you have a working Grafana server up and running and have added at least one [Data Source](/datasources/overview).
+
+This guide will help you get started and acquainted with Grafana. It assumes you have a working Grafana server up and running and have added at least one [Data Source](/features/datasources/).
 
 ## Beginner guides
+
 Watch the 10min [beginners guide to building dashboards](https://www.youtube.com/watch?v=sKNZMtoSHN4&index=7&list=PLDGkOdUX1Ujo3wHw9-z5Vo12YLqXRjzg2) to get a quick intro to setting up Dashboards and Panels.
 
 ## Basic Concepts
+
 Read the [Basic Concepts](/guides/basic_concepts) document to get a crash course in key Grafana concepts.
 
 ### Top header
@@ -34,6 +37,7 @@ The image above shows you the top header for a Dashboard.
 6. Settings: Manage Dashboard settings and features such as Templating and Annotations.
 
 ## Dashboards, Panels, Rows, the building blocks of Grafana...
+
 Dashboards are at the core of what Grafana is all about. Dashboards are composed of individual Panels arranged on a number of Rows. Grafana ships with a variety of Panels. Grafana makes it easy to construct the right queries, and customize the display properties so that you can create the perfect Dashboard for your need. Each Panel can interact with data from any configured Grafana Data Source (currently InfluxDB, Graphite, OpenTSDB, and KairosDB). The [Basic Concepts](/guides/basic_concepts) guide explores these key ideas in detail.
 
 

docs/sources/http_api/auth.md

@@ -30,7 +30,7 @@ curl example:
 
 Open the sidemenu and click the organization dropdown and select the `API Keys` option.
 
-![](/img/v2/orgdropdown_api_keys.png)
+![](/img/docs/v2/orgdropdown_api_keys.png)
 
 You use the token in all requests in the `Authorization` header, like this:
 

docs/sources/plugins/apps.md

@@ -1,24 +0,0 @@
----
-page_title: App plugin
-page_description: App plugin for Grafana
-page_keywords: grafana, plugins, documentation
----
-
-
-# Apps
-
-App plugins is a new kind of grafana plugin that can bundle datasource and panel plugins within one package. It also enable the plugin author to create custom pages within grafana. The custom pages enables the plugin author to include things like documentation, sign up forms or controlling other services using HTTP requests.
-
-Datasource and panel plugins will show up like normal plugins. The app pages will be available in the main menu.
-
-<img class="no-shadow" src="/img/v3/app-in-main-menu.png">
-
-## Enabling app plugins
-After installing an app it have to be enabled before it show up as an datasource or panel. You can do that on the app page in the config tab.
-
-### Develop your own App
-
-> 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/example-app)
-

docs/sources/plugins/developing/apps.md

@@ -0,0 +1,63 @@
++++
+title = "Developing App Plugins"
+keywords = ["grafana", "plugins", "documentation"]
+type = "docs"
+[menu.docs]
+name = "Developing App Plugins"
+parent = "developing"
+weight = 6
++++
+
+# Grafana Apps
+
+App plugins are a new kind of grafana plugin that can bundle datasource 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.
+
+Datasource and panel plugins will show up like normal plugins. The app pages will be available in the main menu.
+
+{{< imgbox img="/img/docs/v3/app-in-main-menu.png" caption="App in Main Menu" >}}
+
+## Enabling app plugins
+
+After installing an app, it has to be enabled before it shows up as a datasource or panel. You can do that on the app page in the config tab.
+
+## Developing an App Plugin
+
+An App is a bundle of panels, dashboards and/or data source(s). There is nothing different about developing panels and data sources for an app.
+
+Apps have to be enabled in Grafana and should import any included dashboards when the user enables it. A ConfigCtrl class should be created and the dashboards imported in the postUpdate hook. See example below:
+
+```javascript
+export class ConfigCtrl {
+  /** @ngInject */
+  constructor($scope, $injector, $q) {
+    this.$q = $q;
+    this.enabled = false;
+    this.appEditCtrl.setPostUpdateHook(this.postUpdate.bind(this));
+  }
+
+  postUpdate() {
+    if (!this.appModel.enabled) {
+      return this.$q.resolve();
+    }
+    return this.appEditCtrl.importDashboards().then(() => {
+      this.enabled = true;
+      return {
+        url: "plugins/raintank-kubernetes-app/page/clusters",
+        message: "Kubernetes App enabled!"
+      };
+    });
+  }
+}
+ConfigCtrl.templateUrl = 'components/config/config.html';
+```
+
+If possible a link to a dashboard or custom page should be shown after enabling the app to guide the user to the appropriate place.
+
+{{< imgbox img="/img/docs/app_plugin_after_enable.png" caption="After enabling" >}}
+
+### Develop your own App
+
+> 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/example-app)
+

docs/sources/plugins/developing/code-styleguide.md

@@ -0,0 +1,182 @@
++++
+title = "Plugin Code Styleguide"
+type = "docs"
+[menu.docs]
+name = "Plugin Code Styleguide"
+parent = "developing"
+weight = 2
++++
+
+# Grafana Plugin Code Styleguide
+
+This guide has two parts. The first part describes the metadata and the second part is a styleguide for HTML/CSS and JavaScript in Grafana plugins and applies if you are using ES6 in your plugin. If using TypeScript then the [Angular TypeScript styleguide](https://angular.io/styleguide) is recommended.
+
+## Metadata
+
+The plugin metadata consists of a plugin.json file and the README.md file. These two files are used by Grafana and Grafana.net.
+
+### Plugin.json (mandatory)
+
+The plugin.json file is the same concept as the package.json file for an npm package. 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.
+
+The most important fields are the first three, especially the id. The convention for the plugin id is **[github username/org]-[plugin name]-[datasource|app|panel]** and it has to be unique.
+
+Examples:
+
+```
+raintank-worldping-app
+grafana-simple-json-datasource
+grafana-piechart-panel
+mtanda-histogram-panel
+```
+
+The full file format for plugin.json is described [here]({{< relref "plugin.json.md" >}}).
+
+Minimal plugin.json:
+
+```javascript
+{
+  "type": "panel",
+  "name": "Clock",
+  "id": "yourorg-clock-panel",
+
+  "info": {
+    "description": "Clock panel for grafana",
+    "author": {
+      "name": "Raintank Inc.",
+      "url": "http://raintank.io"
+    },
+    "keywords": ["clock", "panel"],
+    "version": "1.0.0",
+    "updated": "2015-03-24"
+  },
+
+  "dependencies": {
+    "grafanaVersion": "3.x.x",
+    "plugins": [ ]
+  }
+}
+```
+
+### 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.
+
+## File and Directory Structure Conventions
+
+Here is a typical directory structure for a plugin.
+
+```
+johnnyb-awesome-datasource
+|-- dist
+|-- spec
+|   |-- datasource_spec.js
+|   |-- query_ctrl_spec.js
+|   |-- test-main.js
+|-- src
+|   |-- img
+|   |   |-- logo.svg
+|   |-- partials
+|   |   |-- annotations.editor.html
+|   |   |-- config.html
+|   |   |-- query.editor.html
+|   |-- datasource.js
+|   |-- module.js
+|   |-- plugin.json
+|   |-- query_ctrl.js
+|-- Gruntfile.js
+|-- LICENSE
+|-- package.json
+|-- README.md
+```
+
+Most JavaScript projects have a build step and most Grafana plugins are built using Babel and ES6. 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.
+
+Directories:
+
+- `src/` contains plugin source files.
+- `src/partials` contains html templates.
+- `src/img` contains plugin logos and other images.
+- `spec/` contains tests (optional).
+- `dist/` contains built content.
+
+## HTML and CSS
+
+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.
+
+Below is a minimal example of an editor row with one form group and two fields, a dropdown and a text input:
+
+```html
+<div class="editor-row">
+  <div class="section gf-form-group">
+    <h5 class="section-heading">My Plugin Options</h5>
+    <div class="gf-form">
+      <label class="gf-form-label width-10">Label1</label>
+      <div class="gf-form-select-wrapper max-width-10">
+        <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>
+      </div>
+      <div class="gf-form">
+        <label class="gf-form-label width-10">Label2</label>
+        <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 />
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+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.
+
+## Build Scripts
+
+Our recommendation is to use whatever you usually use - Grunt, Gulp or npm scripts. Most plugins seems to use Grunt so that is probably the easiest to get started with if you do not have a preferred build system. The only requirement is that it supports systemjs which is required by Grafana to load plugins.
+
+## Linting
+
+We recommend that you use a linter for your JavaScript. For ES6, the standard linter is [eslint](http://eslint.org/). Rules for linting are described in an .eslintrc that is placed in the root directory. [Here is an example](https://github.com/grafana/worldmap-panel/blob/master/.eslintrc) of linting rules in a plugin.
+
+### ES6 features
+
+1. Use `const` if a variable is not going to be reassigned.
+2. Prefer to use `let` instead `var` ([Exploring ES6](http://exploringjs.com/es6/ch_core-features.html#_from-var-to-letconst))
+3. Use arrow functions, which don’t shadow `this` ([Exploring ES6](http://exploringjs.com/es6/ch_core-features.html#_from-function-expressions-to-arrow-functions)):
+
+    ```js
+    testDatasource() {
+      return this.getServerStatus()
+      .then(status => {
+        return this.doSomething(status);
+      })
+    }
+    ```
+
+    better than
+
+    ```js
+    testDatasource() {
+      var self = this;
+      return this.getServerStatus()
+      .then(function(status) {
+        return self.doSomething(status);
+      })
+    }
+    ```
+4. Use native _Promise_ object:
+
+    ```js
+    metricFindQuery(query) {
+      if (!query) {
+        return Promise.resolve([]);
+      }
+    }
+    ```
+
+    better than
+
+    ```js
+    metricFindQuery(query) {
+      if (!query) {
+        return this.$q.when([]);
+      }
+    }
+    ```
+5. If using Lodash, then be consequent and prefer that to the native ES6 array functions.

docs/sources/plugins/datasources.md → docs/sources/plugins/developing/datasources.md

@@ -1,3 +1,12 @@
++++
+title = "Developing Datasource Plugins"
+keywords = ["grafana", "plugins", "documentation"]
+type = "docs"
+[menu.docs]
+name = "Developing Datasource Plugins"
+parent = "developing"
+weight = 6
++++
 
 # Datasources
 
@@ -31,9 +40,11 @@ There are two datasource specific settings for the plugin.json
 These settings indicates what kind of data the plugin can deliver. At least one of them have to be true
 
 ## Datasource
+
 The javascript object that communicates with the database and transforms data to times series.
 
-The Datasource should contain the following functions.
+The Datasource should contain the following functions:
+
 ```
 query(options) //used by panels to get data
 testDatasource() //used by datasource configuration page to make sure the connection is working
@@ -41,9 +52,14 @@ annotationQuery(options) // used by dashboards to get annotations
 metricFindQuery(options) // used by query editor to get metric suggestions.
 ```
 
+### testDatasource
+
+When a user clicks on the *Save & Test* button when adding a new data source, the details are first saved to the database and then the `testDatasource` function that is defined in your data source plugin will be called. It is recommended that this function makes 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.
+
 ### Query
 
-Request object passed to datasource.query function
+Request object passed to datasource.query function:
+
 ```json
 {
   "range": { "from": "2015-12-22T03:06:13.851Z", "to": "2015-12-22T06:48:24.137Z" },
@@ -57,11 +73,12 @@ Request object passed to datasource.query function
 }
 ```
 
-There are two different kind of results for datasources.
-Time series and table. Time series is the most common format and is supported by all datasources and panels. Table format is only support by the Influxdb datasource and table panel. But we might see more of this in the future.
+There are two different kinds of results for datasources;
+time series and table. Time series is the most common format and is supported by all datasources and panels. Table format is only supported by the InfluxDB datasource and table panel. But we might see more of this in the future.
+
+Time series response from datasource.query.
+An array of:
 
-Time series response from datasource.query
-An array of
 ```json
 [
   {
@@ -81,8 +98,9 @@ An array of
 ]
 ```
 
-Table response from datasource.query
-An array of
+Table response from datasource.query.
+An array of:
+
 ```json
 [
   {
@@ -119,7 +137,8 @@ An array of
 
 ### Annotation Query
 
-Request object passed to datasource.annotationQuery function
+Request object passed to datasource.annotationQuery function:
+
 ```json
 {
   "range": { "from": "2016-03-04T04:07:55.144Z", "to": "2016-03-04T07:07:55.144Z" },
@@ -132,7 +151,8 @@ Request object passed to datasource.annotationQuery function
 }
 ```
 
-Expected result from datasource.annotationQuery
+Expected result from datasource.annotationQuery:
+
 ```json
 [
   {
@@ -152,24 +172,24 @@ 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 have to inherit from the app/plugins/sdk.QueryCtrl class.
+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.
 
 Requires a static template or templateUrl variable which will be rendered as the view for this controller.
 
 ## ConfigCtrl
 
-A javascript class that will be instantiated and treated as an Angular controller when a user tries to edit or create a new datasource of this type.
+A JavaScript class that will be instantiated and treated as an Angular controller when a user tries to edit or create a new datasource of this type.
 
 Requires a static template or templateUrl variable which will be rendered as the view for this controller.
 
 ## QueryOptionsCtrl
 
-A javascript class that will be instantiated and treated as an Angular controller when the user edits metrics in a panel. This controller is responsible for handling panel wide settings for the datasource. Such as interval, rate and aggregations if needed.
+A JavaScript class that will be instantiated and treated as an Angular controller when the user edits metrics in a panel. This controller is responsible for handling panel wide settings for the datasource, such as interval, rate and aggregations if needed.
 
 Requires a static template or templateUrl variable which will be rendered as the view for this controller.
 
 ## AnnotationsQueryCtrl
 
-A javascript class that will be instantiated and treated as an Angular controller when the user choose this type of datasource in the templating menu in the dashboard.
+A JavaScript class that will be instantiated and treated as an Angular controller when the user choose this type of datasource in the templating menu in the dashboard.
 
-Requires a static template or templateUrl variable which will be rendered as the view for this controller. The fields that are bound to this controller is then sent to the Database objects annotationQuery function.
+Requires a static template or templateUrl variable which will be rendered as the view for this controller. The fields that are bound to this controller are then sent to the Database objects annotationQuery function.

docs/sources/plugins/developing/defaults-and-editor-mode.md

@@ -0,0 +1,128 @@
++++
+title = "Plugin Defaults and Editor Mode"
+type = "docs"
+[menu.docs]
+name = "Plugin Defaults and Editor Mode"
+parent = "developing"
+weight = 3
++++
+
+# Plugin Defaults and Editor Mode
+
+Most plugins allow users to customize the behavior by changing settings on an editor tab. These setting fields are saved in the dashboard json.
+
+## Defaults
+
+We define fields to be saved in Grafana by creating values on the panel object of the controller. You can see these values for any panel by choosing View JSON from the settings menu in Grafana. Here is an excerpt from the clock panel json (with some fields removed), the panel data is saved in the panels array:
+
+```json
+{
+  "id": 4,
+  "title": "Clock",
+...
+  "rows": [
+    {
+...
+      "panels": [
+        {
+          "bgColor": "rgb(132, 151, 130)",
+          "clockType": "24 hour",
+```
+
+You can define panel data by first creating a variable with default values for the fields and then setting them on the panel object:
+
+```javascript
+const panelDefaults = {
+  clockType: '24 hour',
+  fontSize: '60px',
+  fontWeight: 'normal',
+  bgColor: null
+};
+
+constructor($scope, $injector) {
+  super($scope, $injector);
+  _.defaults(this.panel, panelDefaults);
+
+  this.updateClock();
+}
+```
+
+The Lodash function [defaults](https://lodash.com/docs/4.17.4#defaults), which is called in the code above: `_.defaults`, sets a default value only if the value is not already set. This way values that have been changed by the user will not be overwritten.
+
+These panel fields can be used in the controller or module.html template:
+
+```html
+<h2 style="font-size: {{ctrl.panel.fontSize}};">{{ctrl.time}}</h2>
+```
+
+If you want your users to be able to change these panel values then you need to expose them in the Grafana editor.
+
+## Editor Mode
+
+Editor mode is when a user clicks Edit on a panel. Every panel has a general tab where you change the title and width and some panels have more inbuilt tabs like the Metrics tab or Time Range tab. A panel plugin can add its own tab(s) so that a user can customize the panel. 
+
+Grafana conventions mean all you need to do is to hook up an Angular template with input fields and Grafana will automatically save the values to the dashboard json and load them on dashboard load.
+
+## Using Events
+
+To add an editor tab you need to hook into the event model so that the tab is added when the *init-edit-mode* event is triggered. The following code should be added to the constructor of the plugin Ctrl class:
+
+```javascript
+this.events.on('init-edit-mode', this.onInitEditMode.bind(this));
+```
+
+Then you need to create a handler function that is bound to the event. In the example above, the handler is called onInitEditMode. The tab is added by calling the controller function, *addEditorTab*. This function has three parameters; the tab name, the path to a html template for the new editor tab and the tab number. It can be a bit tricky to figure out the path, the path name will be based on the id that is specified in the plugin.json file - for example **grafana-clock-panel**. The code below hooks up an Angular template called editor.html that is located in the `src/partials` directory.
+
+```javascript
+onInitEditMode() {
+  this.addEditorTab('Options', 'public/plugins/grafana-clock-panel/editor.html', 2);
+}
+```
+
+## Editor HTML and CSS
+
+For editor tabs html, it is best to use Grafana css styles rather than custom styles. This is to preserve the look and feel of other tabs in Grafana.
+
+Most editor tabs should use the [gf-form css class](https://github.com/grafana/grafana/blob/master/public/sass/components/_gf-form.scss) from Grafana. The example below has one row with a couple of columns and each column is wrapped in a div like this:
+
+```html
+<div class="section gf-form-group">
+ ```
+
+Then each pair, label and field is wrapped in a div with a gf-form class.
+
+```html
+<div class="gf-form">
+  <label class="gf-form-label width-8">Font Size</label>
+  <input type="text" class="gf-form-input width-4" ng-model="ctrl.panel.fontSize" ng-change="ctrl.render()" ng-model-onblur>
+</div>
+```
+
+Note that there are some Angular attributes here. *ng-model* will update the panel data. *ng-change* will render the panel when you change the value. This change will occur on the onblur event due to the *ng-model-onblur* attribute. This means you can see the effect of your changes on the panel while editing.
+
+{{< imgbox img="/assets/img/blog/clock-panel-editor.png" caption="Panel Editor" >}}
+
+On the editor tab we use a drop down for 12/24 hour clock, an input field for font size and a color picker for the background color.
+
+The drop down/select has its own *gf-form-select-wrapper* css class and looks like this:
+
+```html
+<div class="gf-form">
+  <label class="gf-form-label width-9">12 or 24 hour</label>
+  <div class="gf-form-select-wrapper max-width-9">
+    <select class="input-small gf-form-input" ng-model="ctrl.panel.clockType" ng-options="t for t in ['12 hour', '24 hour', 'custom']" ng-change="ctrl.render()"></select>
+  </div>
+</div>
+```
+
+The color picker (or spectrum picker) is a component that already exists in Grafana. We use it like this for the background color:
+
+```html
+<spectrum-picker class="gf-form-input" ng-model="ctrl.panel.bgColor" ng-change="ctrl.render()" ></spectrum-picker>
+```
+
+## Editor Tab Finished
+
+To reiterate, this all ties together quite neatly. We specify properties and panel defaults in the constructor for the panel controller and these can then be changed in the editor. Grafana takes care of saving the changes.
+
+One thing to be aware of  is that panel defaults are used the first time a panel is created to set the initial values of the panel properties. After the panel is saved then the saved value will be used instead. So beware if you update panel defaults they will not automatically update the property in an existing panel. For example, if you set the default font size to 60px first and then in version 2 of the plugin change it to 50px, existing panels will still have 60px and only new panels will get the new 50px value.

docs/sources/plugins/developing/development.md

@@ -0,0 +1,120 @@
++++
+title = "Developer Guide"
+type = "docs"
+aliases = ["/plugins/development/", "/plugins/datasources/", "/plugins/apps/", "/plugins/panels/"]
+[menu.docs]
+name = "Developer Guide"
+parent = "developing"
+weight = 1
++++
+
+# Developer Guide
+
+From grafana 3.0 it's very easy to develop your own plugins and share them with other grafana users.
+
+There are two blog posts about authoring a plugin that might also be of interest to any plugin authors, [Timing is Everything. Writing the Clock Panel Plugin for Grafana 3.0- part 1](http://grafana.org/blog/2016/04/08/timing-is-everything.-writing-the-clock-panel-plugin-for-grafana-3.0/) and [Timing is Everything. Editor Mode in Grafana 3.0 for the Clock Panel Plugin](http://grafana.org/blog/2016/04/15/timing-is-everything.-editor-mode-in-grafana-3.0-for-the-clock-panel-plugin/).
+
+## Short version
+
+1. [Setup grafana](http://docs.grafana.org/project/building_from_source/)
+2. Clone an example plugin into ```/var/lib/grafana/plugins```  or `data/plugins` (relative to grafana git repo if your running development version from source dir)
+3. Code away!
+
+## 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 is 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.
+
+## Metadata
+
+See the [coding styleguide]({{< relref "code-styleguide.md" >}}) for details on the metadata.
+
+## module.(js|ts)
+
+This is the entry point for every plugin. This is the place where you should export
+your plugin implementation. Depending on what kind of plugin you are developing you
+will be expected to export different things. You can find what's expected for [datasource]({{< relref "datasources.md" >}}), [panels]({{< relref "panels.md" >}})
+and [apps]({{< relref "apps.md" >}}) plugins in the documentation.
+
+The Grafana SDK is quite small so far and can be found here:
+
+- [SDK file in Grafana](https://github.com/grafana/grafana/blob/master/public/app/plugins/sdk.ts)
+- [SDK Readme](https://github.com/grafana/grafana/blob/master/public/app/plugins/plugin_api.md)
+
+The SDK contains three different plugin classes: PanelCtrl, MetricsPanelCtrl and QueryCtrl. For plugins of the panel type, the module.js file should export one of these. There are some extra classes for [data sources]({{< relref "datasources.md" >}}).
+
+Example:
+
+```javascript
+import {ClockCtrl} from './clock_ctrl';
+
+export {
+  ClockCtrl as PanelCtrl
+};
+```
+
+The module class is also where css for the dark and light themes is imported:
+
+```javascript
+import {loadPluginCss} from 'app/plugins/sdk';
+import WorldmapCtrl from './worldmap_ctrl';
+
+loadPluginCss({
+  dark: 'plugins/grafana-worldmap-panel/css/worldmap.dark.css',
+  light: 'plugins/grafana-worldmap-panel/css/worldmap.light.css'
+});
+
+export {
+  WorldmapCtrl as PanelCtrl
+};
+```
+
+## Start developing your plugin
+
+There are three ways that you can start developing a Grafana plugin.
+
+1. Setup a Grafana development environment. [(described here)](http://docs.grafana.org/project/building_from_source/) and place your plugin in the ```data/plugins``` folder.
+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.
+
+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.
+
+## Grafana Events
+
+There are a number of Grafana events that a plugin can hook into:
+
+- `init-edit-mode` can be used to add tabs when editing a panel
+- `panel-teardown` can be used for clean up
+- `data-received` is an event in that is triggered on data refresh and can be hooked into
+- `data-snapshot-load` is an event triggered to load data when in snapshot mode.
+- `data-error` is used to handle errors on dashboard refresh.
+
+If a panel receives data and hooks into the `data-received` event then it should handle snapshot mode too. Otherwise the panel will not work if saved as a snapshot. [Getting Plugins to work in Snapshot Mode]({{< relref "snapshot-mode.md" >}}) describes how to add support for this.
+
+## Examples
+
+We currently 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 datasource plugin for querying json data from backends)
+ - [example-app](https://github.com/grafana/example-app)
+ - [clock-panel](https://github.com/grafana/clock-panel)
+ - [singlestat-panel](https://github.com/grafana/grafana/blob/master/public/app/plugins/panel/singlestat/module.ts)
+ - [piechart-panel](https://github.com/grafana/piechart-panel)
+
+## Other Articles
+
+- [Getting Plugins to work in Snapshot Mode]({{< relref "snapshot-mode.md" >}})
+- [Plugin Defaults and Editor Mode]({{< relref "defaults-and-editor-mode.md" >}})
+- [Grafana Plugin Code Styleguide]({{< relref "code-styleguide.md" >}})
+- [Grafana Apps]({{< relref "apps.md" >}})
+- [Grafana Datasources]({{< relref "datasources.md" >}})
+- [plugin.json Schema]({{< relref "plugin.json.md" >}})

docs/sources/plugins/developing/index.md

@@ -0,0 +1,8 @@
++++
+title = "Developing Plugins"
+type = "docs"
+[menu.docs]
+parent = "plugins"
+identifier = "developing"
+weight = 3
++++

docs/sources/plugins/panels.md → docs/sources/plugins/developing/panels.md

@@ -9,7 +9,7 @@ page_keywords: grafana, plugins, documentation
 title = "Installing Plugins"
 type = "docs"
 [menu.docs]
-parent = "plugins"
+parent = "developing"
 weight = 1
 +++
 

docs/sources/plugins/developing/plugin.json.md

@@ -0,0 +1,28 @@
++++
+title = "plugin.json Schema"
+keywords = ["grafana", "plugins", "documentation"]
+type = "docs"
+[menu.docs]
+name = "plugin.json Schema"
+parent = "developing"
+weight = 6
++++
+
+# Plugin.json
+
+The plugin.json file is mandatory for all plugins. 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.
+
+## Plugin JSON Schema
+
+| Property | Description |
+| ------------- |-------------|
+| id | unique name of the plugin - [conventions described in styleguide]({{< relref "code-styleguide.md" >}}) |
+| type | panel/datasource/app |
+| name | Human readable name of the plugin |
+| info.description | Description of plugin. Used for searching grafana net plugins |
+| info.author | |
+| info.keywords | plugin keywords. Used for search on grafana net|
+| info.logos | link to project logos |
+| info.version | project version of this commit. Must be semver |
+| dependencies.grafanaVersion | Required grafana backend version for this plugin |
+| dependencies.plugins | required plugins for this plugin. |

docs/sources/plugins/developing/snapshot-mode.md

@@ -0,0 +1,79 @@
++++
+title = "Snapshot Mode"
+type = "docs"
+[menu.docs]
+name = "Snapshot Mode"
+parent = "developing"
+weight = 6
++++
+
+# Getting Plugins to work in Snapshot Mode
+
+{{< imgbox img="/img/docs/Grafana-snapshot-example.png" caption="A dashboard using snapshot data and not live data." >}}
+
+Grafana has this great feature where you can [save a snapshot of your dashboard](http://docs.grafana.org/reference/sharing/). Instead of sending a screenshot of a dashboard to someone, you can send them a working, interactive Grafana dashboard with the snapshot data embedded inside it. The snapshot can be saved on your Grafana server and is available to all your co-workers. Raintank also hosts a [snapshot server](http://snapshot.raintank.io/) if you want to send the snapshot to someone who does not have access to your Grafana server.
+
+{{< imgbox img="/img/docs/animated_gifs/snapshots.gif" caption="Selecting a snapshot" >}}
+
+This all works because Grafana saves a snapshot of the current data in the dashboard json instead of fetching the data from a data source. However, if you are building a custom panel plugin then this will not work straight out of the box. You will need to make some small (and easy!) changes first.
+
+## Enabling support for loading snapshot data
+
+Grafana automatically saves data from data sources in the dashboard json when the snapshot is created so we do not have to write any code for that. Enabling snapshot support for reading time series data is very simple. First in the constructor, we need to add an event handler for `data-snapshot-load`. This event is triggered by Grafana when the snapshot data is loaded from the dashboard json.
+
+```javascript
+constructor($scope, $injector, contextSrv) {
+    super($scope, $injector);
+    ...
+    this.events.on('init-edit-mode', this.onInitEditMode.bind(this));
+    this.events.on('data-received', this.onDataReceived.bind(this));
+    this.events.on('panel-teardown', this.onPanelTeardown.bind(this));
+    this.events.on('data-snapshot-load', this.onDataSnapshotLoad.bind(this));
+```
+
+Then we need to create a simple event handler that just forwards the data on to our regular `data-received` handler:
+
+```javascript
+onDataSnapshotLoad(snapshotData) {
+  this.onDataReceived(snapshotData);
+}
+```
+
+This will cover most use cases for snapshot support. Sometimes you will want to save data that is not time series data from a Grafana data source and then you have to do a bit more work to get snapshot support.
+
+## Saving custom data for snapshots
+
+Data that is not time series data from a Grafana data source is not saved automatically by Grafana. Saving custom data for snapshot mode has to be done manually.
+
+{{< imgbox img="/img/docs/Grafana-save-snapshot.png" caption="Save snapshot" >}}
+
+Grafana gives us a chance to save data to the dashboard json when it is creating a snapshot. In the 'data-received' event handler, you can check the snapshot flag on the dashboard object. If this is true, then Grafana is creating a snapshot and you can manually save custom data to the panel json. In the example, a new field called snapshotLocationData in the panel json is initialized with a snapshot of the custom data.
+
+```javascript
+onDataReceived(dataList) {
+  if (!dataList) return;
+
+  if (this.dashboard.snapshot && this.locations) {
+    this.panel.snapshotLocationData = this.locations;
+  }
+```
+
+Now the location data is saved in the dashboard json but we will have to load it manually as well.
+
+## Loading custom data for snapshots
+
+The example below shows a function that loads the custom data. The data source for the custom data (an external api in this case) is not available in snapshot mode so a guard check is made to see if there is any snapshot data available first. If there is, then the snapshot data is used instead of trying to load the data from the external api.
+
+```javascript
+loadLocationDataFromFile(reload) {
+  if (this.map && !reload) return;
+
+  if (this.panel.snapshotLocationData) {
+    this.locations = this.panel.snapshotLocationData;
+    return;
+  }
+```
+
+It is really easy to forget to add this support but it enables a great feature and can be used to demo your panel.
+
+If there is a panel plugin that you would like to be installed on the Raintank Snapshot server then please contact us via [Slack](https://raintank.slack.com) or [GitHub](https://github.com/grafana/grafana).

docs/sources/plugins/development.md

@@ -1,60 +0,0 @@
-+++
-title = "Developer Guide"
-type = "docs"
-aliases = ["/plugins/datasources/", "/plugins/apps/", "/plugins/panels/"]
-[menu.docs]
-name = "Developer Guide"
-parent = "plugins"
-weight = 5
-+++
-
-# Developer Guide
-
-From grafana 3.0 it's very easy to develop your own plugins and share them with other grafana users.
-
-## Short version
-
-1. [Setup grafana](http://docs.grafana.org/project/building_from_source/)
-2. Clone an example plugin into ```/var/lib/grafana/plugins```  or `data/plugins` (relative to grafana git repo if your running development version from source dir)
-3. Code away!
-
-## 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 is 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.
-
-## module.(js|ts)
-
-This is the entry point for every plugin. This is the place where you should export
-your plugin implementation. Depending on what kind of plugin you are developing you
-will be expected to export different things. You can find what's expected for [datasource](./datasources.md), [panels](./panels.md)
-and [apps](./apps.md) plugins in the documentation.
-
-## Start developing your plugin
-
-There are three ways that you can start developing a Grafana plugin.
-
-1. Setup a Grafana development environment. [(described here)](http://docs.grafana.org/project/building_from_source/) and place your plugin in the ```data/plugins``` folder.
-2. Install Grafana and place your plugin in the plugins directory which is set in your [config file](../installation/configuration.md). 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.
-
-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.
-
-## Examples
-
-We currently 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 datasource plugin for querying json data from backends)
- - [example-app](https://github.com/grafana/example-app)
- - [clock-panel](https://github.com/grafana/clock-panel)
- - [singlestat-panel](https://github.com/grafana/grafana/blob/master/public/app/plugins/panel/singlestat/module.ts)
- - [piechart-panel](https://github.com/grafana/piechart-panel)

docs/sources/plugins/plugin.json.md

@@ -1,10 +0,0 @@
----
-page_title: Plugin json file
-page_description: Plugin json for Grafana
-page_keywords: grafana, plugins, documentation
----
-
-# Plugin.json
-
-TODO
-

docs/sources/reference/dashboard.md

@@ -66,11 +66,11 @@ Each field in the dashboard JSON is explained below with its usage:
 | **editable** | whether a dashboard is editable or not |
 | **hideControls** | whether row controls on the left in green are hidden or not |
 | **graphTooltip** | TODO |
-| **rows** | row metadata, see [rows section](/docs/sources/reference/dashboard.md/#rows) for details |
+| **rows** | row metadata, see [rows section](#rows) for details |
 | **time** | time range for dashboard, i.e. last 6 hours, last 7 days, etc |
-| **timepicker** | timepicker metadata, see [timepicker section](/docs/sources/reference/dashboard.md/#timepicker) for details |
-| **templating** | templating metadata, see [templating section](/docs/sources/reference/dashboard.md/#templating) for details |
-| **annotations** | annotations metadata, see [annotations section](/docs/sources/reference/dashboard.md/#annotations) for details |
+| **timepicker** | timepicker metadata, see [timepicker section](#timepicker) for details |
+| **templating** | templating metadata, see [templating section](#templating) for details |
+| **annotations** | annotations metadata, see [annotations section](#annotations) for details |
 | **schemaVersion** | TODO |
 | **version** | TODO |
 | **links** | TODO |
@@ -79,7 +79,7 @@ Each field in the dashboard JSON is explained below with its usage:
 
 `rows` field consists of an array of JSON object representing each row in a dashboard, such as shown below:
 
-```
+```json
  "rows": [
     {
       "collapse": false,
@@ -105,14 +105,14 @@ Usage of the fields is explained below:
 | **collapse** | whether row is collapsed or not |
 | **editable** | whether a row is editable or not |
 | **height** | height of the row in pixels |
-| **panels** | panels metadata, see [panels section](/docs/sources/reference/dashboard.md/#panels) for details |
+| **panels** | panels metadata, see [panels section](#panels) for details |
 | **title** | title of row |
 
 #### panels
 
 Panels are the building blocks a dashboard. It consists of datasource queries, type of graphs, aliases, etc. Panel JSON consists of an array of JSON objects, each representing a different panel in a row. Most of the fields are common for all panels but some fields depends on the panel type. Following is an example of panel JSON representing a `graph` panel type:
 
-```
+```json
 "panels": [
         {
           "aliasColors": {},
@@ -276,7 +276,7 @@ Usage of each field is explained below:
 
 Description: TODO
 
-```
+```json
 "timepicker": {
     "collapse": false,
     "enable": true,
@@ -330,7 +330,7 @@ Usage of the fields is explained below:
 
 `templating` fields contains array of template variables with their saved values along with some other metadata, for example:
 
-```
+```json
  "templating": {
     "enable": true,
     "list": [

docs/sources/reference/playlist.md

@@ -16,7 +16,7 @@ Since Grafana automatically scales Dashboards to any resolution they're perfect
 
 ## Creating a Playlist
 
-{{< docs-imagebox img="img/docs/v3/playlist.png" max-width="25rem" >}}
+{{< docs-imagebox img="/img/docs/v3/playlist.png" max-width="25rem" >}}
 
 The Playlist feature can be accessed from Grafana's sidemenu, in the Dashboard submenu.
 

docs/sources/tutorials/hubot_howto.md

@@ -22,15 +22,17 @@ take you to the graph.
 > is so Hipchat and Slack can show them reliably (they require the image to be publicly available).
 
 <div class="text-center">
-  <img src="/img/tutorials/hubot_grafana.png" class="center"></a>
+  <img src="/img/docs/tutorials/hubot_grafana.png" class="center"></a>
 </div>
 
 ## What is Hubot?
+
 [Hubot](https://hubot.github.com/) is an universal and extensible chat bot that can be used with many chat
 services and has a huge library of third party plugins that allow you to automate anything from your
 chat rooms.
 
 ## Install Hubot
+
 Hubot is very easy to install and host. If you do not already have a bot up and running please
 read the official [Getting Started With Hubot](https://hubot.github.com/docs/) guide.
 
@@ -63,6 +65,7 @@ The `hubot-grafana` plugin requires a number of environment variables to be set
     export HUBOT_GRAFANA_S3_REGION=us-standard
 
 ### Grafana server side rendering
+
 The hubot plugin will take advantage of the Grafana server side rendering feature that can
 render any panel on the server using phantomjs. Grafana ships with a phantomjs binary (linux only).
 
@@ -70,11 +73,13 @@ To verify that this feature works try the `Direct link to rendered image` link i
 If you do not get an image when opening this link verify that the required font packages are installed for phantomjs to work.
 
 ### Grafana API Key
-<img src="/img/v2/orgdropdown_api_keys.png" style="width: 150px" class="right"></img>
+
+<img src="/img/docs/v2/orgdropdown_api_keys.png" style="width: 150px" class="right"></img>
 You need to set the environment variable `HUBOT_GRAFANA_API_KEY` to a Grafana API Key.
 You can add these from the API Keys page which you find in the Organization dropdown.
 
 ### Amazon S3
+
 The `S3` options are optional but for the images to work properly in services like Slack and Hipchat they need
 to publicly available. By specifying the `S3` options the hubot-grafana script will publish the rendered
 panel to `S3` and it will use that URL when it posts to Slack or Hipchat.
@@ -99,6 +104,7 @@ panel to `S3` and it will use that URL when it posts to Slack or Hipchat.
     - Get a templated dashboard with the `$host` parameter set to `carbon-a`
 
 ## Aliases
+
 Some of the hubot commands above can lengthy and you might have to remember the dashboard slug (url id).
 If you have a few favorite graphs you want to be able check up on often (let's say from your mobile) you
 can create hubot command aliases with the hubot script `hubot-alias`.
@@ -115,7 +121,7 @@ Now you can add an alias like this:
 
 <div class="text-center">
   Using the alias:<br>
-  <img src="/img/tutorials/hubot_grafana2.png" class="center"></a>
+  <img src="/img/docs/tutorials/hubot_grafana2.png" class="center"></a>
 </div>
 
 ## Summary