NemesisRE/kiosk-mode v9.0.0

on GitHub

⚠️⚠️⚠️ BREAKING CHANGE! READ BEFORE UPDATE ⚠️⚠️⚠️

This release is a major refactoring of the plugin and it changes radically the way to react to entity state changes. If you do not use the entity_settings option, this update should not be a risk for you and you can update safely, but if you use entity_settings keep reading because you will not be able to use this option anymore.

1. Removal of entity_settings

The entity_settings and ignore_entity_settings options have been removed. If you have some entity changes configured you need to migrate them. For example the next code:

kiosk_mode:
  entity_settings:
    - entity:
        input_boolean.hide_sidebar: 'on'
      hide_sidebar: true
    - entity:
        sensor.hide_header: 'on'
      hide_header: true
    - entity:
        input_text.kiosk: 'true'
      kiosk: true

Needs to be migrated to this one using templates:

kiosk_mode:
  hide_sidebar: '[[[ is_state("input_boolean.hide_sidebar", "on") ]]]'
  hide_header: '[[[ is_state("sensor.hide_header", "on") ]]]'
  kiosk: '[[[ is_state("input_text.kiosk", "true") ]]]'

Optionally, you can also use Jinja templates:

Note: Jinja templates need a WebSocket call to be rendered, it is recommended to use the JavaScript version because it is rendered straightaway. On top of that, JavaScript templates have access to the client, for example, you can use DOM Apis, something that Jinja templates cannot achieve.

kiosk_mode:
  hide_sidebar: '{{ is_state("input_boolean.hide_sidebar", "on") }}'
  hide_header: '{{ is_state("sensor.hide_header", "on") }}'
  kiosk: '{{ is_state("input_text.kiosk", "true") }}'

If you were using the ignore_entity_settings option, now you need to move that logic to the template that reacts to the entity changes. If you were using the ignore_entity_settings inside user_settings, you can use the template variable user_name, if you were using it inside the admin_settings or non_admin_settings, you can use the variable user_is_admin and if you were using it inside the mobile_settings, you can use the user_agent variable or window. innerWidth using a JavaScript template.

2. All the options can be booleans or JavaScript / Jinja templates

Excluding ignore_mobile_settings and ignore_disable_km, all the options can be set as a JavaScript or a Jinja template that returns a boolean. If you set the option as a string but it is not a valid template, the library will throw an error. If you set a template and it doesn't return a boolean, the option will be set as false and a warning will be thrown.

JavaScript template example:

kiosk_mode:
  hide_header: '[[[ user_name === "ElChiniNet" ]]]'
  hide_sidebar: '[[[ is_state("input_boolean.hide_sidebar", "on") ]]]'

Jinja template example:

kiosk_mode:
  hide_header: '{{ user_name == "ElChiniNet" }}'
  hide_sidebar: '{{ is_state("input_boolean.hide_sidebar", "on") }}'

This solves one of the biggest issues that the plugin has: If one wants to configure entity changes for different users or for admins and non-admins the previous entity_settings was not enough because there was a single place to configure entitites changes and it doesn't take into account users or admin privileges. With this new change it is possible to make something like this:

kiosk_mode:
  ## By default the sidebar will be hidden 
  hide_sidebar: true
  admin_settings:
    ## If the input_boolean.hide_sidebar is off the sidebar will be visible for admins
    hide_sidebar: '[[[ is_state("input_boolean.hide_sidebar", "on") ]]]'
  user_settings:
    - users:
        - "ryan meek"
        - "maykar"
      ## If the input_boolean.hide_sidebar_for_friends is off the sidebar will be visible for ryan meek and maykar
      hide_sidebar: '[[[ is_state("input_boolean.hide_sidebar_for_friends", "on") ]]]'

Note: JavaScript templates use Home Assistant Javascript Templates for the JavaScript templating system. To know all the objects, variables and methods available in the JavaScript templates, consult the proper section in the repository.

Jinja templates will have access to some client side variables that are very useful:

• user_name: String with the logged user's name
• user_is_admin: Bolean value than indicates if the logged user is admin or not
• user_is_owner: Bolean value than indicates if the logged user is the owner or not
• user_agent: User agent of the browser in which Home Assistant is being executed

Advantages of using templates for the options

Using templates for the options gives a lot of flexibility and depending on your objectives you can omit the usage of the conditional configs, so when you start to create conditional configurations, ask yourself if it can be achieved with templates. For example:

kiosk_mode:
  hide_sidebar: false
  hide_header: false
  user_settings:
    - users:
      - "ryan meek"
      - "maykar"
      hide_header: true
  non_admin_settings:
    hide_sidebar: true

Can be transformed into a simpler version:

kiosk_mode:
  hide_header: '[[[ ["maykar", "ryan meek"].includes(user_name) ]]]'
  hide_sidebar: '[[[ !user_is_admin ]]]'

3. New debug options

This release brings two new options:

debug

Example with a valid template

Example with an invalid template

debug_template

Changes

🚀 Features

• Add support for JavaScript / Jinja templates in the kiosk-mode options @elchininet (#369)

🧩 Dependencies

• [Dependencies]: Bump the dependencies-dev group with 6 updates @dependabot[bot] (#442)
• [Dependencies]: Bump home-assistant-javascript-templates from 5.8.0 to 5.10.0 in the dependencies-prod group @dependabot[bot] (#441)
• Update browser_list db @elchininet (#436)

⚙️ Configuration

• [Github Actions]: Bump actions/setup-node from 5 to 6 in the actions-deps group @dependabot[bot] (#440)

📝 Documentation

• Add support for JavaScript / Jinja templates in the kiosk-mode options @elchininet (#369)
• Fix the yaml code of aligning tabs to the center in Kiosk Mode Complements @elchininet (#439)