Split dashboard controls page into content-typed pages

contribute-docs/how-to/cumulative-docs/example-scenarios.md

@@ -309,7 +309,7 @@ applies_to:
 
 #### If the section lifecycle is different than the page level [unversioned-added-different]
 
-For example, on the [Dashboard controls](https://www.elastic.co/docs/explore-analyze/dashboards/add-controls#add-esql-control) page we added content about new ES|QL controls functionality that was added to Serverless in preview.
+For example, on the [Add variable controls with ES|QL](https://www.elastic.co/docs/explore-analyze/dashboards/add-variable-controls) page we added content about new ES|QL controls functionality that was added to Serverless in preview.
 Because this is different than the page-level applicability in the frontmatter, `serverless: ga`,
 label the content about the new functionality with `serverless: preview`.
 

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

@@ -6,7 +6,7 @@
 
     * 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. This option is useful for dynamically retrieving control values or perform advanced actions such as [defining chaining controls](/explore-analyze/dashboards/add-controls.md#chain-variable-controls).
+      * For controls with **Values from a query**, write an {{esql}} query to populate the list of options. This option is useful for dynamically retrieving control values or perform advanced actions such as [defining chaining controls](/explore-analyze/dashboards/add-variable-controls.md#chain-variable-controls).
         :::{tip} - Only display values available for the selected time range
         By linking the control to the global time range, the control only shows values that exist within the time range selected in the dashboard or Discover session. You can do that by specifying `WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart` in the control's query, or [custom time parameters](/explore-analyze/query-filter/languages/esql-kibana.md#_custom_time_parameters) if your indices don't have a `@timestamp` field.
         :::

explore-analyze/dashboards.md

@@ -36,7 +36,7 @@ Once you understand the basics, explore these common tasks:
 **Build and customize dashboards**
 - [Build dashboards](dashboards/building.md): Learn the fundamentals of creating and configuring dashboards.
 - [Create a dashboard](dashboards/create-dashboard.md): Start with an empty dashboard and add your content.
-- [Add filter controls](dashboards/add-controls.md): Enable interactive filtering with options lists, range sliders, and time sliders.
+- [Dashboard controls](dashboards/dashboard-controls.md): Enable interactive filtering with options lists, range sliders, time sliders, and ES|QL variable controls.
 - [Add drilldowns](dashboards/drilldowns.md): Create interactive navigation between dashboards or to external URLs.
 - [Organize dashboard panels](dashboards/arrange-panels.md): Arrange panels using collapsible sections, resizing, and positioning.
 

explore-analyze/dashboards/add-variable-controls.md

@@ -0,0 +1,132 @@
+---
+type: how-to
+description: Create ES|QL-powered variable controls for Kibana dashboards to enable dynamic filtering, multi-value selections, and chained controls.
+applies_to:
+  stack: preview 9.0
+  serverless: preview
+products:
+  - id: kibana
+---
+
+# Add variable controls with ES|QL [add-variable-control]
+
+Variable controls let you bind interactive controls to variables in your {{esql}} visualization queries. Unlike standard [dashboard controls](add-controls.md) that filter using data view fields, variable controls work directly with {{esql}} queries to enable dynamic filtering, grouping, and function selection.
+
+:::{note}
+:applies_to: stack: ga 9.0-9.1
+In versions `9.0` and `9.1`, variable controls are called {{esql}} controls.
+:::
+
+## Before you begin
+
+* **All** privilege for the **Dashboard** feature in {{product.kibana}}
+* An existing dashboard open in **Edit** mode
+* An {{esql}} visualization on your dashboard, or the intent to create one
+
+## Create a variable control [create-variable-control]
+
+You can bind controls to your {{esql}} visualizations in dashboards. When creating an {{esql}} visualization, the autocomplete suggestions prompt control insertion for field values, field names, function configuration, and function names. {{esql}} controls act as variables in your {{esql}} visualization queries.
+
+{applies_to}`{ serverless: ga, stack: ga 9.4 }` When you add a variable control from an {{esql}} panel, for example, by choosing **Create control** from the autocomplete menu, you can place it **beside** the panel so the control appears directly next to the visualization that uses it. This enables controls that only apply to specific panels in your dashboards, and exposes visualization configuration such as date histogram interval controls to dashboard users.
+
+Only **Options lists** are supported for {{esql}}-based controls. Options can be:
+- values or fields that can be static or defined by a query
+- {applies_to}`stack: ga 9.1` functions 
+
+:::{include} ../_snippets/variable-control-procedure.md
+:::
+
+If you added it by starting from a query, the control is directly inserted in that query and you can continue editing it.
+You can then insert it in any other {{esql}} visualization queries by typing the control's name.
+
+:::{tip}
+You can also create variable controls to add later to any query by selecting **Add** > **Controls** > **Variable control** in the dashboard's toolbar. 
+:::
+
+:::{include} ../_snippets/variable-control-examples.md
+:::
+
+## Allow multi-value selections [esql-multi-values-controls]
+```{applies_to}
+stack: preview 9.3
+serverless: preview
+```
+
+:::{include} ../_snippets/multi-value-esql-controls.md
+:::
+
+## Chain variable controls [chain-variable-controls]
+```{applies_to}
+serverless: ga
+stack: ga 9.3+
+```
+
+You can set up variable controls in such a way that the selection of one control determines the options available for another control.
+
+This allows you to narrow down control selections dynamically without affecting the entire dashboard, which is especially useful when working with data from multiple indices or when you need hierarchical filtering.
+
+To chain variable controls, you reference one control's variable in another control's {{esql}} query using the `?variable_name` syntax.
+
+**Example**: You create a dashboard that analyzes web traffic by region and IP address. Next, you want to see only the IP addresses that are active in a selected region, and then analyze traffic patterns for a specific IP, all without filtering the entire dashboard by region.
+
+![Chaining controls filtering an {{esql}} visualization in a dashboard](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/bltf697c4ba34f1baf8/6967d6ca03b22700081fadb3/dashboard-chaining-variable-controls.gif "=75%")
+
+1. Create the first control that will be referenced in other controls.
+
+   :::{tip}
+   Create the controls that will be referenced in other controls first. This allows the {{esql}} editor to provide proper autocomplete suggestions.
+   :::
+
+   In **Edit** mode, select **Add** > **Controls** > **Variable control** in the toolbar, then define the control:
+
+   * **Type**: Values from a query
+   * **Query**: 
+     ```esql
+     FROM kibana_sample_data_logs | WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart | STATS BY geo.dest
+     ```
+   * **Variable name**: `?region`
+   * **Label**: Region
+
+   This control extracts all unique destination regions from your logs.
+
+2. Create the second control that depends on the first control.
+
+   Add another variable control:
+
+   * **Type**: Values from a query
+   * **Query**: 
+     ```esql
+     FROM kibana_sample_data_logs 
+     | WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart AND geo.dest == ?region 
+     | STATS BY ip
+     ```
+   * **Variable name**: `?ip`
+   * **Label**: IP address
+
+   This control references the `?region` variable and the built-in time range variables (`?_tstart` and `?_tend`). The available IP addresses will be only those associated with the selected region.
+
+3. Test the chained controls. Both controls are now visible on your dashboard. Select different values in the **Region** control and observe how the available IP addresses in the **IP address** control change to show only IPs from that region.
+
+4. Create an {{esql}} visualization that uses the `?ip` control to filter data. For example:
+
+   ```esql
+   FROM kibana_sample_data_logs
+   | WHERE ip == ?ip
+   | STATS count = COUNT(*) BY day = DATE_TRUNC(1 day, @timestamp)
+   | SORT day
+   ```
+
+   This visualization filters data based on the selected IP address, while the IP address options themselves are filtered by the selected region.
+
+:::{note}
+When you select a value in a parent control, the child control's query reruns automatically. If the currently selected value in the child control is no longer available in the new result set, it is marked as invalid or incompatible.
+:::
+
+## Import a Discover query along with its controls [import-discover-query-controls]
+```{applies_to}
+stack: preview 9.2
+serverless: preview
+```
+
+:::{include} ../_snippets/import-discover-query-controls-into-dashboard.md
+:::

explore-analyze/dashboards/arrange-panels.md

@@ -42,7 +42,7 @@ Users viewing the dashboard will find the section in the same state as when you
 :::{note} 
 :applies_to: stack: ga 9.4
 
-**Filter controls and sections**: Controls placed inside a collapsible section apply their filters only to panels within that section. Controls placed outside sections, or [pinned to the dashboard header](add-controls.md), have global scope and filter all relevant panels on the dashboard. Refer to [Add filter controls](add-controls.md) for more on pinned and unpinned controls.
+**Filter controls and sections**: Controls placed inside a collapsible section apply their filters only to panels within that section. Controls placed outside sections, or [pinned to the dashboard header](dashboard-controls.md), have global scope and filter all relevant panels on the dashboard. Refer to [Dashboard controls](dashboard-controls.md) for more on pinned and unpinned controls.
 :::
 
 ![Collapsible sections](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blt8c368aecdd095010/685e8fcb9c34ed3c353812a5/collapsible_panels.gif)

explore-analyze/dashboards/dashboard-control-settings.md

@@ -0,0 +1,126 @@
+---
+type: reference
+description: Reference for all available dashboard control settings in Kibana, including options list, range slider, and shared control settings.
+applies_to:
+  stack: ga
+  serverless: ga
+products:
+  - id: kibana
+---
+
+# Dashboard control settings [dashboard-control-settings]
+
+This page lists all available settings for [dashboard controls](dashboard-controls.md). Settings vary by control type and version. For instructions on adding controls to your dashboards, refer to [Add controls to dashboards](add-controls.md).
+
+## Options list settings [options-list-settings]
+
+::::{applies-switch}
+:::{applies-item} { serverless: ga, stack: ga 9.4 }
+ * **Label**: Overwrite the default field name with a clearer and self-explanatory label.
+ - **Selections**:
+   Select multiple values to filter with the control, or only one.
+ - **Searching** (for Options list controls on *string* and *IP address* type fields):
+
+   * **Prefix**: Show options that *start with* the entered value.
+   * **Contains**: Show options that *contain* the entered value. This setting option is only available for *string* type fields. Results can take longer to show with this option.
+   * **Exact**: Show options that are an *exact* match with the entered value.
+
+   The search is not case sensitive. For example, searching for `ios` would still retrieve `iOS` if that value exists.
+ - **Additional settings**:
+
+   - **Use global filters**: A panel-level setting that applies to each individual control. It is enabled by default.
+   - **Validate user selections**: Highlight control selections that result in no data.
+   - **Ignore timeout for results**: Wait to display results until the list is complete.
+
+:::
+:::{applies-item} stack: ga 9.0-9.3
+ - **Label**: Overwrite the default field name with a clearer and self-explanatory label.
+ - **Minimum width**: Specify how much horizontal space the control should occupy. The final width can vary depending on the other controls and their own width setting.
+ - **Expand width to fit available space**: Expand the width of the control to fit the available horizontal space on the dashboard.
+
+ - **Selections**:
+   Select multiple values to filter with the control, or only one.
+
+ - **Additional settings**:
+
+   - **Ignore timeout for results**: Delays the display of the list of values until it is fully loaded. This option is useful for large data sets, to avoid missing some available options in case they take longer to load and appear when using the control.
+
+   For Options list controls on *string* and *IP address* type fields, you can define how the control's embedded search should behave:
+
+   * **Prefix**: Show options that *start with* the entered value.
+   * **Contains**: Show options that *contain* the entered value. This setting option is only available for *string* type fields. Results can take longer to show with this option.
+   * **Exact**: Show options that are an *exact* match with the entered value.
+
+   The search is not case sensitive. For example, searching for `ios` would still retrieve `iOS` if that value exists.
+:::
+
+::::
+
+## Range slider settings [range-slider-settings]
+
+::::{applies-switch}
+
+:::{applies-item} { serverless: ga, stack: ga 9.4 }
+ - **Label**: Overwrite the default field name with a clearer and self-explanatory label.
+ - **Step size**: Determine the slider's number of steps. The smaller a slider's step size, the more steps it has.
+ - **Additional settings**:
+   - **Use global filters**: A panel-level setting that applies to each individual control. It is enabled by default.
+   - **Validate user selections**: Highlight control selections that result in no data.
+
+:::
+
+:::{applies-item} stack: ga 9.0-9.3
+ - **Label**: Overwrite the default field name with a clearer and self-explanatory label.
+ - **Minimum width**: Specify how much horizontal space the control should occupy. The final width can vary depending on the other controls and their own width setting.
+ - **Expand width to fit available space**: Expand the width of the control to fit the available horizontal space on the dashboard.
+ - **Step size**: Determine the slider's number of steps. The smaller a slider's step size, the more steps it has.
+
+:::
+::::
+
+## Shared control settings [configure-controls-settings]
+
+::::{applies-switch}
+
+:::{applies-item} { serverless: ga, stack: ga 9.4 }
+Controls are always chained: a change in one control narrows the options available in all other controls on the dashboard. The exception is controls inside a [collapsible section](arrange-panels.md#collapsible-sections), which only chain with other controls in the same section. To opt a control out of chaining, turn off its **Use global filters** setting.
+
+Per-control settings such as label, selections, search options, and additional settings are configured when you [create or edit a control](add-controls.md#create-and-add-options-list-and-range-slider-controls).
+
+For pinned controls, click the Settings {icon}`gear` icon on the control to customize its display:
+
+- **Minimum width**: Specify how much horizontal space the control should occupy. The final width can vary depending on the other controls and their own width setting.
+- **Expand width to fit available space**: Expand the width of the control to fit the available horizontal space on the dashboard.
+
+**Auto apply filters**: When enabled (default), the dashboard updates as soon as options are selected in controls. When disabled, you must click the unified search **Apply** button to apply pending control selections. This option is available from the **Dashboard settings** panel.
+
+:::
+
+:::{applies-item} stack: ga 9.0-9.3
+
+1. Configure the control settings.
+
+    * {applies_to}`stack: ga 9.2-9.3` In **Edit** mode, select **Add** > **Controls** > **Settings** in the toolbar.
+    * {applies_to}`stack: ga 9.0-9.1` In **Edit** mode, select **Controls** > **Settings**.
+
+2. On the **Control settings** flyout, configure the following settings:
+
+    * **Label position** — Specify where the control label appears.
+    * **Filtering** settings:
+
+        * **Apply global filters to controls** — Define whether controls should ignore or apply any filter specified in the main filter bar of the dashboard.
+        * **Apply global time range to controls** — Define whether controls should ignore or apply the main time range specified for the dashboard. Note that [time slider controls](add-controls.md#add-time-slider-controls) rely on the global time range and don't work properly when this option is disabled.
+
+    * **Selections** settings:
+
+        * **Validate user selections** — When selected, any selected option that results in no data is ignored.
+        * **Chain controls** — When selected, controls are applied sequentially from left to right, and line by line. Any selected options in one control narrows the available options in the next control.
+        * **Apply selections automatically** — The dashboard is updated dynamically when options are selected in controls. When this option is disabled, users first need to **Apply** their control selection before they are applied to the dashboard.
+
+    * To remove all controls from the dashboard, select **Delete all**.
+
+3. Select **Save** to apply the changes.
+
+:::
+
+::::