Extend Blueprint documentation (#15873)

Co-authored-by: Paulus Schoutsen <balloob@gmail.com>

plugins/configuration.rb

@@ -5,11 +5,13 @@ module Jekyll
       'device_class' => '/docs/configuration/customizing-devices/#device-class',
       'template'     => '/docs/configuration/templating/',
       'icon'         => '/docs/configuration/customizing-devices/#icon',
+      'selector'     => '/docs/blueprint/selectors/',
     }
 
     TYPES = [
       'action', 'boolean', 'string', 'integer', 'float', 'time', 'template',
-      'device_class', 'icon', 'map', 'list', 'date', 'datetime', 'any'
+      'device_class', 'icon', 'map', 'list', 'date', 'datetime', 'any',
+      'selector',
     ]
 
     MIN_DEFAULT_LENGTH = 30

source/_docs/blueprint/schema.markdown

@@ -3,37 +3,132 @@ title: "Blueprint schema"
 description: "The schema for a valid blueprint."
 ---
 
-Schema of the blueprint metadata:
+The configuration schema of a blueprint consists of 2 parts:
 
-```ts
+- The blueprint high-level metadata, like its name and a description and
-interface BlueprintInput {
+  the input the blueprint needs from the user.
-  name?: string;
+- The schema of the thing the blueprint describes.
-  description?: string;
-  selector?: Selector;
-  default?: any;
-}
 
-interface Blueprint {
+The first part is referred to as the blueprint schema and contains mainly the
-  blueprint: {
+blueprint's metadata. The second part depends on what the blueprint is for.
-    domain: string;
+
-    name: string;
+For example, in the case of creating a blueprint for an automation, the full
-    input?: Record<string, BlueprintInput | null>;
+schema for an [automation](/docs/automation/yaml/) applies.
-    description?: string;
+
-    source_url?: string;
+This page is mainly set up to describe the configuration schema of the
-  }
+blueprint metadata. Try our [blueprint tutorial](/docs/blueprint/tutorial/)
-}
+in case you are interested in creating your first blueprint.
+
+## The blueprint schema
+
+The only requirement for a blueprint is a name. In its most basic form,
+a blueprint would look like:
+
+```yaml
+blueprint:
+  name: Example blueprint
+  domain: automation
 ```
 
-The [built-in blueprints](https://github.com/home-assistant/core/tree/dev/homeassistant/components/automation/blueprints) are great examples.
+And this is already a valid blueprint. But typically, one would need
+more. For example, user inputs or a description to describe the blueprint's
+functionality.
 
-Here is the built-in motion light blueprint:
+This is the full blueprint schema:
+
+{% configuration %}
+name:
+  description: The name of the blueprint. Keep this short and descriptive.
+  type: string
+  required: true
+description:
+  description: >
+    The description of the blueprint. While optional, this field is highly
+    recommended. For example, to describe what the blueprint does, or tell more
+    about the options inputs of the blueprint provide. New lines in this
+    description are displayed in the UI, so paragraphs are allowed.
+  type: string
+  required: false
+domain:
+  description: >
+    The domain name this blueprint provides a blueprint for. Currently, only
+    `automation` is supported.
+  type: string
+  required: true
+input:
+  description: >
+    A dictionary of defined user inputs. These are the input fields that the
+    consumer of your blueprint can provide using YAML definition, or via
+    a configuration form in the UI.
+  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.
+      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
+
+As written in the above schema, a blueprint can accept one (or multiple)
+inputs from the blueprint consumer.
+
+These inputs can be of any type (string, boolean, list, dictionary), can have
+a default value and also provide a [selector](/docs/blueprint/selectors/) that
+ensures a matching input field in the user interface.
+
+Each input field can be referred to, outside of the blueprint metadata, using
+the `!input` custom tag.
+
+The following example shows a minimal blueprint with a single input:
+
+```yaml
+blueprint:
+  name: Example blueprint
+  description: Example showing an input
+  input:
+    my_input:
+      name: Example input
+```
+
+In the above example, `my_input` is the identifier of the input, that can be
+referred to later on using the `!input my_input` custom tag.
+
+In this example, no `selector` was provided. In this case, if this blueprint
+was used in the user interface, a text input field would be shown to the user.
+
+A blueprint can have as many inputs as you like.
+
+## Example blueprints
+
+The [built-in blueprints][blueprint-built-in]
+are great examples to get a bit of a feeling of how blueprints work.
+
+Here is the built-in motion light automation blueprint:
 
 ```yaml
 blueprint:
   name: Motion-activated Light
   description: Turn on a light when motion is detected.
   domain: automation
-  source_url: https://github.com/home-assistant/core/blob/dev/homeassistant/components/automation/blueprints/motion_light.yaml
   input:
     motion_entity:
       name: Motion Sensor
@@ -79,5 +174,10 @@ action:
   - delay: !input no_motion_wait
   - service: light.turn_off
     target: !input light_target
-
 ```
+
+Additional examples, provided by the community, can be found on the
+[community forum][blueprint-tag].
+
+[blueprint-built-in]: https://github.com/home-assistant/core/tree/dev/homeassistant/components/automation/blueprints
+[blueprint-tag]: https://community.home-assistant.io/tag/blueprint

source/_docs/blueprint/selectors.markdown

@@ -3,112 +3,490 @@ title: "Selectors"
 description: "Documentation on available selectors."
 ---
 
-Selectors can be used to specify what values are accepted for an input.
+Selectors can be used to specify what values are accepted for a blueprint
+input. The selector also defines how the input is shown in the user interface.
 
-## Entity Selector
+Some selectors can, for example, show a toggle button to turn something
+on or off, while another select can filter a list of devices to show
+only devices that have motion-sensing capabilities.
 
-Pick an entity. The chosen value will be an entity ID.
+Having the good selectors set on your blueprint automations inputs makes a
+blueprint easier to use from the UI.
 
-```yaml
+The following selectors are currently available:
-entity:
-  # All fields are optional
-  integration: zha
-  domain: binary_sensor
-  device_class: motion
-```
 
-## Device Selector
+- [Action selector](#action-selector)
+- [Area selector](#area-selector)
+- [Boolean selector](#boolean-selector)
+- [Device selector](#device-selector)
+- [Entity selector](#entity-selector)
+- [Number selector](#number-selector)
+- [Target selector](#target-selector)
+- [Time selector](#time-selector)
 
-Pick a device. The chosen value will be a device ID.
+If no selector is defined, a text input for a single line will be shown.
 
-```yaml
+## Action selector
-device:
-  # All fields are optional
-  integration: zha
-  manufacturer: Philips
-  model: Remote X1
-  entity: <see entity selector>
-```
 
-The `entity` option will limit devices that have an entity matching the entity selector.
+The action selector allows the user to input one or more sequences of actions.
+On the user interface, the action part of the automation editor will be shown.
+The value of the input will contain a list of actions to perform.
 
+![Screenshot of an action selector](/images/blueprints/selector-action.png)
 
-## Target Selector
+This selector does not have any other options; therefore, it only has its key.
-
-Pick a target for service calls. Will be a dictionary containing optionally `entity_id`, `device_id` or `area_id` keys with the picked values.
-
-Meant to be specified as the `target` property in a call service step in a script sequence.
-
-```yaml
-target:
-  # All fields are optional
-  entity:
-    integration: zha
-    domain: binary_sensor
-    device_class: motion
-
-  device:
-    integration: zha
-    manufacturer: Philips
-    model: Remote X1
-```
-
-## Number Selector
-
-Pick a number.
-
-```yaml
-number:
-  # Required
-  min: 0
-  max: 100
-  # Optional
-  step: 5
-  unit_of_measurement: seconds
-  mode: slider  # other valid value 'box'
-```
-
-## Boolean Selector
-
-Pick true or false.
-
-```yaml
-boolean:
-```
-
-## Time Selector
-
-Pick a time.
-
-```yaml
-time:
-```
-
-## Action Selector
-
-Enter a script action. Will be a list of action steps.
-
-Meant to be specified as the `action` of an automation or any syntax that accepts actions, like `choose`.
 
 ```yaml
 action:
 ```
 
+## Area selector
 
-## Area Selector
+The area selector shows an area finder that can pick a single area. The value
+of the input will be the area ID of the user-selected area.
 
-Pick an area. The chosen value will be an area ID.
+An area selector can filter the list of areas, based on properties of the devices
+and entities that are assigned to those areas. For example, the areas list could
+be limited to areas with entities provided by the [ZHA](/integration/zha)
+integration.
+
+In its most basic form, it doesn't require any options, which will show
+all areas.
+
+```yaml
+area:
+```
+
+{% configuration area %}
+device:
+  description: >
+    When device options are provided, the list of areas is filtered by areas
+    that at least provide one device that matches the given conditions.
+  type: map
+  keys:
+    integration:
+      description: >
+        Can be set to an integration domain. Limits the list of areas that
+        provide devices by the set integration domain, for example,
+        [`zha`](/integrations/zha).
+      type: string
+      required: false
+    manufacturer:
+      description: >
+        When set, it limits the list of areas that provide devices by the set
+        manufacturer name.
+      type: string
+      required: false
+    model:
+      description: >
+        When set, it limits the list of areas that provide devices that have
+        the set model.
+      type: string
+      required: false
+entity:
+  description: >
+    When entity options are provided, the list of areas is filtered by areas
+    that at least provide one entity that matches the given conditions.
+  type: map
+  required: false
+  keys:
+    integration:
+      description: >
+        Can be set to an integration domain. Limits the list of areas that
+        provide entities by the set integration domain, for example,
+        [`zha`](/integrations/zha).
+      type: string
+      required: false
+    domain:
+      description: >
+        Limits the list of areas that provide entities of a certain domain,
+        for example, [`light`](/integrations/light) or
+        [`binary_sensor`](/integrations/binary_sensor).
+      type: string
+      required: false
+    device_class:
+      description: >
+        Limits the list of areas to areas that have entities with a certain
+        device class, for example, `motion` or `window`.
+      type: device_class
+      required: false
+{% endconfiguration %}
+
+### Example area selectors
+
+An example area selector only shows areas that provide one or more lights
+provided by the [ZHA](/integrations/zha) integration.
 
 ```yaml
 area:
-  # All fields are optional
   entity:
+    integration: zha
+    domain: light
+```
+
+Another example uses the area selector, which only shows areas that provide one
+or more remote controls provided by the [deCONZ](/integrations/deconz)
+integration.
+
+```yaml
+area:
+  device:
+    integration: deconz
+    manufacturer: IKEA of Sweden
+    model: TRADFRI remote control
+```
+
+## Boolean selector
+
+The boolean selector shows a toggle that allows the user to turn on or off
+the selected option. The input's value will contain the boolean value of that
+toggle as a boolean value, being `true` or `false`.
+
+![Screenshot of a boolean selector](/images/blueprints/selector-boolean.png)
+
+The boolean selector can be incredibly useful for adding feature switches
+to, for example, blueprints.
+
+This selector does not have any other options; therefore, it only has its key.
+
+```yaml
+boolean:
+```
+
+## Device selector
+
+The device selector shows a device finder that can pick a single device.
+The value of the input will contain the device ID of the user-selected device.
+
+A device selector can filter the list of devices, based on things like the
+manufacturer or model of the device, the entities the device provides or based
+on the domain that provided the device.
+
+![Screenshot of an device selector](/images/blueprints/selector-device.png)
+
+In its most basic form, it doesn't require any options, which will show
+all devices.
+
+```yaml
+device:
+```
+
+{% configuration device %}
+integration:
+  description: >
+    Can be set to an integration domain. Limits the list of devices to devices
+    provided by the set integration domain.
+  type: string
+  required: false
+manufacturer:
+  description: >
+    When set, it limits the list of devices to devices provided by the set
+    manufacturer name.
+  type: string
+  required: false
+model:
+  description: >
+    When set, it limits the list of devices to devices that have the set model.
+  type: string
+  required: false
+entity:
+  description: >
+    When entity options are provided, the list of devices is filtered by devices
+    that at least provide one entity that matches the given conditions.
+  type: map
+  required: false
+  keys:
+    integration:
+      description: >
+        Can be set to an integration domain. Limits the list of devices that
+        provide entities by the set integration domain, for example,
+        [`zha`](/integrations/zha).
+      type: string
+      required: false
+    domain:
+      description: >
+        Limits the list of devices that provide entities of a certain domain,
+        for example, [`light`](/integrations/light)
+        or [`binary_sensor`](/integrations/binary_sensor).
+      type: string
+      required: false
+    device_class:
+      description: >
+        Limits the list of entities to entities that have a certain device
+        class, for example, `motion` or `window`.
+      type: device_class
+      required: false
+{% endconfiguration %}
+
+### Example device selector
+
+An example entity selector that, will only show devices that are:
+
+- Provided by the [deCONZ](/integration/deconz) integration.
+- Are a Philips Hue Remote of Model RWL021.
+- Provide a battery [sensor](/integration/sensor).
+
+And this is what is looks like in YAML:
+
+```yaml
+device:
+  integration: deconz
+  manufacturer: Philips
+  model: RWL021
+  entity:
+    domain: sensor
+    device_class: battery
+```
+
+## Entity selector
+
+The entity selector shows an entity finder that can pick a single entity.
+The value of the input will contain the entity ID of user-selected entity.
+
+An entity selector can filter the list of entities, based on things like the
+class of the device, the domain of the entity or the domain that provided the
+entity.
+
+![Screenshot of an entity selector](/images/blueprints/selector-entity.png)
+
+In its most basic form, it doesn't require any options, which will show
+all entities.
+
+```yaml
+entity:
+```
+
+{% configuration entity %}
+integration:
+  description: >
+    Can be set to an integration domain. Limits the list of entities to entities
+    provided by the set integration domain, for example,
+    [`zha`](/integrations/zha).
+  type: string
+  required: false
+domain:
+  description: >
+    Limits the list of entities to entities of a certain domain, for example,
+    [`light`](/integrations/light) or
+    [`binary_sensor`](/integrations/binary_sensor).
+  type: string
+  required: false
+device_class:
+  description: >
+    Limits the list of entities to entities that have a certain device class,
+    for example, `motion` or `window`.
+  type: device_class
+  required: false
+{% endconfiguration %}
+
+### Example entity selector
+
+An example entity selector that, will only show entities that are:
+
+- Provided by the [ZHA](/integration/zha) integration.
+- From the [Binary Sensor](/integration/binary_sensor) domain.
+- Have presented themselves as devices of a motion device class.
+
+And this is what it looks like in YAML:
+
+```yaml
+entity:
   integration: zha
   domain: binary_sensor
   device_class: motion
-
+```
-  device:
+
-    integration: zha
+## Number selector
-    manufacturer: Philips
+
-    model: Remote X1
+The number selector shows either a number input or a slider input, that allows
+the user to specify a numeric value. The value of the input will contain
+the select value.
+
+![Screenshot of a number selector](/images/blueprints/selector-number.png)
+
+On the user interface, the input can either be in a slider or number mode.
+Both modes limit the user input by a minimal and maximum value, and can
+have a unit of measurement to go with it.
+
+In its most basic form, it requires a minimal and maximum value:
+
+```yaml
+number:
+  min: 0
+  max: 100
+```
+
+{% configuration number %}
+min:
+  description: The minimal user-settable number value.
+  type: [integer, float]
+  required: true
+max:
+  description: The maximum user-settable number value.
+  type: [integer, float]
+  required: true
+step:
+  description: The step value of the number value.
+  type: [integer, float]
+  required: false
+  default: 1
+unit_of_measurement:
+  description: Unit of measurement in which the number value is expressed in.
+  type: string
+  required: false
+mode:
+  description: This can be either `box` or `slider` mode.
+  type: string
+  required: false
+  default: box
+{% endconfiguration %}
+
+### Example number selectors
+
+An example number selector that allows a user a percentage, directly in a
+regular number input box.
+
+```yaml
+number:
+  min: 0
+  max: 100
+  unit_of_measurement: "%"
+```
+
+A more visual variant of this example could be achieved using a slider.
+This can be helpful for things like allowing the user to select a
+brightness level of lights. Additionally, this example changes the brightness
+in incremental steps of 10%.
+
+```yaml
+number:
+  min: 0
+  max: 100
+  step: 10
+  unit_of_measurement: "%"
+  mode: slider
+```
+
+## Target selector
+
+The target selector is a rather special selector, allowing the user to selector
+targeted entities, devices or areas for service calls. The value of
+the input will contain a special target format, that is accepted by
+service calls.
+
+The selectable targets can be filtered, based on entity or device properties.
+Areas are only selectable as a target, if some entities or devices match
+those properties in those areas.
+
+![Screenshot of a target selector](/images/blueprints/selector-target.png)
+
+Its most basic form, doesn't require any options, which will allow the
+user to target any entity, device or area available in the system.
+
+```yaml
+target:
+```
+
+{% configuration target %}
+device:
+  description: >
+    When device options are provided, the targets are limited by devices
+    that at least match the given conditions.
+  type: map
+  keys:
+    integration:
+      description: >
+        Can be set to an integration domain. Limits the device targets that
+        are provided devices by the set integration domain, for example,
+        [`zha`](/integrations/zha).
+      type: string
+      required: false
+    manufacturer:
+      description: >
+        When set, it limits the targets to devices provided by the set
+        manufacturer name.
+      type: string
+      required: false
+    model:
+      description: When set, it limits the targets to devices by the set model.
+      type: string
+      required: false
+entity:
+  description: >
+    When entity options are provided, the targets are limited by entities
+    that at least match the given conditions.
+  type: map
+  required: false
+  keys:
+    integration:
+      description: >
+        Can be set to an integration domain. Limits targets to entities
+        provided by the set integration domain, for example,
+        [`zha`](/integrations/zha).
+      type: string
+      required: false
+    domain:
+      description: >
+        Limits the targets to entities of a certain domain,
+        for example, [`light`](/integrations/light) or
+        [`binary_sensor`](/integrations/binary_sensor).
+      type: string
+      required: false
+    device_class:
+      description: >
+        Limits the targets to entities with a certain
+        device class, for example, `motion` or `window`.
+      type: device_class
+      required: false
+{% endconfiguration %}
+
+<div class='note'>
+
+Targets are meant to be used with the `target` property of a service call in
+a script sequence. For example:
+
+```yaml
+action:
+  - service: light.turn_on
+    target: !input lights
+```
+
+</div>
+
+### Example target selectors
+
+An example target selector that only shows targets that at least provide one
+or more lights, provided by the [ZHA](/integrations/zha) integration.
+
+```yaml
+target:
+  entity:
+    integration: zha
+    domain: light
+```
+
+Another example using the target selector, which only shows targets that
+provide one or more remote controls, provided by the
+[deCONZ](/integrations/deconz) integration.
+
+```yaml
+target:
+  device:
+    integration: deconz
+    manufacturer: IKEA of Sweden
+    model: TRADFRI remote control
+```
+
+## Time selector
+
+The time selector shows a time input that allows the user to specify a time
+of the day. The value of the input will contain the time in 24-hour format,
+for example, `23:59:59`.
+
+![Screenshot of a time selector](/images/blueprints/selector-time.png)
+
+This selector does not have any other options; therefore, it only has its key.
+
+```yaml
+time:
 ```

source/_docs/blueprint/tutorial.markdown

@@ -12,6 +12,7 @@ For this tutorial, we use a simple automation. The process for converting a comp
 To create a blueprint, we first need to have a working automation. The automation we're going to use in this tutorial, which controls a light based on a motion sensor, looks like this:
 
 {% raw %}
+
 ```yaml
 trigger:
   platform: state
@@ -27,6 +28,7 @@ action:
   target:
     entity_id: light.kitchen
 ```
+
 {% endraw %}
 
 ## Create the blueprint file
@@ -65,6 +67,7 @@ For the light, we can offer some more flexibility. We want to allow the user to
 Inputs are not limited to strings. They can contain complex objects too. So in this case, we're going to mark the whole `target` as input:
 
 {% raw %}
+
 ```yaml
 action:
   service: >
@@ -75,6 +78,7 @@ action:
     {% endif %}
   target: !input target_light
 ```
+
 {% endraw %}
 
 ## Add the inputs to the metadata
@@ -164,6 +168,7 @@ By limiting our blueprint to working with lights and motion sensors, we unlock a
 After we have added all the steps, our blueprint will look like this:
 
 {% raw %}
+
 ```yaml
 blueprint:
   name: Motion Light Tutorial
@@ -198,6 +203,7 @@ action:
     {% endif %}
   target: !input target_light
 ```
+
 {% endraw %}
 
 ## Use it via the UI