From 5bdd871e4dc098e74890d1413052879ad7a6716b Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Wed, 20 Apr 2022 15:35:07 +0200 Subject: [PATCH] Document `this` variable in state-based template entities (#22211) Co-authored-by: Franck Nijhof --- .../alarm_control_panel.template.markdown | 4 ++++ source/_integrations/cover.template.markdown | 4 ++++ source/_integrations/fan.template.markdown | 4 ++++ source/_integrations/light.template.markdown | 4 ++++ source/_integrations/lock.template.markdown | 4 ++++ source/_integrations/switch.template.markdown | 4 ++++ source/_integrations/template.markdown | 22 +++++++++++++++++++ source/_integrations/vacuum.template.markdown | 4 ++++ .../_integrations/weather.template.markdown | 4 ++++ 9 files changed, 54 insertions(+) diff --git a/source/_integrations/alarm_control_panel.template.markdown b/source/_integrations/alarm_control_panel.template.markdown index 837fe0524ef..432f884e248 100644 --- a/source/_integrations/alarm_control_panel.template.markdown +++ b/source/_integrations/alarm_control_panel.template.markdown @@ -111,6 +111,10 @@ panels: default: number {% endconfiguration %} +### Template variables + +State-based template entities have the special template variable `this` available in their templates. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates. + ## Considerations If you are using the state of an integration that takes extra time to load, the Template Alarm Control Panel may get an `unknown` state during startup. This results in error messages in your log file until that integration has completed loading. If you use `is_state()` function in your template, you can avoid this situation. diff --git a/source/_integrations/cover.template.markdown b/source/_integrations/cover.template.markdown index 98686e191e4..aa4983ba236 100644 --- a/source/_integrations/cover.template.markdown +++ b/source/_integrations/cover.template.markdown @@ -114,6 +114,10 @@ cover: type: template {% endconfiguration %} +### Template variables + +State-based template entities have the special template variable `this` available in their templates. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates. + ## Considerations If you are using the state of a platform that takes extra time to load, the diff --git a/source/_integrations/fan.template.markdown b/source/_integrations/fan.template.markdown index 7198153caab..eb35ab6e776 100644 --- a/source/_integrations/fan.template.markdown +++ b/source/_integrations/fan.template.markdown @@ -134,6 +134,10 @@ fan: default: 100 {% endconfiguration %} +### Template variables + +State-based template entities have the special template variable `this` available in their templates. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates. + ## Converting from speeds to percentage When converting a fan with 3 speeds from the old fan entity model, the following percentages can be used: diff --git a/source/_integrations/light.template.markdown b/source/_integrations/light.template.markdown index 3cb2c6930c1..4f556c3ac23 100644 --- a/source/_integrations/light.template.markdown +++ b/source/_integrations/light.template.markdown @@ -179,6 +179,10 @@ light: type: action {% endconfiguration %} +### Template variables + +State-based template entities have the special template variable `this` available in their templates. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates. + ## Considerations If you are using the state of a platform that takes extra time to load, the diff --git a/source/_integrations/lock.template.markdown b/source/_integrations/lock.template.markdown index 8d022bea62e..9c8c98e8466 100644 --- a/source/_integrations/lock.template.markdown +++ b/source/_integrations/lock.template.markdown @@ -75,6 +75,10 @@ lock: default: false {% endconfiguration %} +### Template variables + +State-based template entities have the special template variable `this` available in their templates. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates. + ## Considerations If you are using the state of a platform that takes extra time to load, the Template Lock may get an `unknown` state during startup. This results in error messages in your log file until that platform has completed loading. If you use `is_state()` function in your template, you can avoid this situation. For example, you would replace {% raw %}`{{ state('switch.source') == 'on') }}`{% endraw %} with this equivalent that returns `true`/`false` and never gives an unknown result: {% raw %}`{{ is_state('switch.source', 'on') }}`{% endraw %} diff --git a/source/_integrations/switch.template.markdown b/source/_integrations/switch.template.markdown index 81c0b668133..7c79f8ff03f 100644 --- a/source/_integrations/switch.template.markdown +++ b/source/_integrations/switch.template.markdown @@ -82,6 +82,10 @@ switch: type: template {% endconfiguration %} +### Template variables + +State-based template entities have the special template variable `this` available in their templates. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates. + ## Considerations If you are using the state of a platform that takes extra time to load, the Template Switch may get an `unknown` state during startup. This results in error messages in your log file until that platform has completed loading. If you use `is_state()` function in your template, you can avoid this situation. For example, you would replace {% raw %}`{{ states.switch.source.state == 'on') }}`{% endraw %} with this equivalent that returns `true`/`false` and never gives an unknown result: {% raw %}`{{ is_state('switch.source', 'on') }}`{% endraw %} diff --git a/source/_integrations/template.markdown b/source/_integrations/template.markdown index ca538ac1ddf..13d8141723f 100644 --- a/source/_integrations/template.markdown +++ b/source/_integrations/template.markdown @@ -68,6 +68,10 @@ template: {% endraw %} +### Template variables + +State-based template entities have the special template variable `this` available in their templates. The `this` variable aids [self-referencing](#self-referencing) of an entity's state and attribute in templates. + ## Trigger-based template binary sensors, buttons, numbers, selects and sensors If you want more control over when an entity updates, you can define a trigger. Triggers follow the same format and work exactly the same as [triggers in automations][trigger-doc]. This feature is a great way to create entities based on webhook data ([example](#storing-webhook-information)), or update entities based on a schedule. @@ -564,6 +568,24 @@ template: {% endraw %} +### Self referencing + +This example demonstrates how the `this` variable can be used in templates for self-referencing. + +{% raw %} + +```yaml +template: + - sensor: + - name: test + state: "{{ this.attributes.test }}" + # not: "{{ state_attr('sensor.test', 'test' }}" + attributes: + test: "{{ now() }}" +``` + +{% endraw %} + ## Legacy binary sensor configuration format _This format still works but is no longer recommended. [Use modern configuration](#configuration-variables)._ diff --git a/source/_integrations/vacuum.template.markdown b/source/_integrations/vacuum.template.markdown index 30519747ec8..9d7adb53f22 100644 --- a/source/_integrations/vacuum.template.markdown +++ b/source/_integrations/vacuum.template.markdown @@ -103,6 +103,10 @@ vacuum: type: [string, list] {% endconfiguration %} +### Template variables + +State-based template entities have the special template variable `this` available in their templates. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates. + ## Examples ### Control vacuum with Harmony Hub diff --git a/source/_integrations/weather.template.markdown b/source/_integrations/weather.template.markdown index 7d8c2a335bd..f7d2fe90f65 100644 --- a/source/_integrations/weather.template.markdown +++ b/source/_integrations/weather.template.markdown @@ -87,3 +87,7 @@ forecast_template: required: false type: template {% endconfiguration %} + +### Template variables + +State-based template entities have the special template variable `this` available in their templates. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates.