Dermot Duffy
17146c8ca6
The `initialized` state (used in conditions/triggers) was written once and never cleared, so it meant "has this card ever been initialized" while everything reading it took it as "is this card usable now". Home Assistant takes a card off the page and puts it back whenever its dashboard tab is left and returned to, so the card initialized again while the state claimed it was initialized throughout: `trigger: initialized` fired once per card rather than once per startup, and automations were dropped in between. The card lifecycle is now an explicit state machine (`SessionManager`), the only writer of `initialized`, which separates a card that is starting up from one initializing part of itself again while it runs. A new `ever` parameter (conditions/triggers) selects the old latched behaviour. `remote_control` uses that parameter to keep its two camera priorities correct under repeated starts. With `camera_priority: entity` the card now re-reads the entity every time it starts, so a camera selected while the card was away is picked up on return. With `camera_priority: card` the card writes the entity on its first start only, unchanged, since repeating that write would overwrite a camera the user had selected. Closes: #2642 BREAKING CHANGE: `condition: initialized` is now `false` whenever the card is not usable, and `trigger: initialized` fires each time the card starts up rather than only the first time. Set `ever: true` on either to keep the previous behaviour.
162 lines
4.7 KiB
Markdown
162 lines
4.7 KiB
Markdown
# `overrides`
|
|
|
|
The card configuration may [conditionally](conditions-triggers.md) be overridden (e.g. to
|
|
hide the menu in fullscreen mode).
|
|
|
|
```yaml
|
|
overrides:
|
|
- conditions:
|
|
- [condition]
|
|
# [...]
|
|
```
|
|
|
|
> [!WARNING]
|
|
> Whilst all configuration parameters are theoretically overridable, in some instances a configuration variable may only be consulted on startup or changing its value may negatively impact behavior -- override results may vary!
|
|
|
|
> [!WARNING]
|
|
> Avoid an override whose `conditions` depend on a value that the override itself
|
|
> changes. Applying it changes what its own conditions were matching, so it may
|
|
> turn itself on and off repeatedly, or undo the very change that applied it. Examples: a [`camera`](conditions-triggers.md?id=camera) condition that sets
|
|
> `cameras`, an
|
|
> [`initialized`](conditions-triggers.md?id=initialized) condition that sets
|
|
> anything the card must start up again to use.
|
|
|
|
The top-level `overrides` configuration block expects a list, with each list
|
|
item containing `conditions` and at least one of `merge`, `delete` or `set` specified.
|
|
|
|
| Option | Default | Description |
|
|
| ------------ | ------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
| `conditions` | | A list of [conditions](conditions-triggers.md) that must evaluate to `true` in order for the overrides to be applied. |
|
|
| `delete` | | An array of configuration paths to delete. See [`delete`](#delete). |
|
|
| `merge` | | A dictionary of configuration paths to merge. See [`merge`](#merge). |
|
|
| `set` | | A dictionary of configuration paths to set. See [`set`](#set). |
|
|
|
|
## Configuration Paths
|
|
|
|
The `delete`, `merge` and `set` parameters take configuration paths. Paths are dot-separated references to particular configuration parameters. To refer to list elements use `[n]` notation.
|
|
|
|
For example the path `cameras[1].dimensions.aspect_ratio` refers to the `aspect_ratio` parameter below:
|
|
|
|
```yaml
|
|
cameras:
|
|
- camera_entity: camera.other
|
|
- camera_entity: camera.relevant
|
|
dimensions:
|
|
aspect_ratio: '16:9'
|
|
```
|
|
|
|
## `delete`
|
|
|
|
An array of configuration paths to delete.
|
|
|
|
```yaml
|
|
overrides:
|
|
- conditions:
|
|
- [condition]
|
|
delete:
|
|
- [path_1]
|
|
- [path_2]
|
|
```
|
|
|
|
### Examples
|
|
|
|
Delete the 3rd camera (it indexes from 0):
|
|
|
|
```yaml
|
|
overrides:
|
|
- conditions:
|
|
- [condition]
|
|
delete:
|
|
- 'cameras[2]'
|
|
```
|
|
|
|
Delete the menu style parameter, thus falling back to the default:
|
|
|
|
```yaml
|
|
overrides:
|
|
- conditions:
|
|
- [condition]
|
|
delete:
|
|
- 'menu.style'
|
|
```
|
|
|
|
## `merge`
|
|
|
|
Specifies an object to recursively merge into existing configuration.
|
|
|
|
| Option | Default | Description |
|
|
| -------------------- | ------- | -------------------------------------------------------------------------------------- |
|
|
| [configuration path] | | Arbitrary configuration object to merge. Must be an object (i.e. not a literal value). |
|
|
|
|
### Examples
|
|
|
|
Hide the menu when a given condition is met:
|
|
|
|
```yaml
|
|
overrides:
|
|
- conditions:
|
|
- [condition]
|
|
merge:
|
|
menu: { style: 'hidden' }
|
|
```
|
|
|
|
Enable thumbnails below the `live` feed:
|
|
|
|
```yaml
|
|
overrides:
|
|
- conditions:
|
|
- [condition]
|
|
merge:
|
|
'live.controls.thumbnails': { mode: 'below' }
|
|
```
|
|
|
|
Also enables thumbnails below the `live` feed, but without using the dot-separated notation:
|
|
|
|
```yaml
|
|
overrides:
|
|
- conditions:
|
|
- [condition]
|
|
merge:
|
|
live: { controls: { thumbnails: { mode: 'below' } } }
|
|
```
|
|
|
|
## `set`
|
|
|
|
Specifies a value to set in the configuration. This differs from `merge` in that the existing value is entirely replaced.
|
|
|
|
| Option | Default | Description |
|
|
| -------------------- | ------- | ----------------------------------------------------- |
|
|
| [configuration path] | | Arbitrary configuration value / object / list to set. |
|
|
|
|
### Examples
|
|
|
|
Set the entire menu configuration to defaults with the exception of the `style` which is set to `overlay`.
|
|
|
|
```yaml
|
|
overrides:
|
|
- conditions:
|
|
- [condition]
|
|
set:
|
|
menu: { style: 'overlay' }
|
|
```
|
|
|
|
Set the menu style but without touching the other `menu` parameters:
|
|
|
|
```yaml
|
|
overrides:
|
|
- conditions:
|
|
- [condition]
|
|
set:
|
|
'menu.style': 'overlay'
|
|
```
|
|
|
|
That is equivalent to merging the following:
|
|
|
|
```yaml
|
|
overrides:
|
|
- conditions:
|
|
- [condition]
|
|
merge:
|
|
menu: { style: 'overlay' }
|
|
```
|