v8.0.0

This release is a major release of the plugin and it has breaking changes.

⚠️⚠️⚠️ Breaking Changes ⚠️⚠️⚠️

1. extend_from_base property has been removed from the exceptions config

If you want to have the previous functionality, you need to replace:

extend_from_base: true

by

extend_from: base

And remove any occurrence of:

extend_from_base: false

2. Exceptions are merged

Previously, if multiple exceptions match, the last one were the one used. From now on, if multiple exceptions match, they will be merged. Check the extendable configurations section for more info about how two configurations are merged.

3. Changed the merging logic of an exception extending from the base

Previously, when one exception extended from the base, the options that were in the exception remain, and the options that existed in the base but were not defined in the exception were extended. If both config had an order option, these were merged too, but if the two order options contained an item with the same item property, the last one ruled over the previous.

In this new version the first part remains the same, but the merging of two order options with items with the same item property changed. If two order options are merged and they contain one or more items with the same item property, they will be merged following the same logic: what is in the original item remains, what is in the extending one and not in the original item will be extended. Check the extendable configurations section for more info about how two configurations are merged.

Noteworthy Changes

1. js_variables and jinja_variables allow more variables types

Previously, js_variables and jinja_variables only allowed strings, numbers and booleans. Now it is possible to add more variable types. The next examples using js_variables and jinja_variables will set the same title ("Title 80 dog"):

js_variables example

js_variables:
  my_string: Title
  my_number: 100
  my_boolean: true
  my_object:
    prop1: 4
    prop2: 5
  my_array:
    - cat
    - dog
    - bird
title: |
  [[[
    if (my_boolean) {
      return `${my_string} ${(my_number * my_object.prop1) / my_object.prop2} ${my_array[1]}`;
    }
    return 'Home Assistant';
  ]]]

jinja_variables example

jinja_variables:
  my_string: Title
  my_number: 100
  my_boolean: true
  my_dictionary:
    prop1: 4
    prop2: 5
  my_list:
    - cat
    - dog
    - bird
title: |
  {% if my_boolean %}
    {{ my_string }} {{ ((my_number * my_dictionary.prop1) / my_dictionary.prop2) | int }} {{ my_list.1 }}
  {% else %}
    Home Assistant
  {% endif %}

2. New is_owner option in the exceptions

Now the exceptions configurations accept a new option is_owner.

Property	Type	Required	Description
is_owner	Boolean	no	Checks if the user is owner of the system. This option can be set alone or combined with user, not_user, device, not_device, or is_admin. If it is used together with one of these options they will be taken as conditions separated by a logical OR

3. Extendable configurations

Extendable configurations (extendable_configs) is an object containing different configurations options that could be extended from the main configuration, from the exceptions or from another extendable configuration, making them a very flexible option to share configuration blocks. To specify that a configuration should extend from an extendable configuration, the extend_from option should be used specifying the extendable configuration name(s).

Extending from a configuration basically means "import what I don't already have", so if a configuration already have an option, it will prevail and it will not be overridden if the configuration is extended. For example, the next configuration has a main configuration extending from an extendable configuration named example, let's analyse what will be the result of that extend.

title: Custom Title
order:
  - item: overview
    name: Dashboard
    order: 3
  - new_item: true
    item: Integrations
    href: "/config/integrations"
    icon: mdi:puzzle
    order: 2
extend_from: example
extendable_configs:
  example:
    title: My Home
    subtitle: Assistant
    order:
      - item: overview
        icon: mdi:monitor-dashboard
        order: 0
      - new_item: true
        item: Google
        href: https://mrdoob.com/projects/chromeexperiments/google-gravity/
        icon: mdi:earth
        target: _blank
        order: 1

1. As the title option is defined in the main configuration, it will not get the title option from the extendable configuration.
2. As the subtitle option is not defined in the main configuration, it will be get from the extendable configuration
3. As the main configuration and the extendable configuration both have an order option, it will be merged:
   1. Both orders have an overview item, so it will be merged. As the main config order-item has also an order property, it will not be extended, but as the extendable order-item has an icon property that doesn't exist in the main config order-item, it will be extended
   2. As the extendable order-item doesn't have a name property, it will remain there
   3. The Integrations doesn't exist in the extendable order so it will remain as it is
   4. The Google extendable item doesn't exist in the main config, so it will be extended

The resulted main config after the extending process will be:

title: Custom Title
subtitle: Assistant
order:
  - new_item: true
    item: Google
    href: https://mrdoob.com/projects/chromeexperiments/google-gravity/
    icon: mdi:earth
    target: _blank
    order: 1
  - new_item: true
    item: Integrations
    href: "/config/integrations"
    icon: mdi:puzzle
    order: 2
  - item: overview
    name: Dashboard
    icon: mdi:monitor-dashboard
    order: 3
  

It is possible to extend from multiple configurations and they will be extended in order, as shown in the next example:

extend_from:
  - colors
  - titles
extendable_configs:
  colors:
    icon_color: red
    text_color: red
  titles:
    title: Custom Title
    subtitle: Custom Subtitle

As already mentioned, an extendable configuration can extend from other extendable configurations:

title: Custom Title
extend_from: example
extendable_configs:
  colorful:
    title_color: red,
    subtitle_color: blue
  example:
    subtitle: Assistant
    extend_from: colorful

The resulted main config will be:

title: Custom Title
subtitle: Assistant
title_color: red,
subtitle_color: blue

In the case of exceptions, they can also extend from the main configuration if base is used in the extend_from option:

title: Custom Title
extend_from: example
extendable_configs:
  colorful:
    title_color: red,
    subtitle_color: blue
  example:
    subtitle: Assistant
    extend_from: colorful
exceptions:
  - user:
    - ElChiniNet
    order:
      - item: overview
        name: Dashboard
        icon: mdi:monitor-dashboard
        order: 3
    extend_from: base

So, the configuration for the user ElChiniNet will be the same previous main config, plus an order with an order-item.

The next example is a more complex one extending from multiple configurations:

title: My Home
extend_from: admin_config
order:
  - new_item: true
    item: Google
    href: https://mrdoob.com/projects/chromeexperiments/google-gravity/
    icon: mdi:earth
    target: _blank
    order: 1
extendable_configs:
  multicolor:
    icon_color: red
    icon_color_selected: blue
    icon_color_hover: green
    text_color: red
    text_color_selected: blue
    text_color_hover: green
  admin_config:
    order:
      - new_item: true
        item: Integrations
        href: "/config/integrations"
        icon: mdi:puzzle
        order: 2
      - new_item: true
        item: Entities
        href: "/config/entities"
        icon: mdi:hexagon-multiple
        order: 3
  user_config:
    extend_from: multicolor
    hide_all: true
    order:
      - item: overview
        hide: false
exceptions:
  - is_admin: true
    extend_from:
      - multicolor
      - admin_config
    order:
      - item: config
        bottom: true
  - user:
    - ElChiniNet
    - Palaus
    etend_from: base
    title: HA
  - user:
    - Jim Hawkins
    - Long John Silver
    extend_from: user_config
    order:
      - item: overview
        name: Dashboard

Important

• You need to be careful of circular dependencies when extending configurations, if this is detected an error will be thrown
• You can only use base inside extend_from if you are in an exception, trying to use it in the main config or in an extendable configuration will throw and error

---

🚀 Features

• Next release
  • PR: #257 by @elchininet

🧩 Dependencies

• [Dependencies]: Bump the dependencies-dev group with 3 updates
  • PR: #251 by @dependabot[bot]

📝 Documentation

• Next release
  • PR: #257 by @elchininet