mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-18 23:06:58 +00:00
Documentation for template expand (#9394)
* Documentation for template expand
* ✏️ Tweak
This commit is contained in:
Penny Wood
Franck Nijhof
parent
8d99182d78
commit
4e9d88c40d
@ -33,7 +33,6 @@ We will not go over the basics of the syntax, as Jinja2 does a great job of this
|
||||
|
||||
The frontend has a template editor tool to help develop and debug templates. Click on the <img src='/images/screenshots/developer-tool-templates-icon.png' alt='template developer tool icon' class="no-shadow" height="38" /> icon, create your template in the _Template editor_ and check the results on the right.
|
||||
|
||||
|
||||
Templates can get big pretty fast. To keep a clear overview, consider using YAML multiline strings to define your templates:
|
||||
|
||||
{% raw %}
|
||||
@ -54,9 +53,10 @@ script:
|
||||
|
||||
## {% linkable_title Home Assistant template extensions %}
|
||||
|
||||
Extensions allow templates to access all of the Home Assistant specific states and adds other convenience functions and filters.
|
||||
Extensions allow templates to access all of the Home Assistant specific states and adds other convenience functions and filters.
|
||||
|
||||
### {% linkable_title States %}
|
||||
|
||||
- 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`.
|
||||
@ -67,7 +67,6 @@ script:
|
||||
|
||||
Besides the normal [state object methods and properties](/topics/state_object/), `states.sensor.temperature.state_with_unit` will print the state of the entity and, if available, the unit.
|
||||
|
||||
|
||||
#### {% linkable_title States examples %}
|
||||
The next two statements result in the same value if the state exists. The second one will result in an error if the state does not exist.
|
||||
|
||||
@ -112,7 +111,6 @@ Other state examples:
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
|
||||
### {% linkable_title Attributes %}
|
||||
|
||||
You can print an attribute with `state_attr` if state is defined.
|
||||
@ -143,8 +141,33 @@ With strings:
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Working with Groups %}
|
||||
|
||||
The `expand` function and filter can be used to sort entities and expand groups. It outputs a sorted array of entities with no duplicates.
|
||||
|
||||
#### {% linkable_title Expand examples %}
|
||||
|
||||
{% raw %}
|
||||
```text
|
||||
{% for tracker in expand('device_tracker.paulus', 'group.child_trackers') %}
|
||||
{{ state_attr(tracker, 'battery') }}
|
||||
{%- if not loop.last %}, {% endif -%}
|
||||
{% endfor %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The same thing can also be expressed as a filter:
|
||||
|
||||
{% raw %}
|
||||
```text
|
||||
{{ ['device_tracker.paulus', 'group.child_trackers'] | expand
|
||||
| selectattr("attributes.battery", 'defined')
|
||||
| join(', ', attribute="attributes.battery") }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Time %}
|
||||
|
||||
- `now()` will be rendered as the current time in your time zone.
|
||||
- For specific values: `now().second`, `now().minute`, `now().hour`, `now().day`, `now().month`, `now().year`, `now().weekday()` and `now().isoweekday()`
|
||||
- `utcnow()` will be rendered as UTC time.
|
||||
@ -156,10 +179,12 @@ With strings:
|
||||
- Filter `timestamp_custom(format_string, local_boolean)` will convert a UNIX timestamp to a custom format, the use of a local timestamp is default. Supports the standard [Python time formatting options](https://docs.python.org/3/library/time.html#time.strftime).
|
||||
|
||||
### {% linkable_title Distance %}
|
||||
|
||||
- `distance()` will measure the distance in kilometers between home, entity, coordinates.
|
||||
- `closest()` will find the closest entity.
|
||||
|
||||
#### {% linkable_title Distance examples %}
|
||||
|
||||
If only one location is passed in, Home Assistant will measure the distance from home.
|
||||
|
||||
{% raw %}
|
||||
@ -174,12 +199,14 @@ These can also be combined in any combination:
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Find entities closest to the Home Assistant location:
|
||||
#### {% linkable_title Closest examples %}
|
||||
|
||||
The closest function and filter will find the closest entity to the Home Assisant location:
|
||||
|
||||
{% raw %}
|
||||
```text
|
||||
Query all entities: {{ closest(states) }}
|
||||
Query all entities of a specific domain: {{ closest('states.device_tracker') }}
|
||||
Query all entities of a specific domain: {{ closest(states.device_tracker) }}
|
||||
Query all entities in group.children: {{ closest('group.children') }}
|
||||
Query all entities in group.children: {{ closest(states.group.children) }}
|
||||
```
|
||||
@ -203,11 +230,37 @@ Since closest returns a state, we can combine it with distance too.
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The last argument of the closest function has an implicit `expand`, and can take any iterable sequence of states or entity IDs, and will expand groups:
|
||||
|
||||
{% raw %}
|
||||
```text
|
||||
Closest out of given entities:
|
||||
{{ closest(['group.children', states.device_tracker]) }}
|
||||
Closest to a coordinate:
|
||||
{{ closest(23.456, 23.456, ['group.children', states.device_tracker]) }}
|
||||
Closest to some entity:
|
||||
{{ closest(states.zone.school, ['group.children', states.device_tracker]) }}
|
||||
```
|
||||
|
||||
It will also work as a filter over a iterable group of entities or groups:
|
||||
|
||||
```text
|
||||
Closest out of given entities:
|
||||
{{ ['group.children', states.device_tracker] | closest }}
|
||||
Closest to a coordinate:
|
||||
{{ ['group.children', states.device_tracker] | closest(23.456, 23.456) }}
|
||||
Closest to some entity:
|
||||
{{ ['group.children', states.device_tracker] | closest(states.zone.school) }}
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Formatting %}
|
||||
|
||||
- `float` will format the output as float.
|
||||
|
||||
### {% linkable_title Numeric functions and filters %}
|
||||
|
||||
Some of these functions can also be used in a [filter](http://jinja.pocoo.org/docs/dev/templates/#id11). This means they can act as a normal function like this `sqrt(2)`, or as part of a filter like this `2|sqrt`.
|
||||
|
||||
- `log(value, base)` will take the logarithm of the input. When the base is omitted, it defaults to `e` - the natural logarithm. Can also be used as a filter.
|
||||
@ -225,6 +278,7 @@ Some of these functions can also be used in a [filter](http://jinja.pocoo.org/do
|
||||
- Filter `value_one|bitwise_or(value_two)` perform a bitwise or(\|) operation with two values.
|
||||
|
||||
### {% linkable_title Regular expressions %}
|
||||
|
||||
- Filter `string|regex_match(find, ignorecase=FALSE)` will match the find expression at the beginning of the string using regex.
|
||||
- Filter `string|regex_search(find, ignorecase=FALSE)` will match the find expression anywhere in the string using regex.
|
||||
- Filter `string|regex_replace(find='', replace='', ignorecase=False)` will replace the find expression with the replace string using regex.
|
||||
@ -328,13 +382,13 @@ To evaluate a response, go to the <img src='/images/screenshots/developer-tool-t
|
||||
## {% linkable_title Some more things to keep in mind %}
|
||||
|
||||
### {% linkable_title `entity_id` that begins with a number %}
|
||||
|
||||
If your template uses an `entity_id` that begins with a number (example: `states.device_tracker.2008_gmc`) you must use a bracket syntax to avoid errors caused by rendering the `entity_id` improperly. In the example given, the correct syntax for the device tracker would be: `states.device_tracker['2008_gmc']`
|
||||
|
||||
### {% linkable_title Templates without entities using `now()` %}
|
||||
|
||||
Note that templates that depend on time (`now()`) and do not use any entities will not be updated as it only happens on entity state changes. For more information and examples refer to [`template` sensor documentation](/components/sensor.template/#working-without-entities)
|
||||
|
||||
|
||||
### {% linkable_title Priority of operators %}
|
||||
|
||||
The default priority of operators is that the filter (`|`) has priority over everything except brackets. This means that:
|
||||
@ -346,4 +400,3 @@ The default priority of operators is that the filter (`|`) has priority over eve
|
||||
{% endraw %}
|
||||
|
||||
Would round `10` to 2 decimal places, then divide `states('sensor.temperature')` by that.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user