From 5bc442df7e207bca41538323670228f6d03d9b45 Mon Sep 17 00:00:00 2001 From: Quentame Date: Sat, 30 Mar 2024 07:01:07 +0100 Subject: [PATCH] `conditional` & `entity-filter`: add ability to filter through `entity_id` & add `entity-filter` `conditional`'s conditions (#30561) * entity-filter: add ability to filter through entity_id value * Update to latest frontend PR edits * Update to new upstream * Fix English spelling Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> --------- Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> --- source/_dashboards/conditional.markdown | 79 ++++-- source/_dashboards/entity-filter.markdown | 287 ++++++++++++++++++--- source/dashboards/badges.markdown | 288 ++++++++++++++++++++-- 3 files changed, 593 insertions(+), 61 deletions(-) diff --git a/source/_dashboards/conditional.markdown b/source/_dashboards/conditional.markdown index 3cf505e9a5e..19b188730ba 100644 --- a/source/_dashboards/conditional.markdown +++ b/source/_dashboards/conditional.markdown @@ -25,7 +25,7 @@ type: type: string conditions: required: true - description: List of conditions to check. See [available conditions](/dashboards/conditional/#card-conditions). + description: List of conditions to check. See [available conditions](#conditions-options). type: list card: required: true @@ -79,24 +79,24 @@ card: - binary_sensor.rookmelder ``` -## Card conditions +## Conditions options ### State +Tests if an entity has a specified state. + ```yaml -condition: "state" +condition: state entity: climate.thermostat state: heat ``` ```yaml -condition: "state" +condition: state entity: climate.thermostat state_not: "off" ``` -Tests if an entity has a specified state. - {% configuration %} condition: required: true @@ -108,11 +108,11 @@ entity: type: string state: required: false - description: Entity state is equal to this value. Can contain an array of states.* + description: Entity state or ID to be equal to this value. Can contain an array of states.* type: [list, string] state_not: required: false - description: Entity state is unequal to this value. Can contain an array of states.* + description: Entity state or ID to not be equal to this value. Can contain an array of states.* type: [list, string] {% endconfiguration %} @@ -123,7 +123,7 @@ state_not: Tests if an entity state matches the thresholds. ```yaml -condition: "numeric_state" +condition: numeric_state entity: sensor.outside_temperature above: 10 below: 20 @@ -140,15 +140,15 @@ entity: type: string above: required: false - description: Entity state is above this value.* + description: Entity state or ID to be above this value.* type: string below: required: false - description: Entity state is below to this value.* + description: Entity state or ID to be below this value.* type: string {% endconfiguration %} -*at least one is required (`above` or `below`) +*at least one is required (`above` or `below`), both are also possible for values between. ### Screen @@ -175,7 +175,7 @@ media_query: Specify the visibility of the card per user. ```yaml -condition: "user" +condition: user users: - 581fca7fdc014b8b894519cc531f9a04 ``` @@ -191,6 +191,57 @@ users: type: list {% endconfiguration %} +### And + +Specify that both conditions must be met. + +```yaml +condition: and +conditions: + - condition: numeric_state + above: 0 + - condition: user + users: + - 581fca7fdc014b8b894519cc531f9a04 +``` + +{% configuration %} +condition: + required: true + description: "`and`" + type: string +conditions: + required: false + description: List of conditions to check. See [available conditions](#conditions-options). + type: list +{% endconfiguration %} + +### Or + +Specify that at least one of the conditions must be met. + +```yaml +condition: or +conditions: + - condition: numeric_state + above: 0 + - condition: user + users: + - 581fca7fdc014b8b894519cc531f9a04 +``` + +{% configuration %} +condition: + required: true + description: "`or`" + type: string +conditions: + required: false + description: List of conditions to check. See [available conditions](#conditions-options). + type: list +{% endconfiguration %} + + ## Related topics -- [Dashboard cards](/dashboards/cards/) \ No newline at end of file +- [Dashboard cards](/dashboards/cards/) diff --git a/source/_dashboards/entity-filter.markdown b/source/_dashboards/entity-filter.markdown index 201e7067261..64b57545829 100644 --- a/source/_dashboards/entity-filter.markdown +++ b/source/_dashboards/entity-filter.markdown @@ -29,9 +29,13 @@ entities: required: true description: A list of entity IDs or `entity` objects, see below. type: list +conditions: + required: false + description: List of conditions to check. See [available conditions](#conditions-options).* + type: list state_filter: - required: true - description: List of strings representing states or `filter` objects, see below. + required: false + description: (legacy) List of strings representing states or filters to check. See [available legacy filters](#legacy-state-filters).* type: list card: required: false @@ -45,6 +49,8 @@ show_empty: default: true {% endconfiguration %} +*one is required (`conditions` or `state_filter`) + ### Options for entities If you define entities as objects instead of strings (by adding `entity:` before entity ID), you can add more customization and configurations: @@ -64,8 +70,9 @@ name: type: string icon: required: false - description: Overwrites icon or entity picture. + description: Overwrites icon or entity picture. You can use any icon from [Material Design Icons](https://pictogrammers.com/library/mdi/). Prefix the icon name with `mdi:`, ie `mdi:home`. type: string + default: Entity domain icon secondary_info: required: false description: "Show additional info. Values: `entity-id`, `last-changed`." @@ -74,32 +81,225 @@ format: required: false description: "How the state should be formatted. Currently only used for timestamp sensors. Valid values are: `relative`, `total`, `date`, `time` and `datetime`." type: string +conditions: + required: false + description: List of conditions to check. See [available conditions](#conditions-options).* + type: list state_filter: required: false - description: List of strings representing states or `filter` objects, see below. + description: (legacy) List of strings representing states or filters to check. See [available legacy filters](#legacy-state-filters).* type: list {% endconfiguration %} -### Options for state filter +*only one filter will be applied: `conditions` or `state_filter` if `conditions` is not present -If you define `state_filter` as objects instead of strings (by adding `value:` before your state value), you can add more customization to your filter: +## Conditions options -{% configuration %} -value: +You can specify multiple `conditions`, in which case the entity will be displayed if it matches any condition. + +### State + +Tests if an entity has a specified state. + +```yaml +type: entity-filter +entities: + - climate.thermostat_living_room + - climate.thermostat_bed_room +conditions: + - condition: state + state: heat +``` + +```yaml +type: entity-filter +entities: + - climate.thermostat_living_room + - climate.thermostat_bed_room +conditions: + - condition: state + state_not: "off" +``` + +```yaml +type: entity-filter +entities: + - sensor.gas_station_1 + - sensor.gas_station_2 + - sensor.gas_station_3 +conditions: + - condition: state + state: sensor.gas_station_lowest_price +``` + +{% configuration condition_state %} +condition: required: true - description: String representing the state. + description: "`state`" type: string -operator: +state: required: false - description: Operator to use in the comparison. Can be `==`, `<=`, `<`, `>=`, `>`, `!=`, `in`, `not in`, or `regex`. + description: Entity state or ID to be equal to this value. Can contain an array of states.* + type: [list, string] +state_not: + required: false + description: Entity state or ID to not be equal to this value. Can contain an array of states.* + type: [list, string] +{% endconfiguration %} + +*one is required (`state` or `state_not`) + +### Numeric state + +Tests if an entity state matches the thresholds. + +```yaml +type: entity-filter +entities: + - sensor.outside_temperature + - sensor.living_room_temperature + - sensor.bed_room_temperature +conditions: + - condition: numeric_state + above: 10 + below: 20 +``` + +{% configuration condition_numeric_state %} +condition: + required: true + description: "`numeric_state`" type: string -attribute: +above: required: false - description: Attribute of the entity to use instead of the state. + description: Entity state or ID to be above this value.* + type: string +below: + required: false + description: Entity state or ID to be below this value.* type: string {% endconfiguration %} -## Examples +*at least one is required (`above` or `below`), both are also possible for values between. + +### Screen + +Specify the visibility of the entity per screen size. Some screen size presets are available in the UI but you can use any CSS media query you want in YAML. + +```yaml +type: entity-filter +entities: + - sensor.outside_temperature + - sensor.living_room_temperature + - sensor.bed_room_temperature +conditions: + - condition: screen + media_query: "(min-width: 1280px)" +``` + +{% configuration condition_screen %} +condition: + required: true + description: "`screen`" + type: string +media_query: + required: true + description: Media query to check which screen size are allowed to display the entity. + type: string +{% endconfiguration %} + +### User + +Specify the visibility of the entity per user. + +```yaml +type: entity-filter +entities: + - sensor.outside_temperature + - sensor.living_room_temperature + - sensor.bed_room_temperature +conditions: + - condition: user + users: + - 581fca7fdc014b8b894519cc531f9a04 +``` + +{% configuration condition_user %} +condition: + required: true + description: "`user`" + type: string +users: + required: true + description: User ID that can see the entity (unique hex value found on the Users configuration page). + type: list +{% endconfiguration %} + +### And + +Specify that both conditions must be met. + +```yaml +type: entity-filter +entities: + - sensor.outside_temperature + - sensor.living_room_temperature + - sensor.bed_room_temperature +conditions: + - condition: and + conditions: + - condition: numeric_state + above: 0 + - condition: user + users: + - 581fca7fdc014b8b894519cc531f9a04 +``` + +{% configuration condition_and %} +condition: + required: true + description: "`and`" + type: string +conditions: + required: false + description: List of conditions to check. See [available conditions](#conditions-options). + type: list +{% endconfiguration %} + +### Or + +Specify that at least one of the conditions must be met. + +```yaml +type: entity-filter +entities: + - sensor.outside_temperature + - sensor.living_room_temperature + - sensor.bed_room_temperature +conditions: + - condition: or + conditions: + - condition: numeric_state + above: 0 + - condition: user + users: + - 581fca7fdc014b8b894519cc531f9a04 +``` + +{% configuration condition_or %} +condition: + required: true + description: "`or`" + type: string +conditions: + required: false + description: List of conditions to check. See [available conditions](#conditions-options). + type: list +{% endconfiguration %} + +## Legacy state filters + +### String filter Show only active switches or lights in the house. @@ -134,7 +334,32 @@ card: Entity filter combined with glance card.

-You can also specify multiple `state_filter` conditions, in which case the entity will be displayed if it matches any condition. This example will display everyone who is at home or at work. +You can also specify multiple `state_filter` conditions, in which case the entity will be displayed if it matches any condition. + +If you define `state_filter` as objects instead of strings, you can add more customization to your filter, as described below. + +### Operator filter + +Tests if an entity state correspond to the applied `operator`. + +{% configuration condition_operator %} +value: + required: true + description: String representing the state. + type: string +operator: + required: true + description: Operator to use in the comparison. Can be `==`, `<=`, `<`, `>=`, `>`, `!=`, `in`, `not in`, or `regex`. + type: string +attribute: + required: false + description: Attribute of the entity to use instead of the state. + type: string +{% endconfiguration %} + +#### Examples + +Displays everyone who is at home or at work. ```yaml type: entity-filter @@ -146,7 +371,7 @@ state_filter: - operator: "==" value: home - operator: "==" - value: work + value: work card: type: glance title: Who's at work or home @@ -173,19 +398,19 @@ entities: Use a regex filter against entity attributes. This regex filter below looks for expressions that are 1 digit in length and where the number is between 0-7 (so show holidays today or in the next 7 days) and displays those holidays as entities in the Entity Filter card. ```yaml - - type: entity-filter - card: - title: "Upcoming Holidays In Next 7 Days" - show_header_toggle: false - state_filter: - - operator: regex - value: "^([0-7]{1})$" - attribute: eta - entities: - - entity: sensor.upcoming_ical_holidays_0 - - entity: sensor.upcoming_ical_holidays_1 - - entity: sensor.upcoming_ical_holidays_2 - - entity: sensor.upcoming_ical_holidays_3 - - entity: sensor.upcoming_ical_holidays_4 - show_empty: false +type: entity-filter +card: + title: "Upcoming Holidays In Next 7 Days" + show_header_toggle: false +state_filter: + - operator: regex + value: "^([0-7]{1})$" + attribute: eta +entities: + - entity: sensor.upcoming_ical_holidays_0 + - entity: sensor.upcoming_ical_holidays_1 + - entity: sensor.upcoming_ical_holidays_2 + - entity: sensor.upcoming_ical_holidays_3 + - entity: sensor.upcoming_ical_holidays_4 +show_empty: false ``` diff --git a/source/dashboards/badges.markdown b/source/dashboards/badges.markdown index 56821d17624..198b11f4105 100644 --- a/source/dashboards/badges.markdown +++ b/source/dashboards/badges.markdown @@ -19,7 +19,7 @@ type: state-label entity: light.living_room ``` -{% configuration state_label %} +{% configuration state_badge %} type: required: true description: "`state-label`" @@ -62,12 +62,18 @@ entities: required: true description: A list of entity IDs or `entity` objects, see below. type: list +conditions: + required: false + description: List of conditions to check. See [available conditions](#conditions-options).* + type: list state_filter: - required: true - description: List of strings representing states or `filter` objects, see below. + required: false + description: (legacy) List of strings representing states or filters to check. See [available legacy filters](#legacy-state-filters).* type: list {% endconfiguration %} +*one is required (`conditions` or `state_filter`) + ### Options for entities If you define entities as objects instead of strings (by adding `entity:` before entity ID), you can add more customization and configurations: @@ -93,34 +99,227 @@ image: required: false description: The URL of an image. type: string +conditions: + required: false + description: List of conditions to check. See [available conditions](#conditions-options).* + type: list state_filter: required: false - description: List of strings representing states or `filter` objects, see below. + description: (legacy) List of strings representing states or filters to check. See [available legacy filters](#legacy-state-filters).* type: list {% endconfiguration %} -### Options for state filter +*only one filter will be applied: `conditions` or `state_filter` if `conditions` is not present -If you define state_filter as objects instead of strings (by adding `value:` before your state value), you can add more customization to your filter: +## Conditions options -{% configuration state_filter %} -value: +You can specify multiple `conditions`, in which case the entity will be displayed if it matches any condition. + +### State + +Tests if an entity has a specified state. + +```yaml +type: entity-filter +entities: + - climate.thermostat_living_room + - climate.thermostat_bed_room +conditions: + - condition: state + state: heat +``` + +```yaml +type: entity-filter +entities: + - climate.thermostat_living_room + - climate.thermostat_bed_room +conditions: + - condition: state + state_not: "off" +``` + +```yaml +type: entity-filter +entities: + - sensor.gas_station_1 + - sensor.gas_station_2 + - sensor.gas_station_3 +conditions: + - condition: state + state: sensor.gas_station_lowest_price +``` + +{% configuration condition_state %} +condition: required: true - description: String representing the state. + description: "`state`" type: string -operator: +state: required: false - description: Operator to use in the comparison. Can be `==`, `<=`, `<`, `>=`, `>`, `!=` or `regex`. + description: Entity state or ID to be equal to this value. Can contain an array of states.* + type: [list, string] +state_not: + required: false + description: Entity state or ID to not be equal to this value. Can contain an array of states.* + type: [list, string] +{% endconfiguration %} + +*one is required (`state` or `state_not`) + +### Numeric state + +Tests if an entity state matches the thresholds. + +```yaml +type: entity-filter +entities: + - sensor.outside_temperature + - sensor.living_room_temperature + - sensor.bed_room_temperature +conditions: + - condition: numeric_state + above: 10 + below: 20 +``` + +{% configuration condition_numeric_state %} +condition: + required: true + description: "`numeric_state`" type: string -attribute: +above: required: false - description: Attribute of the entity to use instead of the state. + description: Entity state or ID to be above this value.* + type: string +below: + required: false + description: Entity state or ID to be below this value.* type: string {% endconfiguration %} -### Examples +*at least one is required (`above` or `below`), both are also possible for values between. -Show only active switches or lights in the house +### Screen + +Specify the visibility of the entity per screen size. Some screen size presets are available in the UI but you can use any CSS media query you want in YAML. + +```yaml +type: entity-filter +entities: + - sensor.outside_temperature + - sensor.living_room_temperature + - sensor.bed_room_temperature +conditions: + - condition: screen + media_query: "(min-width: 1280px)" +``` + +{% configuration condition_screen %} +condition: + required: true + description: "`screen`" + type: string +media_query: + required: true + description: Media query to check which screen size are allowed to display the entity. + type: string +{% endconfiguration %} + +### User + +Specify the visibility of the entity per user. + +```yaml +type: entity-filter +entities: + - sensor.outside_temperature + - sensor.living_room_temperature + - sensor.bed_room_temperature +conditions: + - condition: user + users: + - 581fca7fdc014b8b894519cc531f9a04 +``` + +{% configuration condition_user %} +condition: + required: true + description: "`user`" + type: string +users: + required: true + description: User ID that can see the entity (unique hex value found on the Users configuration page). + type: list +{% endconfiguration %} + +### And + +Specify that both conditions must be met. + +```yaml +type: entity-filter +entities: + - sensor.outside_temperature + - sensor.living_room_temperature + - sensor.bed_room_temperature +conditions: + - condition: and + conditions: + - condition: numeric_state + above: 0 + - condition: user + users: + - 581fca7fdc014b8b894519cc531f9a04 +``` + +{% configuration condition_and %} +condition: + required: true + description: "`and`" + type: string +conditions: + required: false + description: List of conditions to check. See [available conditions](#conditions-options). + type: list +{% endconfiguration %} + +### Or + +Specify that at least one of the conditions must be met. + +```yaml +type: entity-filter +entities: + - sensor.outside_temperature + - sensor.living_room_temperature + - sensor.bed_room_temperature +conditions: + - condition: or + conditions: + - condition: numeric_state + above: 0 + - condition: user + users: + - 581fca7fdc014b8b894519cc531f9a04 +``` + +{% configuration condition_or %} +condition: + required: true + description: "`or`" + type: string +conditions: + required: false + description: List of conditions to check. See [available conditions](#conditions-options). + type: list +{% endconfiguration %} + +## Legacy state filters + +### String filter + +Show only active switches or lights in the house. ```yaml type: entity-filter @@ -133,7 +332,47 @@ state_filter: - "on" ``` -Specify filter for a single entity +You can also specify multiple `state_filter` conditions, in which case the entity will be displayed if it matches any condition. + +If you define `state_filter` as objects instead of strings, you can add more customization to your filter, as described below. + +### Operator filter + +Tests if an entity state correspond to the applied `operator`. + +{% configuration condition_operator %} +value: + required: true + description: String representing the state. + type: string +operator: + required: true + description: Operator to use in the comparison. Can be `==`, `<=`, `<`, `>=`, `>`, `!=`, `in`, `not in`, or `regex`. + type: string +attribute: + required: false + description: Attribute of the entity to use instead of the state. + type: string +{% endconfiguration %} + +#### Examples + +Displays everyone who is at home or at work. + +```yaml +type: entity-filter +entities: + - device_tracker.demo_paulus + - device_tracker.demo_anne_therese + - device_tracker.demo_home_boy +state_filter: + - operator: "==" + value: home + - operator: "==" + value: work +``` + +Specify filter for a single entity. ```yaml type: entity-filter @@ -150,3 +389,20 @@ entities: value: 50 attribute: humidity ``` + +Use a regex filter against entity attributes. This regex filter below looks for expressions that are 1 digit in length and where the number is between 0-7 (so show holidays today or in the next 7 days) and displays those holidays as entities in the Entity Filter badge. + +```yaml +type: entity-filter +state_filter: + - operator: regex + value: "^([0-7]{1})$" + attribute: eta +entities: + - entity: sensor.upcoming_ical_holidays_0 + - entity: sensor.upcoming_ical_holidays_1 + - entity: sensor.upcoming_ical_holidays_2 + - entity: sensor.upcoming_ical_holidays_3 + - entity: sensor.upcoming_ical_holidays_4 +show_empty: false +```