Update template entity docs for entity_id removal and guidance on working without entities (#14343)

Co-authored-by: Anders Melchiorsen <amelchio@nogoto.net>
Co-authored-by: Swamp-Ig <github@ninjateaparty.com>

source/_docs/scripts.markdown

@@ -114,6 +114,8 @@ When used within an automation the `trigger` variable is available. See [Availab
 
 This action evaluates the template, and if true, the script will continue. If not, then it will wait until it is true.
 
+The template is re-evaluated whenever an entity ID that it references changes state. If you use non-deterministic functions like `now()` in the template it will not be continuously re-evaluated, but only when an entity ID that is referenced is changed. If you need to periodically re-evaluate the template, reference a sensor from the (Time and Date)[/integrations/time_date/] component that will update minutely or daily.
+
 {% raw %}
 ```yaml
 # Wait until media player have stop the playing

source/_integrations/alarm_control_panel.template.markdown

@@ -106,3 +106,7 @@ panels:
 If you are using the state of a 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.
 
 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 %}
+
+### Working without entities
+
+If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/binary_sensor.template/#working-without-entities) in the Template Binary Sensor integration.

source/_integrations/bayesian.markdown

@@ -132,8 +132,7 @@ binary_sensor:
       below: 50
 ```
 
-Finally, here's an example for `template` observation platform,
+Finally, here's an example for `template` observation platform, as seen in the configuration it requires `value_template`.
-as seen in the configuration it requires `value_template` and does not use `entity_id`.
 
 {% raw %}
 ```yaml
@@ -150,3 +149,7 @@ binary_sensor:
       prob_given_true: 0.95
 ```
 {% endraw %}
+
+The template is re-evaluated whenever an entity ID that it references changes state. If you use non-deterministic functions like `now()` in the template it will not be continuously re-evaluated, but only when an entity ID that is referenced is updated. 
+
+In this example, since the template is only evaluated on state change of `device_tracker.paulus` the template won't change state after 5 mins like intended. The ways to force template reevaluation are documented in the [template binary_sensor](/integrations/binary_sensor.template/#working-without-entities).

source/_integrations/binary_sensor.template.markdown

@@ -110,13 +110,12 @@ with this equivalent that returns `true`/`false` and never gives an unknown
 result:
 {% raw %}`{{ is_state('switch.source', 'on') }}`{% endraw %}
 
-### Entity IDs
+### Sensor state updates
 
-The template engine will attempt to work out what entities should trigger an
+The template engine works out what entities are used to trigger an update of the sensor and recalculates the result when one of those entities change.
-update of the sensor. This can fail, for example if your template loops over
+
-the contents of a group. In this case you can use `entity_id` to provide a
+If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, create an interval-based
-list of entity IDs that will cause the sensor to update or you can run the
+automation that calls the service `homeassistant.update_entity` for the sensor requiring updates. See the [example below](#working-without-entities).
-service `homeassistant.update_entity` to update the sensor at will.
 
 ## Examples
 
@@ -294,3 +293,44 @@ binary_sensor:
 ```
 
 {% endraw %}
+
+### Working without entities
+
+The `template` sensors are not limited to use attributes from other entities but can also work with [Home Assistant's template extensions](/docs/configuration/templating/#home-assistant-template-extensions). If the template includes some non-deterministic property such as time in its calculation, the result will not continually update, but will only update when some entity referenced by the template updates. 
+
+There's a couple of options to manage this issue. This first example creates a `sensor.time` from the [Time & Date](/integrations/time_date/) component which updates every minute, and the binary sensor is triggered by this updating. The binary sensor returns true if in the first half of the hour:
+
+{% raw %}
+```yaml
+sensor:
+  - platform: time_date
+    display_options:
+      - 'time'
+
+binary_sensor:
+  - platform: template
+    sensors:
+      half_hour:
+        value_template: '{{ (states.sensor.time.state[3:]|int) < 30 }}'
+```
+{% endraw %}
+
+An alternative to this is to create an interval-based automation that calls the service `homeassistant.update_entity` for the entities requiring updates. This modified example updates every 2 minutes:
+
+{% raw %}
+```yaml
+binary_sensor:
+- platform: template
+  sensors:
+    minute_is_odd:
+      value_template: '{{ now().minute % 2 }}'
+
+automation:
+  - alias: 'Update minute_is_odd'
+    trigger:
+      - platform: time_pattern
+        minutes: '*'
+    action:
+      - service: homeassistant.update_entity
+        entity_id: binary_sensor.minute_is_odd
+{% endraw %}

source/_integrations/cover.template.markdown

@@ -49,10 +49,6 @@ cover:
         description: Name to use in the frontend.
         required: false
         type: string
-      entity_id:
-        description: A list of entity IDs so the cover only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities.
-        required: false
-        type: [string, list]
       unique_id:
         description: An ID that uniquely identifies this cover. Set this to an unique value to allow customisation trough the UI.
         required: false
@@ -126,6 +122,10 @@ with this equivalent that returns `true`/`false` and never gives an unknown
 result:
 {% raw %}`{{ is_state('cover.source', 'open') }}`{% endraw %}
 
+### Working without entities
+
+If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/binary_sensor.template/#working-without-entities) in the Template Binary Sensor integration.
+
 ## Optimistic Mode
 
 In optimistic mode, the cover position state is maintained internally. This mode
@@ -219,9 +219,6 @@ cover:
           {% else %}
             mdi:window-closed
           {% endif %}
-        entity_id:
-          - cover.bedroom
-          - cover.livingroom
 
 sensor:
   - platform: template

source/_integrations/fan.template.markdown

@@ -114,3 +114,7 @@ fan:
         type: [string, list]
         default: ['low', 'medium', 'high']
 {% endconfiguration %}
+
+### Working without entities
+
+If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/binary_sensor.template/#working-without-entities) in the Template Binary Sensor integration.

source/_integrations/light.template.markdown

@@ -70,10 +70,6 @@ light:
         description: Name to use in the frontend.
         required: false
         type: string
-      entity_id:
-        description: A list of entity IDs so the light only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities.
-        required: false
-        type: [string, list]
       unique_id:
         description: An ID that uniquely identifies this light. Set this to an unique value to allow customisation trough the UI.
         required: false
@@ -150,6 +146,10 @@ with this equivalent that returns `true`/`false` and never gives an unknown
 result:
 {% raw %}`{{ is_state('switch.source', 'on') }}`{% endraw %}
 
+### Working without entities
+
+If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/binary_sensor.template/#working-without-entities) in the Template Binary Sensor integration.
+
 ## Examples
 
 In this section you will find some real-life examples of how to use this light.

source/_integrations/lock.template.markdown

@@ -79,6 +79,10 @@ lock:
 
 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 %}`{{ is_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 %}
 
+### Working without entities
+
+If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/binary_sensor.template/#working-without-entities) in the Template Binary Sensor integration.
+
 ## Examples
 
 In this section, you find some real-life examples of how to use this lock.

source/_integrations/switch.template.markdown

@@ -50,10 +50,6 @@ switch:
         description: Name to use in the frontend.
         required: false
         type: string
-      entity_id:
-        description: A list of entity IDs so the switch only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities.
-        required: false
-        type: [string, list]
       unique_id:
         description: An ID that uniquely identifies this switch. Set this to an unique value to allow customisation trough the UI.
         required: false
@@ -90,6 +86,10 @@ switch:
 
 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 %}
 
+### Working without entities
+
+If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/binary_sensor.template/#working-without-entities) in the Template Binary Sensor integration.
+
 ## Examples
 
 In this section you find some real-life examples of how to use this switch.

source/_integrations/template.markdown

@@ -50,10 +50,6 @@ sensor:
         description: Defines a template for the name to be used in the frontend (this overrides friendly_name).
         required: false
         type: template
-      entity_id:
-        description: A list of entity IDs so the sensor only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities.
-        required: false
-        type: [string, list]
       unique_id:
         description: An ID that uniquely identifies this sensor. Set this to an unique value to allow customisation trough the UI.
         required: false
@@ -104,9 +100,12 @@ If you are using the state of a platform that takes extra time to load, the Temp
 
 {% raw %}`{{ is_state('switch.source', 'on') }}`{% endraw %}
 
-### Entity IDs
+### Sensor state updates
 
-The template engine will attempt to work out what entities should trigger an update of the sensor. This can fail, for example, if your template loops over the contents of a group. In this case, you can use `entity_id` to provide a list of entity IDs that will cause the sensor to update or you can run the service `homeassistant.update_entity` to update the sensor at will.
+The template engine works out what entities are used to trigger an update of the sensor and recalculates the result when one of those entities change.
+
+If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, create an interval-based
+automation that calls the service `homeassistant.update_entity` for the sensor requiring updates. See the [example below](#working-without-entities).
 
 ### Unique ID
 
@@ -322,17 +321,19 @@ sensor:
 
 The `template` sensors are not limited to use attributes from other entities but can also work with [Home Assistant's template extensions](/docs/configuration/templating/#home-assistant-template-extensions).
 
-This template contains no entities that will trigger an update (as `now()` is a function), so we add an `entity_id:` line with an entity that will force an update - here we're using a [date sensor](/integrations/time_date) to get a daily update:
+This template contains no entities that will trigger an update, so we add in a reference to the `sensor.date` sensor from the [Time & Date](/integrations/time_date/), which will update once a day.
 
 {% raw %}
 
 ```yaml
 sensor:
+  - platform: time_date
+    display_options:
+      - 'date'
   - platform: template
     sensors:
       nonsmoker:
-        value_template: "{{ (( as_timestamp(now()) - as_timestamp(strptime('06.07.2018', '%d.%m.%Y')) ) / 86400 ) | round(2) }}"
+        value_template: '{{ states('sensor.date') and (( as_timestamp(now()) - as_timestamp(strptime("06.07.2018", "%d.%m.%Y")) ) / 86400 ) | round(2) }}'
-        entity_id: sensor.date
         friendly_name: 'Not smoking'
         unit_of_measurement: "Days"
 ```
@@ -367,8 +368,7 @@ sensor:
   - platform: template
     sensors:
       nonsmoker:
-        value_template: "{{ (( as_timestamp(now()) - as_timestamp(strptime('06.07.2018', '%d.%m.%Y')) ) / 86400 ) | round(2) }}"
+        value_template: '{{ (( as_timestamp(now()) - as_timestamp(strptime("06.07.2018", "%d.%m.%Y")) ) / 86400 ) | round(2) }}'
-        entity_id: []
         friendly_name: 'Not smoking'
         unit_of_measurement: "Days"
 

source/_integrations/universal.markdown

@@ -74,6 +74,8 @@ It is also recommended that the command `volume_up`, the command `volume_down`,
 
 When providing `select_source` as a command, it is recommended to also provide the attributes `source`, and `source_list`. The `source` attribute is the currently select source, while the `source_list` attribute is a list of all available sources.
 
+When using `state_template`, if you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see the [example](/integrations/binary_sensor.template/#working-without-entities) in the template binary_sensor.
+
 ## Usage examples
 
 ### Chromecast & Kodi control with switches

source/_integrations/vacuum.template.markdown

@@ -103,6 +103,10 @@ vacuum:
         type: [string, list]
 {% endconfiguration %}
 
+### Working without entities
+
+If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/template/#working-without-entities) in the Template Sensor integration.
+
 ## Examples
 
 ### Control vacuum with Harmony Hub