mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-21 08:16:53 +00:00
Document blueprint input sections (#32769)
* Document blueprint input sections * Update schema.markdown * Update schema.markdown * Update schema.markdown * Update schema.markdown * Update schema.markdown * Update source/_docs/blueprint/schema.markdown --------- Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
This commit is contained in:
karwosts
GitHub
parent
3437d9eab2
commit
a41757f6c8
@ -79,34 +79,12 @@ homeassistant:
|
||||
required: false
|
||||
input:
|
||||
description: >
|
||||
A dictionary of defined user inputs. These are the input fields that the
|
||||
A dictionary of defined user inputs or sections. These are the input fields that the
|
||||
consumer of your blueprint can provide using YAML definition, or via
|
||||
a configuration form in the UI.
|
||||
a configuration form in the UI. Sections provide a way to visually group a set of
|
||||
related inputs (see below).
|
||||
type: map
|
||||
required: false
|
||||
keys:
|
||||
name:
|
||||
description: The name of the input field.
|
||||
type: string
|
||||
required: false
|
||||
description:
|
||||
description: >
|
||||
A short description of the input field. Keep this short and descriptive.
|
||||
The description can include [Markdown](https://commonmark.org/help/).
|
||||
type: string
|
||||
required: false
|
||||
selector:
|
||||
description: >
|
||||
The [selector](/docs/blueprint/selectors/) to use for this input. A
|
||||
selector defines how the input is displayed in the frontend UI.
|
||||
type: selector
|
||||
required: false
|
||||
default:
|
||||
description: >
|
||||
The default value of this input, in case the input is not provided
|
||||
by the user of this blueprint.
|
||||
type: any
|
||||
required: false
|
||||
{% endconfiguration %}
|
||||
|
||||
### Blueprint inputs
|
||||
@ -118,6 +96,34 @@ These inputs can be of any type (string, boolean, list, dictionary). They can ha
|
||||
a default value and also provide a [selector](/docs/blueprint/selectors/) that
|
||||
ensures a matching input field in the user interface.
|
||||
|
||||
A blueprint input has the following configuration:
|
||||
|
||||
{% configuration %}
|
||||
name:
|
||||
description: The name of the input field.
|
||||
type: string
|
||||
required: false
|
||||
description:
|
||||
description: >
|
||||
A short description of the input field. Keep this short and descriptive.
|
||||
The description can include [Markdown](https://commonmark.org/help/).
|
||||
type: string
|
||||
required: false
|
||||
selector:
|
||||
description: >
|
||||
The [selector](/docs/blueprint/selectors/) to use for this input. A
|
||||
selector defines how the input is displayed in the frontend UI.
|
||||
type: selector
|
||||
required: false
|
||||
default:
|
||||
description: >
|
||||
The default value of this input, in case the input is not provided
|
||||
by the user of this blueprint.
|
||||
type: any
|
||||
required: false
|
||||
|
||||
{% endconfiguration %}
|
||||
|
||||
Each input field can be referred to, outside of the blueprint metadata, using
|
||||
the `!input` custom YAML tag.
|
||||
|
||||
@ -140,6 +146,70 @@ It is then up to the user to find out what to enter there. Blueprints that come
|
||||
|
||||
A blueprint can have as many inputs as you like.
|
||||
|
||||
### Blueprint input sections
|
||||
|
||||
One or more input sections can be added under the main `input` key. Each section visually groups the inputs in that section,
|
||||
allows an optional description, and optionally allows for collapsing those inputs.
|
||||
|
||||
A section is differentiated from an input by the presence of an additional `input` key within that section.
|
||||
|
||||
<div class='note warning'>
|
||||
Input sections are a new feature in version 2024.6. Set the `min_version` for the blueprint to at least this version if using input sections. Otherwise, the blueprint will generate errors on older versions.
|
||||
</div>
|
||||
|
||||
The full configuration for a section is below:
|
||||
|
||||
{% configuration %}
|
||||
|
||||
name:
|
||||
description: A name for the section. If omitted the key of the section is used.
|
||||
type: string
|
||||
required: false
|
||||
icon:
|
||||
description: An icon to display next to the name of the section.
|
||||
type: string
|
||||
required: false
|
||||
description:
|
||||
description: >
|
||||
An optional description of this section, which will be displayed at the top of the section.
|
||||
The description can include [Markdown](https://commonmark.org/help/).
|
||||
type: string
|
||||
required: false
|
||||
collapsed:
|
||||
description: If `true`, the section will be collapsed by default. Useful for optional or less important inputs. All collapsed inputs must also have a defined `default` before they can be hidden.
|
||||
type: boolean
|
||||
default: false
|
||||
required: false
|
||||
input:
|
||||
description: >
|
||||
A dictionary of defined user inputs within this section.
|
||||
type: map
|
||||
required: true
|
||||
|
||||
{% endconfiguration %}
|
||||
|
||||
|
||||
|
||||
The following example shows a blueprint with some inputs in a section:
|
||||
|
||||
```yaml
|
||||
blueprint:
|
||||
name: Example sections blueprint
|
||||
description: Example showing a section
|
||||
input:
|
||||
base_input:
|
||||
name: An input not in the section
|
||||
my_section:
|
||||
name: My Section
|
||||
icon: mdi:cog
|
||||
description: These options control a specific feature of this blueprint
|
||||
input:
|
||||
my_input:
|
||||
name: Example input
|
||||
my_input_2:
|
||||
name: 2nd example input
|
||||
```
|
||||
|
||||
### Blueprint inputs in templates
|
||||
|
||||
The inputs are available as custom YAML tags, but not as template variables.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user