docs: wip templating docs

docs/sources/reference/templating.md

@@ -10,19 +10,36 @@ weight = 1
 
 
 # Templating
 # Templating
 
 
-<img class="no-shadow" src="/img/docs/v2/templating_var_list.png">
+<img class="no-shadow" src="/img/docs/v4/templated_dash.png">
 
 
-Dashboard Templating allows you to make your Dashboards more interactive and dynamic.
+Templating allows you to make your dashboards more interactive and dynamic. They’re one of the more powerful and complex features in Grafana. The templating
+feature allows you to create variables that are shown as dropdown select boxes at the top of the dashboard.
+These dropdowns makes it easy to change the variable value and in turn quickly change the data being displayed.
 
 
-They’re one of the most powerful and most used features of Grafana, and they’ve recently gotten even more attention in Grafana 2.0 and Grafana 2.1.
+## What is a variable?
 
 
-You can create Dashboard Template variables that can be used practically anywhere in a Dashboard: data queries on individual Panels (within the Query Editor), the names in your legends, or titles in Panels and Rows.
+A variable is a placeholder for a value. You can use variables in metric queries and in panel titles. So when you change
+the value, using the dropdown at the top of the dashboard, your panel's metric queries will change to reflect the new value.
 
 
-You can configure Dashboard Templating by clicking the dropdown cog on the top of the Dashboard while viewing it.
+### Interpolation
 
 
+Panel titles and metric queries can refer to variables using two different syntaxes:
+
+- `$<varname>`  Example: apps.frontend.$server.requests.count
+- `[[varname]]` Example: apps.frontend.[[server]].requests.count
+
+Why two ways? The first syntax is easier to read and write but does not allow you to use a variable in the middle of word. Use
+the second syntax for scenarios like this: `my.server[[serverNumber]].count`.
+
+Before queries are sent to your data source the query is **interpolated**, meaning the variable is replaced with its current value. During
+interpolation the variable value might be **escaped** in order to conform to the syntax of the query langauge of where it is used. For example
+a variable used in a regex expression in an InfluxDB or Prometheus query will be regex escaped. Read the data source specific documentation
+article for details on value escaping during interpolation.
 
 
 ## Variable types
 ## Variable types
 
 
+<img class="no-shadow" src="/img/docs/v4/templating_var_list.png">
+
 There are three different types of Template variables: query, custom, and interval.
 There are three different types of Template variables: query, custom, and interval.
 
 
 They can all be used to create dynamic variables that you can use throughout the Dashboard, but they differ in how they get the data for their values.
 They can all be used to create dynamic variables that you can use throughout the Dashboard, but they differ in how they get the data for their values.
@@ -40,6 +57,15 @@ You can even create nested variables that use other variables in their definitio
 
 
 You can utilize the special ** All ** value to allow the Dashboard user to query for every single Query variable returned. Grafana will automatically translate ** All ** into the appropriate format for your Data Source.
 You can utilize the special ** All ** value to allow the Dashboard user to query for every single Query variable returned. Grafana will automatically translate ** All ** into the appropriate format for your Data Source.
 
 
+### Annotation query details
+
+The annotation query options are different for each data source.
+
+- [Graphite annotation queries]({{< relref "features/datasources/graphite.md#annotations" >}})
+- [Elasticsearch annotation queries]({{< relref "features/datasources/elasticsearch.md#annotations" >}})
+- [InfluxDB annotation queries]({{< relref "features/datasources/influxdb.md#annotations" >}})
+- [Prometheus annotation queries]({{< relref "features/datasources/prometheus.md#annotations" >}})
+
 #### Multi-select
 #### Multi-select
 As of Grafana 2.1, it is now possible to select a subset of Query Template variables (previously it was possible to select an individual value or 'All', not multiple values that were less than All). This is accomplished via the Multi-Select option. If enabled, the Dashboard user will be able to enable and disable individual variables.
 As of Grafana 2.1, it is now possible to select a subset of Query Template variables (previously it was possible to select an individual value or 'All', not multiple values that were less than All). This is accomplished via the Multi-Select option. If enabled, the Dashboard user will be able to enable and disable individual variables.