Add availability explanation to template advanced #36910
Conversation
home-assistant
bot
added
has-parent
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughThe documentation update introduces a new section on "Availability" in the templating documentation for Home Assistant. This section explains how availability templates can be used to conditionally render state- and trigger-based templates. The documentation clarifies the criteria for determining an entity's availability, including specific truthy values that indicate availability and the implications of an entity being marked as unavailable. Changes
Sequence DiagramsequenceDiagram
participant Template as Availability Template
participant Entity as Home Assistant Entity
Template->>Entity: Evaluate availability
alt Availability Conditions Met
Entity-->>Template: Entity Available
Template->>Entity: Render Full Template
else Availability Conditions Not Met
Entity-->>Template: Entity Unavailable
Template->>Entity: Suppress Attributes
end
The sequence diagram illustrates the process of evaluating an entity's availability using an availability template, showing how the template determines whether the full entity information should be rendered or suppressed. Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
source/_docs/configuration/templating.markdown (3)
359-359: Fix hyphenation in "case sensitive".The term should be hyphenated as "case-sensitive" when used as a compound adjective.
-Note that the string comparison not case sensitive; `"TrUe"` and `"yEs"` are allowed. +Note that the string comparison is not case-sensitive; `"TrUe"` and `"yEs"` are allowed.🧰 Tools
🪛 LanguageTool
[misspelling] ~359-~359: This word is normally spelled with a hyphen.
Context: ...e. Note that the string comparison not case sensitive;"TrUe"and"yEs"` are allowed. It ...(EN_COMPOUNDS_CASE_SENSITIVE)
361-363: Fix possessive pronoun "it's".Use "its" (possessive) instead of "it's" (contraction of "it is").
-At which point, it will again render the icon according to it's template. +At which point, it will again render the icon according to its template.🧰 Tools
🪛 LanguageTool
[grammar] ~363-~363: Did you mean the possessive pronoun “its”?
Context: ...will again render the icon according to it's template. #### Availability use exampl...(IT_S_ITS)
365-379: Enhance the example with comments and realistic conditions.While the example is functional, it could be more educational with inline comments and realistic availability conditions.
template: - sensor: - name: "Transmission Up Speed" unit_of_measurement: "kB/s" state: "{{ states.sensor.test_sensor.state }}" - availability: "{{ is_state('sensor.test_sensor', 'on') }}" + # Only render templates if the test sensor is connected and reporting valid data + availability: >- + {{ + is_state('sensor.test_sensor', 'on') and + not is_state('sensor.test_sensor','unavailable') and + not is_state('sensor.test_sensor','unknown') + }} icon: "{% if states.sensor.test_sensor.state == 'on' %}mdi:on{% else %}mdi:off{% endif %}"
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_docs/configuration/templating.markdown(1 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_docs/configuration/templating.markdown
[misspelling] ~359-~359: This word is normally spelled with a hyphen.
Context: ...e. Note that the string comparison not case sensitive; "TrUe"and"yEs"` are allowed. It ...
(EN_COMPOUNDS_CASE_SENSITIVE)
[grammar] ~363-~363: Did you mean the possessive pronoun “its”?
Context: ...will again render the icon according to it's template. #### Availability use exampl...
(IT_S_ITS)
🔇 Additional comments (1)
source/_docs/configuration/templating.markdown (1)
355-358: LGTM! Clear and concise introduction.The introduction effectively explains the purpose of availability templates and their role in suppressing template rendering.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_docs/configuration/templating.markdown(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
🔇 Additional comments (3)
source/_docs/configuration/templating.markdown (3)
361-363: 🛠️ Refactor suggestionImprove clarity of implications explanation.
The explanation could be clearer about what happens when an entity becomes unavailable.
Apply this diff to improve clarity:
-For example, if the entity has the icon `mdi:on` and becomes unavailable, the icon will remain `mdi:on` until the entity becomes available. At that point, it will again render the icon according to its template. +For example, if the entity has the icon `mdi:on` and becomes unavailable, the icon will remain `mdi:on` until the entity becomes available. At that point, it will again render the icon according to its template.Likely invalid or redundant comment.
355-357: 🛠️ Refactor suggestionImprove clarity of the introduction.
The current wording could be clearer about how availability templates affect template rendering.
Apply this diff to improve clarity:
-Both state- and trigger-based templates can have an availability template that suppresses further rendering of other templates if the availability renders as `False`. +Both state- and trigger-based templates can have an availability template that suppresses further rendering of other templates if the availability renders as `False`.Likely invalid or redundant comment.
359-360: 🛠️ Refactor suggestionImprove clarity of availability behavior explanation.
The explanation could be clearer about valid values and case-insensitivity.
Apply this diff to improve clarity:
-If the template either fails to render or returns True, "1", "true", "yes", "on", "enable", or a non-zero number, the entity will be available. For any other value, the entity will be `unavailable`. Note that the string comparison is not case-sensitive; `"TrUe"` and `"yEs"` are allowed. +If the template either fails to render or returns True, "1", "true", "yes", "on", "enable", or a non-zero number, the entity will be available. For any other value, the entity will be `unavailable`. Note that the string comparison is not case-sensitive; `"TrUe"` and `"yEs"` are allowed.Likely invalid or redundant comment.
| #### Availability use example | ||
|
|
||
| {% raw %} | ||
|
|
||
| ```yaml | ||
| template: | ||
| - sensor: | ||
| - name: "Transmission Up Speed" | ||
| unit_of_measurement: "kB/s" | ||
| state: "{{ states.sensor.test_sensor.state }}" | ||
| availability: "{{ is_state('sensor.test_sensor', 'on') }}" | ||
| icon: "{% if states.sensor.test_sensor.state == 'on' %}mdi:on{% else %}mdi:off{% endif %}" | ||
| ``` | ||
|
|
||
| {% endraw %} |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Improve the example to be more realistic and clear.
The current example has several issues:
- Uses a test sensor which may not be available.
- Uses an 'on' state which is not typical for sensors.
- Mixes availability and icon conditions which may be confusing.
Consider using this more realistic example:
template:
- sensor:
- - name: "Transmission Up Speed"
- unit_of_measurement: "kB/s"
- state: "{{ states.sensor.test_sensor.state }}"
- availability: "{{ is_state('sensor.test_sensor', 'on') }}"
- icon: "{% if states.sensor.test_sensor.state == 'on' %}mdi:on{% else %}mdi:off{% endif %}"
+ - name: "Living Room Temperature"
+ unit_of_measurement: "°C"
+ state: "{{ states('sensor.living_room_temp_raw') }}"
+ availability: >
+ {{ not is_state('sensor.living_room_temp_raw', 'unavailable')
+ and not is_state('sensor.living_room_temp_raw', 'unknown') }}
+ icon: >
+ {% if states('sensor.living_room_temp_raw') | float > 25 %}
+ mdi:thermometer-high
+ {% else %}
+ mdi:thermometer-low
+ {% endif %}This example:
- Uses a more realistic temperature sensor scenario
- Shows proper availability checking for sensor states
- Demonstrates a meaningful icon template based on temperature values
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| #### Availability use example | |
| {% raw %} | |
| ```yaml | |
| template: | |
| - sensor: | |
| - name: "Transmission Up Speed" | |
| unit_of_measurement: "kB/s" | |
| state: "{{ states.sensor.test_sensor.state }}" | |
| availability: "{{ is_state('sensor.test_sensor', 'on') }}" | |
| icon: "{% if states.sensor.test_sensor.state == 'on' %}mdi:on{% else %}mdi:off{% endif %}" | |
| ``` | |
| {% endraw %} | |
| #### Availability use example | |
| {% raw %} | |
Proposed change
Adds explanation to
availabilityin template advanced configuration topic.Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit