From 3030779ccba98c1dc3d756a1c0003331eea8217e Mon Sep 17 00:00:00 2001 From: Lukas Waslowski Date: Sat, 13 Sep 2025 02:34:26 +0200 Subject: [PATCH 1/9] Add documentation for new Alternative selector --- source/_docs/blueprint/selectors.markdown | 92 +++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index 691f7b5afc77..0660f633aece 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -17,6 +17,7 @@ The following selectors are currently available: - [Action selector](#action-selector) - [Add-on selector](#add-on-selector) +- [Alternative selector](#alternative-selector) - [Area selector](#area-selector) - [Attribute selector](#attribute-selector) - [Assist pipeline selector](#assist-pipeline-selector) @@ -102,6 +103,97 @@ addon: The output of this selector is the slug of the selected add-on. For example: `core_ssh`. +## Alternative selector + +The alternative selector allows choosing between multiple mutually exclusive sets of parameters. This is useful e.g. for choosing & configuring a DNS provider. + +```yaml +alternative: + aws: + label: Amazon Web Services (AWS) + fields: + access_key_id: + label: AWS Access Key ID + required: true + selector: + text: + secret_access_key: + label: AWS Secret Access Key + selector: + text: + azure: + label: Microsoft Azure + fields: + azure_config: + label: Azure Configuration + selector: + object: {} + cloudflare: + fields: + api_key: + label: Cloudflare API Key + selector: + text: + api_token: str? + label: Cloudflare API Token + selector: + text: + email: + label: Cloudflare Email Address + selector: + text: +``` + +The output of this selector is a YAML object. For example, given the configuration above: + +``` +aws: + access_key_id: "abc" + secret_access_key: "def" +``` + +{% configuration alternative %} +options: + description: > + List of mutually exclusive options. + type: map + required: true + keys: + label: + description: The label of the option + required: false + type: string + fields: + description: > + List of fields for this option + type: map + required: false + keys: + label: + description: The label of the field + required: false + type: string + selector: + description: The selector to use for this field. It can be any available selector. + required: true + type: string +translation_key: + description: > + Allows translations provided by an integration where `translation_key` + is the translation key that is providing the selector option strings + translation. See the documentation on + [Backend Localization](https://developers.home-assistant.io/docs/internationalization/core/#selectors) + for more information. + type: string + required: false +multiple: + description: > + Allows selecting multiple options. If set to `true`, the resulting value of this selector will be a list instead of a single string value. This option is only used if `fields` option set. + type: boolean + required: false + default: false +{% endconfiguration %} + ## Area selector The area selector shows an area finder that can pick a single or multiple areas From 057ef25a25f4838af1621ffaba7f8317fcdc30b3 Mon Sep 17 00:00:00 2001 From: Lukas Waslowski Date: Sat, 13 Sep 2025 03:31:56 +0200 Subject: [PATCH 2/9] fix: Add language to fenced code block --- source/_docs/blueprint/selectors.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index 0660f633aece..bf593425b4c6 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -144,9 +144,9 @@ alternative: text: ``` -The output of this selector is a YAML object. For example, given the configuration above: +The output of this selector is a YAML object. For example, given the configuration above, one possible output would look like this: -``` +```yaml aws: access_key_id: "abc" secret_access_key: "def" From 0f566209790006b7995bb69c18820b333bddeb59 Mon Sep 17 00:00:00 2001 From: Lukas Waslowski Date: Sat, 13 Sep 2025 03:41:30 +0200 Subject: [PATCH 3/9] fix: Add `alternative.options` field in example --- source/_docs/blueprint/selectors.markdown | 67 ++++++++++++----------- 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index bf593425b4c6..3d1a7784a867 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -109,39 +109,40 @@ The alternative selector allows choosing between multiple mutually exclusive set ```yaml alternative: - aws: - label: Amazon Web Services (AWS) - fields: - access_key_id: - label: AWS Access Key ID - required: true - selector: - text: - secret_access_key: - label: AWS Secret Access Key - selector: - text: - azure: - label: Microsoft Azure - fields: - azure_config: - label: Azure Configuration - selector: - object: {} - cloudflare: - fields: - api_key: - label: Cloudflare API Key - selector: - text: - api_token: str? - label: Cloudflare API Token - selector: - text: - email: - label: Cloudflare Email Address - selector: - text: + options: + aws: + label: Amazon Web Services (AWS) + fields: + access_key_id: + label: AWS Access Key ID + required: true + selector: + text: + secret_access_key: + label: AWS Secret Access Key + selector: + text: + azure: + label: Microsoft Azure + fields: + azure_config: + label: Azure Configuration + selector: + object: {} + cloudflare: + fields: + api_key: + label: Cloudflare API Key + selector: + text: + api_token: str? + label: Cloudflare API Token + selector: + text: + email: + label: Cloudflare Email Address + selector: + text: ``` The output of this selector is a YAML object. For example, given the configuration above, one possible output would look like this: From c4a198f4ce156925e254c9d5980a3b775b016786 Mon Sep 17 00:00:00 2001 From: Lukas Waslowski Date: Sat, 13 Sep 2025 03:45:16 +0200 Subject: [PATCH 4/9] fix: Add punctuation. --- source/_docs/blueprint/selectors.markdown | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index 3d1a7784a867..a900d4099866 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -161,17 +161,17 @@ options: required: true keys: label: - description: The label of the option + description: The label of the option. required: false type: string fields: description: > - List of fields for this option + List of fields for this option. type: map required: false keys: label: - description: The label of the field + description: The label of the field. required: false type: string selector: From a68624d181edb64ea4107baaafb355879c676e3b Mon Sep 17 00:00:00 2001 From: Lukas Waslowski Date: Sat, 13 Sep 2025 13:05:03 +0200 Subject: [PATCH 5/9] Add `discriminator_field` to Alternative selector --- source/_docs/blueprint/selectors.markdown | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index a900d4099866..4899b4dfd0dd 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -153,6 +153,22 @@ aws: secret_access_key: "def" ``` +When a `discriminator_field` is specified, the output would look this instead: + +```yaml +# Modified schema: +# +# alternative: +# discriminator_field: provider +# options: +# aws: { ... } +# azure: { ... } +# cloudflare: { ... } +provider: aws +access_key_id: "abc" +secret_access_key: "def" +``` + {% configuration alternative %} options: description: > @@ -178,6 +194,12 @@ options: description: The selector to use for this field. It can be any available selector. required: true type: string +discriminator_field: + description: > + The field to use as the discriminator, for example `type` or `action`. If not set, + the value will instead be wrapped in a dict whose single key is used as the discriminator. + type: string + required: false translation_key: description: > Allows translations provided by an integration where `translation_key` From 022c58273d7b3462d03df93c8d51e425a9714695 Mon Sep 17 00:00:00 2001 From: Lukas Waslowski Date: Sun, 14 Sep 2025 11:14:20 +0200 Subject: [PATCH 6/9] Add "See also" links to Alternative/Object/Select selector --- source/_docs/blueprint/selectors.markdown | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index 4899b4dfd0dd..6bd0071f19f5 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -105,6 +105,8 @@ For example: `core_ssh`. ## Alternative selector +_See also: [Object selector](#object-selector) and [Select selector](#select-selector)_ + The alternative selector allows choosing between multiple mutually exclusive sets of parameters. This is useful e.g. for choosing & configuring a DNS provider. ```yaml @@ -1302,6 +1304,8 @@ number: ## Object selector +_See also: [Alternative selector](#alternative-selector)_ + The object selector can be used to input arbitrary data in YAML form. This is useful for e.g. lists and dictionaries containing data for actions. The value of the input will contain the provided data. When used without options, the selector will accept a free form object. @@ -1427,6 +1431,8 @@ The output of this selector is a list with the three (RGB) color value, for exam ## Select selector +_See also: [Alternative selector](#alternative-selector)_ + The select selector shows a list of available options from which the user can choose. The value of the input contains the value of the selected option. Only a single option can be selected at a time. ![Screenshot of a select selector](/images/blueprints/selector-select.png) From e47247522f09770966992c85bc58900158493b90 Mon Sep 17 00:00:00 2001 From: Lukas Waslowski Date: Sun, 14 Sep 2025 11:19:15 +0200 Subject: [PATCH 7/9] Add to "See also" paragraphs --- source/_docs/blueprint/selectors.markdown | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index 6bd0071f19f5..fa04361154e7 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -105,7 +105,7 @@ For example: `core_ssh`. ## Alternative selector -_See also: [Object selector](#object-selector) and [Select selector](#select-selector)_ +_See also: [Object selector](#object-selector) and [Select selector](#select-selector)_ The alternative selector allows choosing between multiple mutually exclusive sets of parameters. This is useful e.g. for choosing & configuring a DNS provider. @@ -1304,7 +1304,7 @@ number: ## Object selector -_See also: [Alternative selector](#alternative-selector)_ +_See also: [Alternative selector](#alternative-selector)_ The object selector can be used to input arbitrary data in YAML form. This is useful for e.g. lists and dictionaries containing data for actions. The value of the input will contain the provided data. @@ -1431,7 +1431,7 @@ The output of this selector is a list with the three (RGB) color value, for exam ## Select selector -_See also: [Alternative selector](#alternative-selector)_ +_See also: [Alternative selector](#alternative-selector)_ The select selector shows a list of available options from which the user can choose. The value of the input contains the value of the selected option. Only a single option can be selected at a time. From 6a41156d75791a841f964cadfbd5b8c2c3908774 Mon Sep 17 00:00:00 2001 From: Lukas Waslowski Date: Sun, 14 Sep 2025 11:34:08 +0200 Subject: [PATCH 8/9] Update selectors.markdown --- source/_docs/blueprint/selectors.markdown | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index fa04361154e7..ab55e6a7b7f6 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -202,6 +202,13 @@ discriminator_field: the value will instead be wrapped in a dict whose single key is used as the discriminator. type: string required: false +multiple: + description: > + Allows adding multiple objects. If set to `true`, the resulting value + of this selector will be a list instead of a single map value. + type: boolean + required: false + default: false translation_key: description: > Allows translations provided by an integration where `translation_key` @@ -211,9 +218,9 @@ translation_key: for more information. type: string required: false -multiple: +sort: description: > - Allows selecting multiple options. If set to `true`, the resulting value of this selector will be a list instead of a single string value. This option is only used if `fields` option set. + Display options in alphabetical order. type: boolean required: false default: false From 2cc26502788044b794b3693056117d3bcf529be2 Mon Sep 17 00:00:00 2001 From: Lukas Waslowski Date: Mon, 15 Sep 2025 12:32:34 +0200 Subject: [PATCH 9/9] Convert `options` config field of Object selector to list --- source/_docs/blueprint/selectors.markdown | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index ab55e6a7b7f6..2a59a1be2bad 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -112,7 +112,7 @@ The alternative selector allows choosing between multiple mutually exclusive set ```yaml alternative: options: - aws: + - value: aws label: Amazon Web Services (AWS) fields: access_key_id: @@ -124,14 +124,14 @@ alternative: label: AWS Secret Access Key selector: text: - azure: + - value: azure label: Microsoft Azure fields: azure_config: label: Azure Configuration selector: object: {} - cloudflare: + - value: cloudflare fields: api_key: label: Cloudflare API Key @@ -175,9 +175,13 @@ secret_access_key: "def" options: description: > List of mutually exclusive options. - type: map + type: list required: true keys: + value: + description: The key of the option. + required: true + type: string label: description: The label of the option. required: false