From 10253cfd3d0ec75aa14dbfa03594d949506ae810 Mon Sep 17 00:00:00 2001 From: Paul Bottein Date: Thu, 9 Mar 2023 12:43:02 +0100 Subject: [PATCH] Add documentation for entity and device filters (#26145) --- source/_docs/blueprint/selectors.markdown | 170 +++++++++++++--------- 1 file changed, 99 insertions(+), 71 deletions(-) diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index e4f0b6a9c12..f81b5e432a3 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -115,8 +115,9 @@ 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 + that at least provide one device that matches the given conditions. Can be + either a object or a list of object. + type: list keys: integration: description: > @@ -140,8 +141,9 @@ device: 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 + that at least provide one entity that matches the given conditions. Can be + either a object or a list of object. + type: list required: false keys: integration: @@ -162,8 +164,10 @@ entity: 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 + device class(es), for example, `motion` or `window`. Can be either a string + with a single device_class, or a list of string device_class to limit + the selection to. + type: [device_class, list] required: false multiple: description: > @@ -208,10 +212,9 @@ integration. Multiple areas can be selected. area: multiple: true device: - multiple: true - integration: deconz - manufacturer: IKEA of Sweden - model: TRADFRI remote control + - integration: deconz + manufacturer: IKEA of Sweden + model: TRADFRI remote control ``` ## Attribute selector @@ -354,28 +357,12 @@ 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 + that at least provide one entity that matches the given conditions. Can be + either a object or a list of object. + type: list required: false keys: integration: @@ -397,8 +384,35 @@ entity: device_class: description: > Limits the list of entities to entities that have a certain device - class, for example, `motion` or `window`. - type: device_class + class(es), for example, `motion` or `window`. Can be either a string + with a single device_class, or a list of string device_class to limit + the selection to. + type: [device_class, list] + required: false +filter: + description: > + When filter options are provided, the list of devices is filtered by devices + that at least provide one entity that matches the given conditions. Can be either + a object or a list of object. + type: list + required: false + keys: + 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 multiple: description: > @@ -433,12 +447,13 @@ And this is what is looks like in YAML: ```yaml device: - integration: deconz - manufacturer: Philips - model: RWL021 + filter: + - integration: deconz + manufacturer: Philips + model: RWL021 entity: - domain: sensor - device_class: battery + - domain: sensor + device_class: battery ``` ## Duration selector @@ -499,28 +514,37 @@ include_entities: description: List of entity IDs to limit the selectable list to. type: list required: false -integration: +filter: 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(s), for example, - [`light`](/integrations/light) or - [`binary_sensor`](/integrations/binary_sensor). Can be either a string - with a single domain, or a list of string domains to limit the selection - to. - type: [string, list] - 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 + When filter options are provided, the entities are limited by entities + that at least match the given conditions. Can be either a object or a list of object. + Can be either a object or a list of object. + type: list required: false + keys: + 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(s), for example, + [`light`](/integrations/light) or + [`binary_sensor`](/integrations/binary_sensor). Can be either a string + with a single domain, or a list of string domains to limit the selection + to. + type: [string, list] + required: false + device_class: + description: > + Limits the list of entities to entities that have a certain device class(es), + for example, `motion` or `window`. Can be either a string with a single device_class, + or a list of string device_class to limit the selection to. + type: [device_class, list] + required: false multiple: description: > Allows selecting multiple entities. If set to `true`, the resulting value of @@ -556,9 +580,10 @@ And this is what it looks like in YAML: ```yaml entity: multiple: true - integration: zha - domain: binary_sensor - device_class: motion + filter: + - integration: zha + domain: binary_sensor + device_class: motion ``` ## Icon selector @@ -895,8 +920,9 @@ target: device: description: > When device options are provided, the targets are limited by devices - that at least match the given conditions. - type: map + that at least match the given conditions. Can be either a object or a list + of object. + type: list keys: integration: description: > @@ -918,8 +944,9 @@ device: entity: description: > When entity options are provided, the targets are limited by entities - that at least match the given conditions. - type: map + that at least match the given conditions. Can be either a object or a list + of object. + type: list required: false keys: integration: @@ -940,9 +967,10 @@ entity: required: false device_class: description: > - Limits the targets to entities with a certain - device class, for example, `motion` or `window`. - type: device_class + Limits the targets to entities with a certain device class(es), for example, + `motion` or `window`. Can be either a string with a single device_class, + or a list of string device_class to limit the selection to. + type: [device_class, list] required: false {% endconfiguration %} @@ -967,8 +995,8 @@ or more lights, provided by the [ZHA](/integrations/zha) integration. ```yaml target: entity: - integration: zha - domain: light + - integration: zha + domain: light ``` Another example using the target selector, which only shows targets that @@ -978,9 +1006,9 @@ provide one or more remote controls, provided by the ```yaml target: device: - integration: deconz - manufacturer: IKEA of Sweden - model: TRADFRI remote control + - integration: deconz + manufacturer: IKEA of Sweden + model: TRADFRI remote control ``` ## Template selector