Restructure dashboard controls docs and present controls as panels#5664
Restructure dashboard controls docs and present controls as panels#5664florent-leborgne wants to merge 89 commits into
Conversation
Replace inline {applies_to} directives with applies-switch/applies-item
blocks so version-specific instructions render as proper switchable tabs
instead of stacked badges with disconnected content.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Elastic Docs Style Checker (Vale)Summary: 2 warnings found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/visualize/add-controls.md | 2 | Elastic.MappedPages | mapped_pages should only be added or updated in rare scenarios. Talk with your local technical writer before pushing changes to this key. |
| explore-analyze/visualize/dashboard-controls.md | 71 | Elastic.QuotesPunctuation | Place punctuation inside closing quotation marks. |
The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Intro: convert standalone inline applies_to badges to note with :applies_to: option for pinned/unpinned concept - Step 6: add missing search techniques (Prefix/Contains/Exact) to 9.4 Options list tab (verified against codebase) - Step 6: fix non-standard 9.0-9.3+ syntax to 9.0-9.3 - Steps: renumber 8-10 to 7-9 (step 7 was merged into step 6) - Step 8: convert inline applies_to to applies-switch for chaining - Time slider: convert step 2 to applies-switch; use :applies_to: option on warning callout - Configure settings: clarify 9.4 tab with link to creation flow; fix 9.0-9.3+ syntax; remove stale serverless badge - Variable controls: merge two inline badges into single badge on same line as paragraph text - Fix "Pin to top" label to match codebase: "Pin to Dashboard" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Edit controls: applies-switch for 9.4 (panel menu) vs 9.0-9.3 (hover pencil icon), fix "Save and close" to "Save" (matches code) - Fix inconsistent capitalization: "Control" → "control" in step 3 - Scope "ES|QL controls" version note to 9.0-9.1 with applies_to - Remove duplicated filter scope paragraph from variable controls section (already covered in intro note) - Add "Clear control" tip with eraser icon (exists in all versions) - Add chaining behavior to "Configure controls" 9.4 tab so users who jump to this section via TOC understand controls are always chained Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Wrap comma-separated applies_to values in curly braces to prevent the YAML parser from interpreting colons as mapping indicators. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Multiple conditions in applies-item arguments and inline applies_to roles must use object notation with curly braces to prevent the YAML parser from treating the second colon as an invalid mapping. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Intro: make pinned/unpinned a core concept in the main paragraph (not a version-scoped note), with a note for 9.0-9.3 clarifying controls were always pinned to the header - Variable controls: convert inline applies_to badge for ES|QL rename to a proper note callout scoped to 9.0-9.1 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
benironside
left a comment
There was a problem hiding this comment.
Looks good! Left a few questions and suggestions. Hope they're helpful
|
Thanks @benironside and also sorry I forgot to turn this into draft, I haven't reviewed it entirely yet. |
Split the monolithic dashboard controls page into separate pages with clear content types for better navigation and maintainability: - dashboard-controls.md (overview): control types, concepts, requirements - add-controls.md (how-to): add/edit/delete options list, range slider, and time slider controls - add-variable-controls.md (how-to): ES|QL-powered variable controls, multi-value, chaining, Discover import - dashboard-control-settings.md (reference): all settings per type/version Update TOC, cross-links (11 files), and anchor redirects. Made-with: Cursor
Tighten the 4 controls pages and 2 shared snippets so they read with a
consistent voice, surface the right content at the right level, and use
the {applies_to} syntax consistently.
- Normalize all applies-switch tab args and admonition :applies_to: tags
to the JSON-object form ({"stack": "ga 9.4", "serverless": "ga"}).
- add-controls.md:
- Restructure the add procedure: fold the "Range slider only works on
number fields" tip into the type step; move the cross-control
chaining explanation out of the numbered procedure into a clearly
framed follow-up paragraph.
- Promote the time slider "pinned only in 9.4" constraint to a
warning before the procedure so users see it before they try.
- Rename "Delete controls" to "Clear, unpin, and delete controls" and
integrate the Clear control action into the 9.4 panel-menu list.
- Fix the 9.0+ applies-item on the delete tab to 9.0-9.3 so the two
tabs do not overlap on 9.4.
- dashboard-controls.md:
- Tighten the intro: remove the duplicated link to collapsible
sections and rephrase the 9.0-9.3 note.
- Replace em dashes in the Control types list with colons; tighten
each definition.
- add-variable-controls.md:
- Link the "standard dashboard controls" comparison to the overview
page rather than the how-to.
- Tighten the "Create a variable control" intro and move the 9.4
"place beside the panel" capability into a clearly version-scoped
tip rather than a floating paragraph.
- dashboard-control-settings.md:
- Restructure the 9.4 shared settings tab into four subsections
(Chaining, Per-control settings, Pinned control display, Auto apply
filters) so each piece of information has a clear home.
- Replace "click the Settings gear icon" with the standard
icon+bold-label pattern, and "click" with "select" throughout.
- Tighten the per-version settings lists and align their wording so
the same setting reads the same way across versions.
- _snippets/variable-control-procedure.md:
- Fix the malformed :::{tip} directive (title in directive args).
- Combine the two consecutive {applies_to} badges on the multi-value
bullet into a single JSON-object badge.
- _snippets/import-discover-query-controls-into-dashboard.md:
- Fix the empty {applies_to}`serverless:` badge.
All UI labels (Create control, Edit control, Save, Pin to Dashboard,
Unpin, Clear control, Use global filters, Validate user selections,
Auto apply filters, Dashboard settings, Searching, Prefix, Contains,
Exact, Ignore timeout for results) verified against Kibana at HEAD.
Relates to #5666
Co-authored-by: Cursor <cursoragent@cursor.com>
…switch Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # explore-analyze/_snippets/variable-control-procedure.md # explore-analyze/dashboards/add-controls.md # explore-analyze/query-filter/languages/esql-kibana.md # redirects.yml
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
Co-authored-by: Cursor <cursoragent@cursor.com>
- Add a shared control-limits snippet (1,000 items total, 100 pinned) and include it on the add-controls and add-variable-controls pages - Correct the multi-value selection tag to preview 9.3 (verified via the introducing Kibana PR), matching the page section - Rephrase variable controls as appearing as options lists, and note the Add > Controls > Variable control creation method - Reframe the variable control manage section by pinned/unpinned state - Tidy the create-control conclusion to cover both creation entry points - Drop the incorrect 9.4 tag on "Ignore timeout for results" (available since 9.0) Co-authored-by: Cursor <cursoragent@cursor.com>
Replace '>' with '→' in bold menu navigation paths across the control pages and the behavior settings snippet. Leaves ES|QL comparison operators in code blocks untouched. Co-authored-by: Cursor <cursoragent@cursor.com>
Relocate the label-highlighting behavior out of the creation flow into Manage variable controls, where post-creation interactions belong. Rendered as a version-tagged paragraph to avoid stacking admonitions. Co-authored-by: Cursor <cursoragent@cursor.com>
Rework the Manage section to match add-controls.md: pinned/unpinned framing plus an actions table (Unpin/Pin, Edit, Display settings, Remove/Delete). Variable controls have no Clear action because ES|QL controls aren't clearable, and Display settings mirrors the same pre-9.4 flyout history as data controls. Co-authored-by: Cursor <cursoragent@cursor.com>
Relocate the label-highlighting behavior from the variable control how-to to the Scope by control type section of the overview, where it illustrates what a variable control affects. Rendered as a tip nested under the variable control bullet. Highlighting is edit-mode only and specific to variable controls. Co-authored-by: Cursor <cursoragent@cursor.com>
Rework dashboard-control-settings.md into definition lists grouped by where each setting is configured (control editor, Display settings, Dashboard settings), covering options list, range slider, variable, and time slider controls. Note that Display settings apply to pinned controls only, and reach the editor by hovering and selecting Edit. Remove the orphaned control-settings snippet files now folded into the page. Co-authored-by: Cursor <cursoragent@cursor.com>
Reword the dashboard limits snippet to reflect the independent UI limits (1,000 top-level items and, separately, 100 pinned controls) instead of implying a shared budget. Replace "header" with "top of the dashboard" for consistency, and use "application menu" rather than "toolbar" for the current-version dashboard settings access. Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Docs review summary
Focus areas
- Style and clarity: Clean. The new pages are well-structured and consistently use active voice, second person, and present tense. Vale flagged a
QuotesPunctuationwarning indashboard-controls.md:71("preview 9.5",) — this is a false positive: the match is inside a JSONapplies_toblock, not prose. Identical false positives appear on pre-existing, unchanged lines increate-dashboard.md:19andusing.md:42. No action needed on these. - Jargon: None found. ES|QL, data view, collapsible section, and global time range are all linked or contextually explained on first use.
- Frontmatter and
applies_to:description,navigation_title,products, andapplies_toare present and well-formed across all five new pages. One issue:dashboard-control-settings.mdusestype: reference, which is not a documented valid content type (see inline comment). - Content type fit: The overview / how-to split is well-executed.
dashboard-controls.md(overview),add-controls.md,add-time-slider-controls.md, andadd-variable-controls.md(all how-to) are appropriately scoped. The settings page is the outlier. - Parent issue satisfaction: Satisfied. #5666 (accuracy and formatting) is addressed with version-scoped
applies_tothroughout. #7058 (controls as panels) is handled by relocating pages tovisualize/, treating controls as panels, and updating cross-links and redirects. #7130 (ES|QL pre-filtering) is covered inadd-controls.mdstep 3 with the Write a query option and the?variable_namechaining tip.
Nits
dashboard-controls.mddescription opens with "Learn about..." — a meta phrasing. Consider a value-first rewrite such as "Interactive filter controls for Kibana dashboards...".esorql.md:26usesetc.in prose (histogram, bar charts, etc.); the Elastic style guide prefers ending with a specific example or using "and so on". This is pre-existing and outside the changed hunk, so no action needed in this PR.
Generated by Docs review agent for issue #5664 · 94.2 AIC · ⌖ 8.96 AIC · ⊞ 10.7K
Rewrite the chaining overview to present data-control and variable-control chaining as two independent mechanisms, link how-tos and settings to the chaining and control-types concepts, drop meta phrasing from the overview description, and remove mid-sentence semicolons. Co-authored-by: Cursor <cursoragent@cursor.com>
Heenawter
left a comment
There was a problem hiding this comment.
Left a few notes but otherwise LGTM :) These docs are so much cleaner and easier to follow than before - thanks so much for tackling this!
| Because the values come from a query, you can also chain the control to a [variable control](add-variable-controls.md) by referencing its variable with the `?variable_name` syntax. | ||
| ::: | ||
|
|
||
| 4. Under **Control type**, select **Options list** or **Range slider**. Range sliders are only compatible with numeric fields. When you populate a Range slider with a query, the query results set the slider's minimum and maximum values. |
There was a problem hiding this comment.
When you populate a Range slider with a query, the query results set the slider's minimum and maximum values.
This is true when you select a field directly, too (without using the query builder). Perhaps we rephrase this?
| | --- | --- | | ||
| | **Clear** | Reset the control's selections without changing its settings. Available only when the control has a selection. | | ||
| | **Unpin** or **Pin to Dashboard** {applies_to}`serverless: ga` {applies_to}`stack: ga 9.4` | Move the control between the top of the dashboard and the dashboard body. For details, refer to [Pinned and unpinned controls](dashboard-controls.md#pinned-unpinned-controls). | | ||
| | **Edit** | Change the control's settings in the **Edit control** flyout. For the full list, refer to [Dashboard control settings](dashboard-control-settings.md). | |
There was a problem hiding this comment.
You can do more than just edit settings - you can change the field, control type, query, etc. Not sure if we need to use a broader term here?
| 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. |
There was a problem hiding this comment.
Do we want a similar note for normal controls?
teresaalvarezsoler
left a comment
There was a problem hiding this comment.
LGTM! Just a minor comment, also if we can add a couple of screenshots it would be great for these actions:
- Pin/unpin controls (so users know where to find these)
- Write a query for a control
| 1. From the **Data view** dropdown, select the data view that contains the field you want to use. | ||
| 2. In the **Field** list, select the field you want to filter on. | ||
|
|
||
| - {applies_to}`serverless: ga` {applies_to}`stack: ga 9.5` **Write a query**: populate the control with the results of an {{esql}} query. Use this for high-cardinality fields, or when you want to filter or otherwise shape the values the control offers. |
There was a problem hiding this comment.
Why for high-cardinality fields? Do we consider it will be more performant? If so, we should add that reason here.
natasha-moore-elastic
left a comment
There was a problem hiding this comment.
Great restructure, much easier to follow than the previous mega-page 🎉
Left a few minor suggestions and comments, hope they're helpful.
| - [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](visualize/dashboard-controls.md): Enable interactive filtering with options lists, range sliders, time sliders, and ES|QL variable controls. |
There was a problem hiding this comment.
| - [Dashboard controls](visualize/dashboard-controls.md): Enable interactive filtering with options lists, range sliders, time sliders, and ES|QL variable controls. | |
| - [Add dashboard controls](visualize/dashboard-controls.md): Enable interactive filtering with options lists, range sliders, time sliders, and ES|QL variable controls. |
Since the other bullets are all action-based
| - Up to 1,000 top-level items (panels, including unpinned controls, and sections combined) | ||
| - Up to 1,000 panels inside each section | ||
| - Up to 100 [pinned controls](add-controls.md) | ||
| - Up to 100 [pinned controls](../visualize/add-controls.md) |
There was a problem hiding this comment.
I'm wondering if this should instead link to https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5664/explore-analyze/visualize/dashboard-controls (or more specifically to its subsection https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5664/explore-analyze/visualize/dashboard-controls#pinned-unpinned-controls). Linking to https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5664/explore-analyze/visualize/add-controls might suggest that only Options list and Range slider controls can be pinned.
| :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 top of the dashboard](../visualize/dashboard-controls.md), have global scope and filter all relevant panels on the dashboard. Refer to [Dashboard controls](../visualize/dashboard-controls.md) for more on pinned and unpinned controls. |
There was a problem hiding this comment.
| **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 top of the dashboard](../visualize/dashboard-controls.md), have global scope and filter all relevant panels on the dashboard. Refer to [Dashboard controls](../visualize/dashboard-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 top of the dashboard](../visualize/dashboard-controls.md), have global scope and filter all relevant panels on the dashboard. |
I feel like we can omit the last sentence since it's linking to the same page as the previous sentence.
| - [{{esql}} for {{elastic-sec}}](/solutions/security/esql-for-security.md): Use cases and examples for threat hunting and detection rules. | ||
| - [{{esql}} visualizations](/explore-analyze/visualize/esorql.md): Create and edit {{esql}}-based visualizations in dashboards. | ||
| - [Dashboard controls](/explore-analyze/dashboards/add-controls.md): Add {{esql}}-powered controls to dashboards. | ||
| - [Dashboard controls](/explore-analyze/visualize/add-variable-controls.md): Add {{esql}}-powered variable controls to dashboards. |
There was a problem hiding this comment.
| - [Dashboard controls](/explore-analyze/visualize/add-variable-controls.md): Add {{esql}}-powered variable controls to dashboards. | |
| - [Add variable controls to dashboards](/explore-analyze/visualize/add-variable-controls.md): Add {{esql}}-powered variable controls to dashboards. |
|
|
||
| | Action | Description | | ||
| | --- | --- | | ||
| | **Clear** | Reset the control's selections without changing its settings. Available only when the control has a selection. | |
There was a problem hiding this comment.
| | **Clear** | Reset the control's selections without changing its settings. Available only when the control has a selection. | | |
| | **Clear** | Clear the selected values without changing the control's settings. Available only when a value is selected. | |
| * **Range slider**: A slider that filters data within a specified range of values. Only compatible with numeric fields. | ||
| For example, in the **[Logs] Web Traffic** dashboard from the sample web logs data, you can add a range slider for the `hour_of_day` field to display only the log data from 9:00 AM to 5:00 PM. | ||
|
|
||
| :::{image} /explore-analyze/images/kibana-dashboard-controls-range-slider.png |
|
|
||
| # Dashboard control settings [dashboard-control-settings] | ||
|
|
||
| The settings available depend on the [control type](dashboard-controls.md#control-types). |
There was a problem hiding this comment.
A short intent sentence would be nice here, both for humans and SEO. Something like "This page describes the settings you can configure when adding dashboard controls. The available settings depend on the control type."
|
|
||
| Display settings apply to pinned controls: hover over the control and select {icon}`gear` **Display settings**. Resize an unpinned control by dragging it, like any other panel. | ||
|
|
||
| **Width** |
There was a problem hiding this comment.
| **Width** | |
| **Minimum width** |
| **Selections** | ||
| : Let viewers select a single value. | ||
|
|
||
| {applies_to}`serverless: preview` {applies_to}`stack: preview 9.3` You can also allow multiple values. |
There was a problem hiding this comment.
This makes it sound like before 9.3 the Selections setting existed but only with the option to let viewers select a single value. Is that correct?
|
|
||
| Display settings apply to pinned controls: hover over the control and select {icon}`gear` **Display settings**. Resize an unpinned control by dragging it, like any other panel. | ||
|
|
||
| **Width** |
There was a problem hiding this comment.
| **Width** | |
| **Minimum width** |

Summary
Rework the dashboard controls documentation: split the single
add-controls.mdpage into five content-typed pages, relocate them to the Panels and visualizations section, present controls as panels, and document the new {{esql}} values source for data controls. This addresses the formatting/accuracy issues from #5666, the controls-as-panels move from #7058, and the {{esql}} pre-filtering coverage from #7130.New page structure
The old
explore-analyze/dashboards/add-controls.mdis split into five pages, all under Explore and analyze > Panels and visualizations (explore-analyze/visualize/), with parallel H1s, navigation titles, and section structure:dashboard-controls.mdadd-controls.mdadd-time-slider-controls.mdadd-variable-controls.mddashboard-control-settings.mdControls as panels (#7058)
visualize.md.add-controls.mdsplit redirects to the newvisualize/locations.Prefilter control values with {{esql}} (#7130)
add-controls.md: write an {{esql}} query returning a single column, preview values with Run query under Values preview, and derive Range slider min/max from the results. Queries can reference variable controls (?variable_name) for chaining.stack: ga 9.5/serverless: ga. Verified againstelastic/kibanaorigin/main: theSelect a field/Write a querytoggle andconfigure_values_query.tsxexist only onmain(9.5), are absent in 9.4, and carry no tech-preview badge (GA).Accuracy and version scoping (#5666)
Verified against
elastic/kibanaatorigin/main(9.5-dev),9.4.3(current GA), and 9.3/9.2/9.1/9.0:getControlsGroupSchema()caps the pinned controls group atmaxSize: 100in 9.4 and main, so "up to 100 pinned controls" is accurate (kept in the add pages' Before you begin).applies_tonormalized: standalone inline directives moved toapplies-switch/applies-itemor list-item-start inline form;serverless: gaadded alongsidestack: ga 9.4; non-standard range syntax removed.Variable controls: Technical preview alignment
previewaccordingly: functions, chaining, multi-value / single-or-multiple selection, and the 9.5 highlight-related-panels tip. Tagged the Variable control type as preview in the overview.add-controls.md.Overview, settings, and naming refinements
## Options list settings,## Range slider settings): each setting is a definition-list entry telling the reader where to set it. Settings whose location differs by version use nestedapplies_tobullets (for example, chaining is Use global filters on the control in 9.4+, or dashboard-wide Chain controls in 9.0-9.3). Shared behavior settings and width live in snippets so they stay consistent across control types. Restored the 9.0-9.3 "how to open the control settings dialog" menu path.Snippet fixes
variable-control-procedure.md: titled:::{tip}preserved; consecutive{applies_to}badges combined; links updated to the new location.multi-value-esql-controls.md: merged stacked notes; fixed broken list numbering (1 -> 3 -> 4 corrected to 1 -> 2 -> 3).variable-control-examples.md: rewrote example labels to a parallel "do X" form; fixed an invalid standaloneBUCKETfragment.control-settings-selections.md,control-settings-searching.md,control-settings-behavior.md,control-display-settings.md.Cross-links and redirects
visualize/paths (Dashboards overview/building pages, Discover learning tutorial, {{esql}} pages, {{esql}} visualization page, snippets, cumulative-docs example).redirects.yml, including anchor-level redirects for renamed sections (edit-controls/remove-controls->manage-controls, time slider split,configure-controls-settings-> page anchor).Screenshots to add or update
add-controls.md— panel menu showing Edit, Clear control, Pin to Dashboard / Unpin, Remove.add-controls.md— Create control flyout with Write a query selected, showing the query editor and Values preview.Test plan
applies_tobadges render correctlyexplore-analyze/dashboards/*controls*URLs (page and anchors)Relates to #4676, #5154. Closes #5666. Closes #7058. Closes #7130.