Variable controls in Discover (elastic#3440)

This PR:

- Adds a section about creating variable controls in Discover, with
sub-sections on how to edit them and how to bring these controls over to
a dashboard
- Transforms certain pieces of content into content snippets that are
shared between Discover and Dashboards docs as variable controls are
used in both apps: code examples, control parameters.
- Adds the section about "how to bring Discover sessions along with
their controls to a dashboard" to the "Add controls" page in dashboards
docs as well. This content is single-sourced so only maintained in one
place.
- Re-adds a "preview" flag to the Variable controls section in dashboard
docs, that one was mistakenly removed in another PR

Find page previews in one of the comments below

Note: Tested on staging environment on Oct 10

Closes: elastic#3096

---------

Co-authored-by: Stratou <[email protected]>
Co-authored-by: Benjamin Ironside Goldstein <[email protected]>

Author: 3 people

explore-analyze/_snippets/import-discover-query-controls-into-dashboard.md

@@ -0,0 +1,17 @@
+To add a Discover query to a dashboard in a way that preserves the [controls created from Discover](/explore-analyze/discover/try-esql.md#add-variable-control-discover) and also adds them to the dashboard, do as follows:
+
+1. Save the {{esql}} query containing the variable control into a Discover session. If your Discover session contains several tabs, only the first tab will be imported to the dashboard.
+
+1. Go to **Dashboards** and open or create one.
+
+1. Select **Add**, then **From library**.
+
+1. Find and select the Discover session you saved earlier.
+
+A new panel appears on the dashboard with the results of the query along with any attached controls.
+
+![Importing Discover controls into a dashboard](/explore-analyze/images/import-discover-control-dashboard.png " =40%")
+
+:::{note}
+When you add a visualization to a dashboard using the {icon}`save` **Save visualization** option, controls are not added to the dashboard.
+:::

explore-analyze/_snippets/variable-control-examples.md

@@ -0,0 +1,25 @@
+**Examples**
+
+* Integrate filtering into your {{esql}} experience
+
+  ```esql
+  | WHERE field == ?value
+  ```
+
+* Fields in controls for dynamic group by
+
+  ```esql
+  | STATS count=COUNT(*) BY ??field
+  ```
+
+* Variable time ranges? Bind function configuration settings to a control
+
+  ```esql
+  | BUCKET(@timestamp, ?interval),
+  ```
+
+* Make the function itself dynamic
+
+  ```esql
+  | STATS metric = ??function
+  ```

explore-analyze/_snippets/variable-control-form.md

@@ -0,0 +1,11 @@
+* The type of the control. 
+  * For controls with **Static values**, enter available controls manually or select them from the dropdown list. 
+  * For controls with **Values from a query**, write an {{esql}} query to populate the list of options.
+* The name of the control. This name is used to reference the control in {{esql}} queries. 
+  * Start the name with `?` if you want the options to be simple static values.
+  * {applies_to}`stack: ga 9.1` Start the name with `??` if you want the options to be fields or functions.
+* The values users can select for this control. You can add multiple values from suggested fields, or type in custom values. If you selected **Values from a query**, you must instead write an {{esql}} query at this step.
+* The label of the control. This is the label displayed in **Discover** or in the dashboard.
+* The width of the control.
+
+  ![ESQL control settings](/explore-analyze/images/esql-visualization-control-settings.png "title =50%")

explore-analyze/dashboards/add-controls.md

@@ -90,6 +90,10 @@ You can add one interactive time slider control to a dashboard.
 
 
 ## Add variable controls [add-variable-control]
+```{applies_to}
+stack: preview 9.0
+serverless: preview
+```
 
 :::{note}
 In versions `9.0` and `9.1`, variable controls are called {{esql}} controls.
@@ -113,17 +117,8 @@ Only **Options lists** are supported for {{esql}}-based controls. Options can be
 
 2. A menu opens to let you configure the control. This is where you can specify:
 
-    * The type of the control. 
-      * For controls with **Static values**, select the options available in the controls by entering them manually or by using a dropdown listing available values. 
-      * For controls with **Values from a query**, write an {{esql}} query to populate the list of options.
-    * The name of the control. This name is used to reference the control in {{esql}} queries. 
-      * Start the name with `?` if you want the options to be simple static values.
-      * Start the name with `??` if you want the options of the control to be fields or functions. {applies_to}`stack: ga 9.1`
-    * The values users can select for this control. You can add multiple values from suggested fields, or type in custom values. If you selected **Values from a query**, you must instead write an {{esql}} query at this step.
-    * The label of the control. This is the label displayed for users viewing the dashboard for that control.
-    * The width of the control.
-
-    ![ESQL control settings](/explore-analyze/images/esql-visualization-control-settings.png "title =50%")
+   :::{include} ../_snippets/variable-control-form.md
+   :::
 
 3. Save the control. 
 
@@ -132,34 +127,19 @@ If you added it by starting from a query, the control is directly inserted in th
 
 You can then insert it in any other {{esql}} visualization queries by typing the control's name.
 
+:::{include} ../_snippets/variable-control-examples.md
+:::
 
-**Examples**
-
-* Integrate filtering into your {{esql}} experience
-
-  ```esql
-  | WHERE field == ?value
-  ```
-
-* Fields in controls for dynamic group by
-
-  ```esql
-  | STATS count=COUNT(*) BY ?field
-  ```
-
-* Variable time ranges? Bind function configuration settings to a control
-
-  ```esql
-  | BUCKET(@timestamp, ?interval),
-  ```
-
-* Make the function itself dynamic
+![Editing {{esql}} controls from a dashboard](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blte42dfaa404bfc2d6/67d2e31e2e4dc59da190d78f/dashboard-esql-controls.gif)
 
-  ```esql
-  | STATS metric = ?function
-  ```
+### Import a Discover query along with its controls into a dashboard
+```{applies_to}
+stack: preview 9.2
+serverless: preview
+```
 
-![Editing {{esql}} controls from a dashboard](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blte42dfaa404bfc2d6/67d2e31e2e4dc59da190d78f/dashboard-esql-controls.gif)
+:::{include} ../_snippets/import-discover-query-controls-into-dashboard.md
+:::
 
 ## Configure the controls settings [configure-controls-settings]
 

explore-analyze/discover/try-esql.md

@@ -188,4 +188,43 @@ To view or edit an index:
    Editing a lookup index affects all {{esql}} queries that reference it. Make sure that your changes are compatible with existing queries that use this index.
    :::
 
-4. If you made changes, select **Save** before closing the flyout.
+4. If you made changes, select **Save** before closing the flyout.
+
+### Add variable controls to your Discover queries [add-variable-control-discover]
+```{applies_to}
+stack: preview 9.2
+serverless: preview
+```
+
+Variable controls help you make your queries more dynamic instead of having to maintain several versions of almost identical queries.
+
+![Variable control in Discover](/explore-analyze/images/variable-control-discover.png " =75%")
+
+You can add them from your Discover {{esql}} query.
+
+1. While editing your {{esql}} query, the autocomplete menu suggests adding a control when relevant or when typing `?` in the query. Select **Create control**.
+
+2. A menu opens to let you configure the control. This is where you can specify:
+
+   :::{include} ../_snippets/variable-control-form.md
+   :::
+
+3. Save the control.
+
+The variable is inserted into your query, and the control appears in the query editor.
+
+:::{include} ../_snippets/variable-control-examples.md
+:::
+
+#### Edit a variable control
+
+Once a control is active for your query, you can still edit it by hovering over it and by selecting the {icon}`pencil` **Edit** option that appears.
+
+You can edit all of the options described in [](#add-variable-control-discover).
+
+When you save your edits, the control is updated for your query.
+
+#### Import a Discover query along with its controls into a dashboard
+
+:::{include} ../_snippets/import-discover-query-controls-into-dashboard.md
+:::