Document trigger entity (#17092)

Co-authored-by: Hmmbob <33529490+hmmbob@users.noreply.github.com>
Co-authored-by: Franck Nijhof <git@frenck.dev>

source/_docs/automation/templating.markdown

@@ -1,26 +1,10 @@
 ---
-title: "Automation Templating"
+title: "Automation Trigger Variables"
-description: "Advanced automation documentation using templating."
+description: "List all available variables made available by triggers."
 ---
 
 Automations support [templating](/docs/configuration/templating/) in the same way as scripts do. In addition to the [Home Assistant template extensions](/docs/configuration/templating/#home-assistant-template-extensions) available to scripts, the `trigger` template variable is available.
 
-<div class='note'>
-  
-  Be aware that if you reference a `trigger` state object in templates of an automation' `action` or `condition` sections, attempting to test that automation by calling the `automation.trigger` service or by clicking EXECUTE in the More Info box for the automation will not work. This is because the trigger state object doesn't exist in those contexts. One way to test automations like these is to manually check that the templates work as expected by pasting them in {% my developer_template title="Developer Tools > Template" %} together with your trigger's definition like:
-
-{%raw%}
-
-```yaml
-{% set trigger={'to_state':{'state': 'heat'}} %}
-{% set option = trigger.to_state.state %}
-{{ 'on' if option == 'heat' else 'off' }}
-```
-
-{%endraw%}
-  
-</div>
-
 ## Available Trigger Data
 
 The following tables show the available trigger data per platform.

source/_docs/automation/trigger.markdown

@@ -3,13 +3,24 @@ title: "Automation Trigger"
 description: "All the different ways how automations can be triggered."
 ---
 
-## What are triggers
-
 Triggers are what starts the processing of an automation rule. When _any_ of the automation's triggers becomes true (trigger _fires_), Home Assistant will validate the [conditions](/docs/automation/condition/), if any, and call the [action](/docs/automation/action/).
 
 An automation can be triggered by an event, with a certain entity state, at a given time, and more. These can be specified directly or more flexible via templates. It is also possible to specify multiple triggers for one automation.
 
-The following sections introduce all trigger types and further details to get started.
+- [Event trigger](#event-trigger)
+- [Home Assistant trigger](#home-assistant-trigger)
+- [MQTT trigger](#mqtt-trigger)
+- [Numeric state trigger](#numeric-state-trigger)
+- [State trigger](#state-trigger)
+- [Sun trigger](#sun-trigger)
+- [Tag trigger](#tag-trigger)
+- [Template trigger](#template-trigger)
+- [Time trigger](#time-trigger)
+- [Time pattern trigger](#time-pattern-trigger)
+- [Webhook trigger](#webhook-trigger)
+- [Zone trigger](#zone-trigger)
+- [Geolocation trigger](#geolocation-trigger)
+- [Device triggers](#device-triggers)
 
 ## Trigger variables
 

source/_integrations/template.markdown

@@ -23,7 +23,22 @@ ha_platforms:
   - weather
 ---
 
-The `template` platform supports sensors which get their values from other entities.
+The `template` integration allows creating entities which derive their values from other entities. This is done by defining [templates](/docs/configuration/templating/) for each property of an entity, like the name or the state. Entities are updated automatically whenever a value that a template relies on changes.
+
+For sensors it's also possible to derive the state from [automation triggers](#configuration-for-trigger-based-template-sensors).
+
+Available template platforms:
+
+- [Alarm_control_panel](/integrations/alarm_control_panel.template/)
+- [Binary_sensor](/integrations/binary_sensor.template/)
+- [Cover](/integrations/cover.template/)
+- [Fan](/integrations/fan.template/)
+- [Light](/integrations/light.template/)
+- [Lock](/integrations/lock.template/)
+- Sensor (this page)
+- [Switch](/integrations/switch.template/)
+- [Vacuum](/integrations/vacuum.template/)
+- [Weather](/integrations/weather.template/)
 
 ## Configuration
 
@@ -49,7 +64,7 @@ sensor:
 
 {% configuration %}
   sensors:
-    description: List of your sensors.
+    description: Map of your sensors.
     required: true
     type: map
     keys:
@@ -103,6 +118,59 @@ sensor:
         default: None
 {% endconfiguration %}
 
+## Configuration for trigger-based template sensors
+
+Trigger-based template sensors allow the user to define [an automation trigger][trigger-doc] for a group of template sensors. Whenever the trigger fires, the template sensor will re-render and it will have access to [the trigger data](/docs/automation/templating/) in the templates. This feature is a great way to create data based on webhook data, or have sensors be updated based on a time-schedule.
+
+Trigger-based template entities are defined in YAML directly under the `template:` key. You can define multiple configuration blocks as a list. Each block defines one or more triggers and the sensors that should be updated when the trigger fires.
+
+Trigger-based entities do not automatically update when states referenced in the templates change. This functionality can be added by defining a [state trigger](/docs/automation/trigger/#state-trigger) for each entity that you want to trigger updates.
+
+{% raw %}
+
+```yaml
+# Example configuration entry
+template:
+  - trigger:
+      - platform: webhook
+        webhook_id: my-super-secret-webhook-id
+    sensor:
+      - name: "Webhook Temperature"
+        state: "{{ trigger.json.temperature }}"
+      - name: "Webhook Humidity"
+        state: "{{ trigger.json.humidity }}"
+```
+
+{% endraw %}
+
+You can test this trigger entity with the following CURL command:
+
+```bash
+curl --header "Content-Type: application/json" \
+  --request POST \
+  --data '{"temperature": 5, "humidity": 34}' \
+  http://homeassistant.local:8123/api/webhook/my-super-secret-webhook-id
+```
+
+{% configuration %}
+trigger:
+  description: The trigger configuration for this entity. [See trigger documentation](/docs/automation/trigger)
+  required: true
+  type: list
+unique_id:
+  description: The unique ID for this trigger. This will be prefixed to all unique IDs of all entities in this block.
+  required: false
+  type: string
+sensor:
+  description: Map of your sensors to create from the trigger data. For available keys, see [configuration variables](#configuration-variables) above.
+  required: true
+  type: map
+{% endconfiguration %}
+
+<p class='note'>It's currently only possible to define trigger-based entities via the top-level configuration. These entities are not yet included when reloading template entities.</p>
+
+[trigger-doc]: /docs/automation/trigger
+
 ## Considerations
 
 ### Startup