Docs: Clarify and document dashboard URL query parameters for variables (#56055)

docs/sources/dashboards/build-dashboards/create-dashboard-url-variables/index.md

@@ -0,0 +1,73 @@
+---
+title: Dashboard URL variables
+keywords:
+  - grafana
+  - url variables
+  - documentation
+  - variables
+  - dashboards
+aliases:
+  - /docs/grafana/latest/dashboards/build-dashboards/create-dashboard-url-variables/
+  - /docs/grafana/latest/variables/url-variables/
+  - /docs/grafana/latest/variables/variable-types/url-variables/
+weight: 250
+---
+
+# Dashboard URL variables
+
+Grafana can apply variable values passed as query parameters in dashboard URLs.
+For more information, refer to [Manage dashboard links]({{< relref "../manage-dashboard-links/" >}}) and [Templates and variables]({{< relref "../../variables/" >}}).
+
+## Passing variables as query parameters
+
+Grafana interprets query string parameters prefixed with `var-` as variables in the given dashboard.
+
+For example, in this URL:
+
+```
+https://${your-domain}/path/to/your/dashboard?var-example=value
+```
+
+The query parameter `var-example=value` represents the dashboard variable `example` with a value of `value`.
+
+### Passing multiple values for a variable
+
+To pass multiple values, repeat the variable parameter once for each value:
+
+```
+https://${your-domain}/path/to/your/dashboard?var-example=value1&var-example=value2
+```
+
+Grafana interprets `var-example=value1&var-example=value2` as the dashboard variable `example` with two values: `value1` and `value2`.
+
+### Example
+
+See [https://play.grafana.org/d/000000074/alerting?var-app=backend&var-server=backend_01&var-server=backend_03&var-interval=1]h - this passes the variable `server` with multiple values, and the variables `app` and `interval` with a single value each.
+
+## Adding variables to dashboard links
+
+Grafana can add variables to dashboard links when you generate them from a dashboard's settings. For more information and steps to add variables, refer to [Manage dashboard links]({{< relref "../manage-dashboard-links/" >}}).
+
+## Passing ad hoc filters
+
+Ad hoc filters apply key/value filters to all metric queries that use a specified data source. For more information, refer to [Add ad hoc filters]({{< relref "../../variables/add-template-variables/#add-ad-hoc-filters" >}}).
+
+To pass an ad hoc filter as a query parameter, use the variable syntax to pass the ad hoc filter variable, and also provide the key, the operator as the value, and the value as a pipe-separated list.
+
+For example, in this URL:
+
+```
+https://${your-domain}/path/to/your/dashboard?var-adhoc=example_key|=|example_value
+```
+
+The query parameter `var-adhoc=key|=|value` applies the ad hoc filter configured as the `adhoc` dashboard variable using the `example_key` key, the `=` operator, and the `example_value` value.
+
+> **Note:** When sharing URLs with ad hoc filters, remember to encode the URL. In the above example, replace the pipes (`|`) with `%7C` and the equality operator (`=`) with `%3D`.
+
+### Example
+
+See [https://play.grafana.org/d/000000002/influxdb-templated?orgId=1&var-datacenter=America&var-host=All&var-summarize=1m&var-adhoc=datacenter%7C%3D%7CAmerica] - this passes the ad hoc filter variable `adhoc` with the filter value `datacenter = America`.
+
+## Controlling time range using the URL
+
+To set a dashboard's time range, use the `from`, `to`, `time`, and `time.window` query parameters. Because these are not variables, they do not require the `var-` prefix. For more information, see the [Linking overview]({{< relref "../" >}}).

docs/sources/dashboards/build-dashboards/manage-dashboard-links/index.md

@@ -40,7 +40,7 @@ The next step is to figure out which link type is right for your workflow. Even
 
 ## Controlling time range using the URL
 
-You can control the time range of a panel or dashboard by providing following query parameters in dashboard URL:
+To control the time range of a panel or dashboard, you can provide query parameters in the dashboard URL:
 
 - `from` - defines lower limit of the time range, specified in ms epoch
 - `to` - defines upper limit of the time range, specified in ms epoch
@@ -70,7 +70,7 @@ Add links to other dashboards at the top of your current dashboard.
    - **With tags** – Enter tags to limit the linked dashboards to only the ones with the tags you enter. Otherwise, Grafana includes links to all other dashboards.
    - **As dropdown** – If you are linking to lots of dashboards, then you probably want to select this option and add an optional title to the dropdown. Otherwise, Grafana displays the dashboard links side by side across the top of your dashboard.
    - **Time range** – Select this option to include the dashboard time range in the link. When the user clicks the link, the linked dashboard opens with the indicated time range already set. **Example:** https://play.grafana.org/d/000000010/annotations?orgId=1&from=now-3h&to=now
-   - **Variable values** – Select this option to include template variables currently used as query parameters in the link. When the user clicks the link, any matching templates in the linked dashboard are set to the values from the link. Here is the variable format: `https://${you-domain}/path/to/your/dashboard?var-${template-variable1}=value1&var-${template-variable2}=value2` **Example:** https://play.grafana.org/d/000000074/alerting?var-app=backend&var-server=backend_01&var-server=backend_03&var-interval=1h
+   - **Variable values** – Select this option to include template variables currently used as query parameters in the link. When the user clicks the link, any matching templates in the linked dashboard are set to the values from the link. For more information, see [Dashboard URL variables]({{< relref "../create-dashboard-url-variables/" >}}).
    - **Open in new tab** – Select this option if you want the dashboard link to open in a new tab or window.
 1. Click **Add**.