Add support for more advanced forms of overriding
This commit is contained in:
Dermot Duffy
+150
-23
@@ -1,39 +1,166 @@
|
||||
# `overrides`
|
||||
|
||||
Various parts of card configuration may [conditionally](conditions.md) be
|
||||
overridden (e.g. to hide the menu in fullscreen mode).
|
||||
The card configuration may [conditionally](conditions.md) be overridden (e.g. to
|
||||
hide the menu in fullscreen mode).
|
||||
|
||||
```yaml
|
||||
overrides:
|
||||
- conditions:
|
||||
[condition]
|
||||
overrides:
|
||||
[override]
|
||||
[...]
|
||||
```
|
||||
|
||||
Not all configuration parameters are overriddable, some because it doesn't make
|
||||
sense for that parameter to vary, and many because of the extra complexity of
|
||||
supporting overriding given the lack of compelling usecases ([please request new
|
||||
overridable parameters
|
||||
here!](https://github.com/dermotduffy/frigate-hass-card/issues/new/choose)).
|
||||
!> 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!
|
||||
|
||||
Each entry under the top-level `overrides` configuration block should be a list
|
||||
item, that has both of the following parameters set:
|
||||
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.md) that must evaluate to `true` in order for the overrides to be applied. |
|
||||
| `overrides` | | Configuration overrides to be applied. Any configuration parameter matching [Overrideable parameters](overrides.md?id=overrideable-parameters) can be overridden. |
|
||||
| `delete` | | An array of configuration paths to delete. See below. |
|
||||
| `merge` | | A dictionary of configuration paths to merge. See below. |
|
||||
| `set` | | A dictionary of configuration paths to set. See below. |
|
||||
|
||||
## Overrideable parameters
|
||||
## Configuration Paths
|
||||
|
||||
| Configuration Key | Overrideable |
|
||||
| - | - |
|
||||
| [`cameras.*`](cameras/README.md) | :white_check_mark: |
|
||||
| [`cameras_global.*`](cameras/README.md) | :white_check_mark: |
|
||||
| [`dimensions.*`](dimensions.md) | :white_check_mark: |
|
||||
| [`image.*`](image.md) | :white_check_mark: |
|
||||
| [`live.controls.*`](live.md?id=controls), [`live.display.*`](live.md?id=display), [`live.microphone.*`](live.md?id=microphone), [`live.show_image_during_load`](live.md), [`live.zoomable`](live.md) | :white_check_mark: |
|
||||
| [`menu.*`](menu.md) | :white_check_mark: |
|
||||
| [`view.*`](view.md) | :white_check_mark: |
|
||||
| *(Everything else)* | :heavy_multiplication_x: |
|
||||
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 2nd camera:
|
||||
|
||||
```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'
|
||||
}
|
||||
```
|
||||
+25
-7
@@ -424,7 +424,7 @@ overrides:
|
||||
- condition: state
|
||||
entity: light.office_main_lights
|
||||
state: 'on'
|
||||
overrides:
|
||||
merge:
|
||||
menu:
|
||||
position: bottom
|
||||
```
|
||||
@@ -451,7 +451,7 @@ overrides:
|
||||
- condition: state
|
||||
entity: binary_sensor.alarm_armed
|
||||
state: 'off'
|
||||
overrides:
|
||||
merge:
|
||||
view:
|
||||
default: image
|
||||
```
|
||||
@@ -471,7 +471,7 @@ overrides:
|
||||
fullscreen: true
|
||||
- condition: display_mode
|
||||
display_mode: grid
|
||||
overrides:
|
||||
merge:
|
||||
live:
|
||||
display:
|
||||
grid_columns: 5
|
||||
@@ -497,7 +497,7 @@ overrides:
|
||||
- conditions:
|
||||
- condition: expand
|
||||
expand: true
|
||||
overrides:
|
||||
merge:
|
||||
menu:
|
||||
style: overlay
|
||||
```
|
||||
@@ -520,11 +520,29 @@ overrides:
|
||||
- conditions:
|
||||
- condition: fullscreen
|
||||
fullscreen: true
|
||||
overrides:
|
||||
merge:
|
||||
menu:
|
||||
style: none
|
||||
```
|
||||
|
||||
### Remove a camera when an entity state changes
|
||||
|
||||
This example removes a camera from the card when an entity is disabled (e.g. a switch controlling power to the camera).
|
||||
|
||||
```yaml
|
||||
type: custom:frigate-card
|
||||
cameras:
|
||||
- camera_entity: camera.office
|
||||
- camera_entity: camera.kitchen
|
||||
overrides:
|
||||
- conditions:
|
||||
- condition: state
|
||||
entity: switch.kitchen_camera_power
|
||||
state: off
|
||||
delete:
|
||||
- 'cameras[1]'
|
||||
```
|
||||
|
||||
## PTZ control
|
||||
|
||||
The card supports using PTZ controls to conveniently control pan, tilt and zoom for cameras. This example shows the PTZ controls on the `live` view. Note that if your camera engine supports it (e.g. `frigate`) this will just work out of the box with no configuration at all.
|
||||
@@ -568,7 +586,7 @@ overrides:
|
||||
- conditions:
|
||||
- condition: screen
|
||||
media_query: '(orientation: landscape)'
|
||||
overrides:
|
||||
merge:
|
||||
menu:
|
||||
position: left
|
||||
```
|
||||
@@ -584,7 +602,7 @@ overrides:
|
||||
- conditions:
|
||||
- condition: screen
|
||||
media_query: '(max-width: 300px)'
|
||||
overrides:
|
||||
merge:
|
||||
menu:
|
||||
style: none
|
||||
live:
|
||||
|
||||
Reference in New Issue
Block a user