Documentation

examples/Actions.md

@@ -0,0 +1,52 @@
+# Actions
+
+A simple example using a scene as a `tap`` menu item.
+
+```json
+{
+  "entity": "scene.telly_watching",
+  "name": "Telly Scene",
+  "type": "tap",
+  "tap_action": {
+    "service": "scene.turn_on"
+  }
+},
+```
+
+Any menu item with an action (`tap`, `template`, or `toggle`), may have a confirmation view added. For consistency this is always done via the `tap_action` JSON object, even though for a `toggle` menu item there will only ever be a single field inside. For the `toggle` menu item, the confirmation is presented on both `on` and `off` directions. There is no option for asymmetry, i.e. only in one direction.
+
+```json
+  "tap_action": {
+    "confirm": true
+  }
+```
+
+For example:
+
+```json
+{
+  "entity": "switch.garage_door",
+  "name": "Garage Door",
+  "type": "toggle",
+  "tap_action": {
+    "confirm": true
+  }
+}
+```
+
+Note that for notify events, you _must_ not supply an `entity_id` or the API call will fail. There are other examples too.
+
+```json
+{
+  "name": "Message",
+  "type": "tap",
+  "tap_action": {
+    "service": "notify.mobile_app_on_phone",
+    "data": {
+      "title": "This is a title",
+      "message": "This is the message"
+    },
+    "confirm": true
+  }
+}
+```

examples/Templates.md

@@ -64,3 +64,71 @@ Here we generate a bar graph of the battery level. We use the following steps to
   "content": "{{ states('sensor.<device>_battery_level') }}%{% if is_state('binary_sensor.<device>_is_charging', 'on') %}+{% endif %} {{ '#' * (((states('sensor.<device>_battery_level') | int) / 100 * <width>) | int) }}{{ '_' * (<width> - (((states('sensor.<device>_battery_level') | int) / 100 * <width>) | int)) }}"
 }
 ```
+
+An example of a dimmer light with 4 brightness settings 0..3. Here our light worked on a percentage, so that had to be converted to the range 0..3.
+
+```json
+{
+  "$schema": "./schema.json",
+  "title": "Home",
+  "items": [
+    {
+      "entity": "light.green_house",
+      "name": "LEDs",
+      "type": "template",
+      "content": "{% if not (is_state('light.green_house', 'off') or is_state('light.green_house', 'unavailable')) %}{{ ((state_attr('light.green_house', 'brightness') | float) / 255 * 100) | int }}%{% else %}Off{% endif %}"
+    },
+    {
+      "entity": "light.green_house",
+      "name": "LEDs 0",
+      "type": "template",
+      "content": "{% if not (is_state('light.green_house', 'off') or is_state('light.green_house', 'unavailable')) %}{{ ((state_attr('light.green_house', 'brightness') | float) / 255 * 100) | int }}%{% else %}Off{% endif %}",
+      "tap_action": {
+        "service": "light.turn_on",
+        "data": {
+          "brightness_pct": 12
+        }
+      }
+    },
+    {
+      "entity": "light.green_house",
+      "name": "LEDs 1",
+      "type": "tap",
+      "tap_action": {
+        "service": "light.turn_on",
+        "data": {
+          "brightness_pct": 37
+        }
+      }
+    },
+    {
+      "entity": "light.green_house",
+      "name": "LEDs 2",
+      "type": "template",
+      "content": "{% if not (is_state('light.green_house', 'off') or is_state('light.green_house', 'unavailable')) %}{{ ((state_attr('light.green_house', 'brightness') | float) / 255 * 100) | int }}%{% else %}Off{% endif %}",
+      "tap_action": {
+        "service": "light.turn_on",
+        "data": {
+          "brightness_pct": 62
+        }
+      }
+    },
+    {
+      "entity": "light.green_house",
+      "name": "LEDs 3",
+      "type": "template",
+      "content": "{% if not (is_state('light.green_house', 'off') or is_state('light.green_house', 'unavailable')) %}{{ ((state_attr('light.green_house', 'brightness') | float) / 255 * 100) | int }}%{% else %}Off{% endif %}",
+      "tap_action": {
+        "service": "light.turn_on",
+        "data": {
+          "brightness_pct": 87
+        }
+      }
+    }
+  ]
+}
+```
+
+## Warnings
+
+Just remember, you have the ability to crash the application by creating an excessive menu definition. Older devices running as a widget can be limited in memory such that the JSON definition causes an "Out of Memory" error. Templates can require significant definition for highly customised text. Don't be silly.