Document trigger templating (#16455)

Co-authored-by: Franck Nijhof <git@frenck.dev>

source/_docs/automation/trigger.markdown

@@ -11,6 +11,10 @@ An automation can be triggered by an event, with a certain entity state, at a gi
 
 The following sections introduce all trigger types and further details to get started.
 
+### Trigger variables
+
+Similar to [script level variables](/integrations/script/#variables), `trigger_variables` will be available in trigger templates with the difference that only [limited templates](/docs/configuration/templating/#limited-templates) can  be used to pass a value to the trigger variable.
+
 ### Event trigger
 
 Fires when an event is being received. Events are the raw building blocks of Home Assistant. You can match events on just the event name or also require specific event data or context to be present.
@@ -44,6 +48,29 @@ automation:
       - scene_reloaded
 ```
 
+It's also possible to use [limited templates](/docs/configuration/templating/#limited-templates) in the `event_type`, `event_data` and `context` options.
+
+<div class='note'>
+
+The `event_type`, `event_data` and `context` templates are only evaluated when setting up the trigger, they will not be reevaluated for every event.
+
+</div>
+
+{% raw %}
+
+```yaml
+automation:
+  trigger_variables:
+    sub_event: ABC
+    node: ac
+    value: on
+  trigger:
+    platform: event
+    event_type: "{{ 'MY_CUSTOM_EVENT_' ~ sub_event }}"
+```
+
+{% endraw %}
+
 ### Home Assistant trigger
 
 Fires when Home Assistant starts up or shuts down.
@@ -70,6 +97,32 @@ automation:
     encoding: "utf-8"
 ```
 
+It's also possible to use [limited templates](/docs/configuration/templating/#limited-templates) in the `topic` and `payload` options.
+
+<div class='note'>
+
+The `topic` and `payload` templates are only evaluated when setting up the trigger, they will not be re-evaluated for every incoming MQTT message.
+
+</div>
+
+{% raw %}
+
+```yaml
+automation:
+  trigger_variables:
+    room: "living_room"
+    node: "ac"
+    value: "on"
+  trigger:
+    platform: mqtt
+    topic: "{{ room ~ '/switch/' ~ node}}"
+    # Optional
+    payload: "{{ 'state:' ~ value }}"
+    encoding: "utf-8"
+```
+
+{% endraw %}
+
 ### Numeric state trigger
 
 Fires when the numeric value of an entity's state (or attribute's value if using the `attribute` property) crosses a given threshold. On state change of a specified entity, attempts to parse the state as a number and fires if the value is changing from above to below or from below to above the given threshold.

source/_docs/configuration/templating.markdown

@@ -59,8 +59,14 @@ Remembering these simple rules will help save you from many headaches and endles
 
 Extensions allow templates to access all of the Home Assistant specific states and adds other convenience functions and filters.
 
+### Limited Templates
+
+Templates for some triggers [triggers](/docs/automation/trigger/) as well as `trigger_variables` only support a subset of the Home Assistant template extensions. This subset is referred to as "Limited Templates".
+
 ### States
 
+Not supported in [limited templates](#limited-templates).
+
 - Iterating `states` will yield each state sorted alphabetically by entity ID.
 - Iterating `states.domain` will yield each state of that domain sorted alphabetically by entity ID.
 - `states.sensor.temperature` returns the state object for `sensor.temperature` (avoid when possible, see note below).
@@ -128,6 +134,8 @@ Other state examples:
 
 ### Attributes
 
+Not supported in [limited templates](#limited-templates).
+
 You can print an attribute with `state_attr` if state is defined.
 
 #### Attributes examples
@@ -158,6 +166,8 @@ With strings:
 
 ### Working with Groups
 
+Not supported in [limited templates](#limited-templates).
+
 The `expand` function and filter can be used to sort entities and expand groups. It outputs a sorted array of entities with no duplicates.
 
 #### Expand examples
@@ -183,6 +193,8 @@ The same thing can also be expressed as a filter:
 
 ### Time
 
+`now()` and `utcnow()` are not supported in [limited templates](#limited-templates).
+
 - `now()` returns a datetime object that represents the current time in your time zone.
   - You can also use: `now().second`, `now().minute`, `now().hour`, `now().day`, `now().month`, `now().year`, `now().weekday()` and `now().isoweekday()` and other [`datetime`](https://docs.python.org/3.8/library/datetime.html#datetime.datetime) attributes and functions.
   - Using `now()` will cause templates to be refreshed at the start of every new minute.
@@ -288,6 +300,8 @@ The temperature is 25°C
 
 ### Distance
 
+Not supported in [limited templates](#limited-templates).
+
 - `distance()` will measure the distance in kilometers between home, entity, coordinates.
 - `closest()` will find the closest entity.
 
@@ -489,11 +503,11 @@ To evaluate a response, go to **Developer Tools** -> **Template**, create your o
 ```yaml
 {% set value_json=
     {"name":"Outside",
-	 "device":"weather-ha",
+     "device":"weather-ha",
      "data":
-	    {"temp":"24C",
-		 "hum":"35%"
-		 }	}%}
+        {"temp":"24C",
+         "hum":"35%"
+         } }%}
 
 {{value_json.data.hum[:-1]}}
 ```

source/_docs/scripts.markdown

@@ -160,7 +160,7 @@ The template is re-evaluated whenever an entity ID that it references changes st
 
 ### Wait for Trigger
 
-This action can use the same triggers that are available in an automation's `trigger` section. See [Automation Trigger](/docs/automation/trigger). The script will continue whenever any of the triggers fires.
+This action can use the same triggers that are available in an automation's `trigger` section. See [Automation Trigger](/docs/automation/trigger). The script will continue whenever any of the triggers fires. All previously defined [trigger_variables](/docs/automation/trigger#trigger_variables), [variables](#variables) and [script variables] are passed to the trigger.
 {% raw %}
 
 ```yaml