Misc tricks - thomasloven/hass-config GitHub Wiki
I wrote a short description of how YAML works aimed at people who normally don't program. Some texts here will repeat some of the things in that description.
YAML node anchors is a simple way to reuse code in Home Assistant configuration files. Basically, you store the value of a key in an anchor while defining it:
# When you write:
key: &anchor value
# It will be interpreted as:
key: value
And then you can reuse it as many times as you want:
# When you write:
another_key: *anchor
yet_another_key: *anchor
# It will be interpreted as:
another_key: value
yet_another_key: value
anchor
should be a single word, but may contain underscores.
value
can be any valid YAML structure, strings, numbers, sequences or mappings.
The merge key can be used in yaml to merge a mapping into another:
# When you write:
key1: value1
key2: value2
<<:
key3: value3
key4: value4
# It will be interpreted as:
key1: value1
key2: value2
key3: value3
key4: value4
This is very useful in combination with node anchors:
# When you write:
thing_a:
key1: value1
<<: &common_things
key2: value2
key3: value3
thing_b:
key1: valueA
<<: *common_things
# It will be interpreted as:
thing_a:
key1: value1
key2: value2
key3: value3
thing_b:
key1: valueA
key2: value2
key3: value3
Probably the most common usage of node anchors in Home Assistant is in packages. People like to add a configuration section to their packages which contain something like:
homeassistant:
customize:
package.node_anchors:
common: &common
package: "my package"
sensor.my_sensor:
<<: *common
This will add the attribute package
with the value "my package"
to every entity where it's been specified. The point of this is that if you open up the more-info dialog of the entity, or find it in the dev-states list, you can easily see where it's definition can be found.
Note that the package.node_anchors
"entity" is just a dummy to have somewhere to define the node anchor. It could just as well be defined in the first real entity.
Another good use for node anchors is as a variable for any repeated value.
In my coffee maker control package, I define a node anchor &cfe_switch
which contains the entity id of the coffee maker outlet switch. I then use *cfe_switch
in several automations to minimize the risk of me mistyping the entity.
If you design a very good package, you may want to distribute it to other users. It might then be a good idea to put a number of definitions near the top of the code, in a customize:
section, for example, with values the user may want to customize. This might be things like output messages, time offsets, entity ids etc.
Since Home Assistant 0.107 this trick is not guaranteed to work. This comes down to optimization which decreases the Lovelace interface load times at the cost of having to load a few cards, rows and entities later.
However, with one(sic!) more line of configuration, hui-element can be used instead.
In Lovelace, there are three things that can be replaced with custom elements. Those are cards, picture-elements
elements and entities
rows (I'll just call them "things").
To replace either of them with a custom element you set the type:
attribute of the thing to custom:<tag>
where <tag>
is the html element name of the thing, such as card-modder
, slider-entity-row
or radial-menu
.
Now here's the magic part. All things have the same interface, and can be used interchangeably. They are not meant to be, but it is possible. Furthermore, all built-in things have a <tag>
that can be used to put them anywhere in the same way. The tag is usually on the form hui-<name>-<thing>
, such as hui-glance-card
or hui-state-icon-element
. The best way to find the names are from the names of the source files for cards, elements and entity rows (there's also a few special rows).
Example:
- type: entities
entities:
- light.bed_light
- type: custom:hui-glance-card
entities:
- light.bed_light
- light.kithen_lights
- light.kitchen_lights
- type: custom:hui-state-icon-element
entity: light.bed_light
- type: picture-elements
image: http://placekitten.com/g/800/600
elements:
- type: custom:hui-markdown-card
style:
# Note that left and top are required, but any style added here will be applied to the thing
# The google search word you're looking for is "CSS"
left: 50%
top: 50%
border: solid 5xp red
# Any variable that can be used in a theme can be used as well, but preceded with two dashes and enclosed in quotes
"--ha-card-background": rgba(0,0,128,0.5)
"--primary-text-color": white
content: |
# Hello!