Code documentation comments were not updated

Also closes #250.

config.schema.json

@@ -47,6 +47,12 @@
             }
           },
           "additionalProperties": false
+        },
+        "enabled": {
+          "$ref": "#/$defs/enabled"
+        },
+        "exit": {
+          "$ref": "#/$defs/exit"
         }
       },
       "required": ["entity", "name", "type"],
@@ -75,6 +81,9 @@
               "deprecated": true,
               "title": "Schema change:",
               "description": "Use 'info' or 'tap' instead."
+            },
+            "enabled": {
+              "$ref": "#/$defs/enabled"
             }
           },
           "required": ["name", "content", "type"],
@@ -101,6 +110,12 @@
             },
             "tap_action": {
               "$ref": "#/$defs/tap_action"
+            },
+            "enabled": {
+              "$ref": "#/$defs/enabled"
+            },
+            "exit": {
+              "$ref": "#/$defs/exit"
             }
           },
           "required": ["name", "content", "type", "tap_action"],
@@ -120,6 +135,9 @@
         "type": {
           "$ref": "#/$defs/type",
           "const": "info"
+        },
+        "enabled": {
+          "$ref": "#/$defs/enabled"
         }
       },
       "required": ["name", "content", "type"],
@@ -149,6 +167,12 @@
         },
         "tap_action": {
           "$ref": "#/$defs/tap_action"
+        },
+        "enabled": {
+          "$ref": "#/$defs/enabled"
+        },
+        "exit": {
+          "$ref": "#/$defs/exit"
         }
       },
       "required": ["name", "type"],
@@ -181,6 +205,9 @@
         },
         "items": {
           "$ref": "#/$defs/items"
+        },
+        "enabled": {
+          "$ref": "#/$defs/enabled"
         }
       },
       "required": ["name", "title", "type", "items"],
@@ -293,6 +320,18 @@
           "required": ["type"]
         }
       ]
+    },
+    "enabled": {
+      "type": "boolean",
+      "default": true,
+      "title": "Enable the menu item",
+      "description": "Typically used to temporarily disable a menu item, e.g. for seasonal variations. Enabled (true) by default."
+    },
+    "exit": {
+      "type": "boolean",
+      "default": false,
+      "title": "Exit on selection",
+      "description": "Choose to exit the application after this item has been selected. Disabled (false) by default. N.B. Only actionable menu items can have this field added."
     }
   }
 }

examples/Actions.md

@@ -76,3 +76,35 @@ Note that for notify events, you _must_ not supply an `entity_id` or the API cal
 > Be careful with the value of the `service` field.
 
 Note that the `service` field will need to be a locally custom `script.<something>` as soon as any `data` fields are populated and not something more generic like `script.turn_on`. If the `service` field is wrong, the application will fail with a [`Communications.INVALID_HTTP_BODY_IN_NETWORK_RESPONSE`](https://developer.garmin.com/connect-iq/api-docs/Toybox/Communications.html) error in the response from your Home Assistant and show the error message as _"No JSON returned from HTTP request"_ on your device. In the [web-based editor](https://house-of-abbey.github.io/GarminHomeAssistant/web/) you can use the standard developer tools to observe an `HTTP 400` error which the application does not see. Here we are limited by the [Garmin Connect IQ](https://developer.garmin.com/connect-iq/overview/) software development kit (SDK). We do not have enough information at the point of execution in the application to determine the cause of the error. Nor is there an immediately obvious way of identifying this issue using the JSON schema checks.
+
+## Exit on Tap
+
+You can choose individual items that will quit after they have completed their action.
+
+```json
+{
+  "entity": "automation.turn_off_stuff",
+  "name": "Turn off Stuff",
+  "type": "tap",
+  "tap_action": {
+    "service": "automation.trigger"
+  },
+  "exit": true
+}
+```
+
+## Disable Menu Item
+
+If you would like to temporarily disable an item in your menu, e.g. for seasonal reasons like not needing to turn on the heating in summer, then rather than swapping menu definition files or deleting a section of the menu you can mark the item as 'disabled'. This field applies to all menu items.
+
+```json
+{
+  "entity": "automation.turn_off_stuff",
+  "name": "Turn off Stuff",
+  "type": "tap",
+  "tap_action": {
+    "service": "automation.trigger"
+  },
+  "enabled": false
+}
+```

examples/Switches.md

@@ -109,3 +109,29 @@ Then you can use the following in your config:
   "type": "toggle"
 }
 ```
+
+## Exit On Toggle
+
+You can choose individual items that will quit after they have completed their action.
+
+```json
+{
+  "entity": "light.hall_light",
+  "name": "Hall Light & Quit",
+  "type": "toggle",
+  "exit": true
+}
+```
+
+## Disable Menu Item
+
+If you would like to temporarily disable an item in your menu, e.g. for seasonal reasons like not needing to turn on Christmas tree lights outside the festive season, then rather than swapping menu definition files or deleting a section of the menu you can mark the item as 'disabled'. This field applies to all menu items.
+
+```json
+{
+  "entity": "light.chrissmas_tree",
+  "name": "Christmas Lights",
+  "type": "toggle",
+  "enabled": false
+}
+```

examples/Templates.md

@@ -218,6 +218,19 @@ An example of a dimmer light with 4 brightness settings 0..3. Here our light wor
 }
 ```
 
+## Disable Menu Item
+
+If you would like to temporarily disable an item in your menu, then rather than swapping menu definition files or deleting a section of the menu you can mark the item as 'disabled'. This field applies to all menu items.
+
+```json
+{
+  "name": "Phone",
+  "type": "info",
+  "content": "{{ ... }}",
+  "enabled": false
+}
+```
+
 ## Warnings
 
 Just remember, on older smaller memory devices **you have the ability to crash the application by creating an excessive menu definition**. Templates can require significant definition for highly customised text. Don't be silly.

source/HomeAssistantMenuItemFactory.mc

@@ -70,6 +70,7 @@ class HomeAssistantMenuItemFactory {
     //! @param label     Menu item label.
     //! @param entity_id Home Assistant Entity ID (optional)
     //! @param template  Template for Home Assistant to render (optional)
+    //! @param exit      Should the service call complete and then exit?
     //! @param confirm   Should this menu item selection be confirmed?
     //! @param pin       Should this menu item selection request the security PIN?
     //
@@ -77,15 +78,17 @@ class HomeAssistantMenuItemFactory {
         label     as Lang.String or Lang.Symbol,
         entity_id as Lang.String or Null,
         template  as Lang.String or Null,
+        exit      as Lang.Boolean,
         confirm   as Lang.Boolean,
         pin       as Lang.Boolean
     ) as WatchUi.MenuItem {
         return new HomeAssistantToggleMenuItem(
             label,
             template,
+            { "entity_id" => entity_id },
+            exit,
             confirm,
             pin,
-            { "entity_id" => entity_id },
             mMenuItemOptions
         );
     }
@@ -96,18 +99,20 @@ class HomeAssistantMenuItemFactory {
     //! @param entity_id Home Assistant Entity ID (optional)
     //! @param template  Template for Home Assistant to render (optional)
     //! @param service   Template for Home Assistant to render (optional)
+    //! @param data      Sourced from the menu JSON, this is the `data` field from the `tap_action` field.
+    //! @param exit      Should the service call complete and then exit?
     //! @param confirm   Should this menu item selection be confirmed?
     //! @param pin       Should this menu item selection request the security PIN?
-    //! @param data      Sourced from the menu JSON, this is the `data` field from the `tap_action` field.
     //
     function tap(
-        label     as Lang.String or Lang.Symbol,
-        entity_id as Lang.String or Null,
-        template  as Lang.String or Null,
-        service   as Lang.String or Null,
+        label     as Lang.String     or Lang.Symbol,
+        entity_id as Lang.String     or Null,
+        template  as Lang.String     or Null,
+        service   as Lang.String     or Null,
+        data      as Lang.Dictionary or Null,
+        exit      as Lang.Boolean,
         confirm   as Lang.Boolean,
-        pin       as Lang.Boolean,
-        data      as Lang.Dictionary or Null
+        pin       as Lang.Boolean
     ) as WatchUi.MenuItem {
         if (entity_id != null) {
             if (data == null) {
@@ -121,9 +126,10 @@ class HomeAssistantMenuItemFactory {
                 label,
                 template,
                 service,
+                data,
+                exit,
                 confirm,
                 pin,
-                data,
                 mTapTypeIcon,
                 mMenuItemOptions,
                 mHomeAssistantService
@@ -133,9 +139,10 @@ class HomeAssistantMenuItemFactory {
                 label,
                 template,
                 service,
+                data,
+                exit,
                 confirm,
                 pin,
-                data,
                 mInfoTypeIcon,
                 mMenuItemOptions,
                 mHomeAssistantService

source/HomeAssistantService.mc

@@ -46,7 +46,13 @@ class HomeAssistantService {
         data         as Null or Lang.Dictionary or Lang.String,
         context      as Lang.Object
     ) as Void {
-        var entity_id = context as Lang.String or Null;
+        var c = context as Lang.Dictionary;
+        var entity_id;
+        var exit = false;
+        if (c != null) {
+            entity_id = c.get(:entity_id) as Lang.String;
+            exit      = c.get(:exit)      as Lang.Boolean;
+        }
         // System.println("HomeAssistantService onReturnCall() Response Code: " + responseCode);
         // System.println("HomeAssistantService onReturnCall() Response Data: " + data);
 
@@ -102,6 +108,9 @@ class HomeAssistantService {
                         :bgcolor => Graphics.COLOR_BLACK
                     }).pushView(WatchUi.SLIDE_IMMEDIATE);
                 }
+                if (exit) {
+                    System.exit();
+                }
                 break;
 
             default:
@@ -117,7 +126,8 @@ class HomeAssistantService {
     //
     function call(
         service as Lang.String,
-        data    as Lang.Dictionary or Null
+        data    as Lang.Dictionary or Null,
+        exit    as Lang.Boolean
     ) as Void {
         if (! System.getDeviceSettings().phoneConnected) {
             // System.println("HomeAssistantService call(): No Phone connection, skipping API call.");
@@ -149,7 +159,10 @@ class HomeAssistantService {
                         "Authorization" => "Bearer " + Settings.getApiKey()
                     },
                     :responseType => Communications.HTTP_RESPONSE_CONTENT_TYPE_JSON,
-                    :context      => entity_id
+                    :context      => {
+                        :entity_id => entity_id,
+                        :exit      => exit
+                    }
                 },
                 method(:onReturnCall)
             );

source/HomeAssistantTapMenuItem.mc

@@ -23,6 +23,7 @@ class HomeAssistantTapMenuItem extends HomeAssistantMenuItem {
     private var mHomeAssistantService as HomeAssistantService;
     private var mService              as Lang.String or Null;
     private var mConfirm              as Lang.Boolean;
+    private var mExit                 as Lang.Boolean;
     private var mPin                  as Lang.Boolean;
     private var mData                 as Lang.Dictionary or Null;
 
@@ -31,9 +32,10 @@ class HomeAssistantTapMenuItem extends HomeAssistantMenuItem {
     //! @param label     Menu item label.
     //! @param template  Menu item template.
     //! @param service   Menu item service.
+    //! @param data      Data to supply to the service call.
+    //! @param exit      Should the service call complete and then exit?
     //! @param confirm   Should the service call be confirmed to avoid accidental invocation?
     //! @param pin       Should the service call be protected with a PIN for some low level of security?
-    //! @param data      Data to supply to the service call.
     //! @param icon      Icon to use for the menu item.
     //! @param options   Menu item options to be passed on.
     //! @param haService Shared Home Assistant service object that will perform the required call. Only
@@ -43,9 +45,10 @@ class HomeAssistantTapMenuItem extends HomeAssistantMenuItem {
         label     as Lang.String or Lang.Symbol,
         template  as Lang.String,
         service   as Lang.String or Null,
+        data      as Lang.Dictionary or Null,
+        exit      as Lang.Boolean,
         confirm   as Lang.Boolean,
         pin       as Lang.Boolean,
-        data      as Lang.Dictionary or Null,
         icon      as Graphics.BitmapType or WatchUi.Drawable,
         options   as {
             :alignment as WatchUi.MenuItem.Alignment,
@@ -67,9 +70,10 @@ class HomeAssistantTapMenuItem extends HomeAssistantMenuItem {
 
         mHomeAssistantService = haService;
         mService              = service;
+        mData                 = data;
+        mExit                 = exit;
         mConfirm              = confirm;
         mPin                  = pin;
-        mData                 = data;
     }
 
     //! Call a Home Assistant service only after checks have been done for confirmation or PIN entry.
@@ -103,7 +107,7 @@ class HomeAssistantTapMenuItem extends HomeAssistantMenuItem {
     //
     function onConfirm(b as Lang.Boolean) as Void {
         if (mService != null) {
-            mHomeAssistantService.call(mService, mData);
+            mHomeAssistantService.call(mService, mData, mExit);
         }
     }
 

source/HomeAssistantToggleMenuItem.mc

@@ -22,27 +22,30 @@ using Toybox.Timer;
 //! Light or switch toggle menu button that calls the API to maintain the up to date state.
 //
 class HomeAssistantToggleMenuItem extends WatchUi.ToggleMenuItem {
-    private var mConfirm    as Lang.Boolean;
-    private var mPin        as Lang.Boolean;
     private var mData       as Lang.Dictionary;
     private var mTemplate   as Lang.String;
+    private var mExit       as Lang.Boolean;
+    private var mConfirm    as Lang.Boolean;
+    private var mPin        as Lang.Boolean;
     private var mHasVibrate as Lang.Boolean = false;
 
     //! Class Constructor
     //!
     //! @param label    Menu item label.
     //! @param template Menu item template.
+    //! @param data     Data to supply to the service call.
+    //! @param exit     Should the service call complete and then exit?
     //! @param confirm  Should the service call be confirmed to avoid accidental invocation?
     //! @param pin      Should the service call be protected with a PIN for some low level of security?
-    //! @param data     Data to supply to the service call.
     //! @param options  Menu item options to be passed on.
     //
     function initialize(
         label    as Lang.String or Lang.Symbol,
         template as Lang.String,
+        data     as Lang.Dictionary or Null,
+        exit     as Lang.Boolean,
         confirm  as Lang.Boolean,
         pin      as Lang.Boolean,
-        data     as Lang.Dictionary or Null,
         options  as {
             :alignment as WatchUi.MenuItem.Alignment,
             :icon      as Graphics.BitmapType or WatchUi.Drawable or Lang.Symbol
@@ -58,10 +61,11 @@ class HomeAssistantToggleMenuItem extends WatchUi.ToggleMenuItem {
         if (Attention has :vibrate) {
             mHasVibrate = true;
         }
-        mConfirm  = confirm;
-        mPin      = pin;
         mData     = data;
         mTemplate = template;
+        mExit     = exit;
+        mConfirm  = confirm;
+        mPin      = pin;
     }
 
     //! Set the state of a toggle menu item.
@@ -212,6 +216,9 @@ class HomeAssistantToggleMenuItem extends WatchUi.ToggleMenuItem {
                 ErrorView.show(WatchUi.loadResource($.Rez.Strings.UnhandledHttpErr) as Lang.String + responseCode);
         }
         getApp().setApiStatus(status);
+        if (mExit) {
+            System.exit();
+        }
     }
 
     //! Set the state of the toggle menu item.

source/HomeAssistantView.mc

@@ -51,21 +51,42 @@ class HomeAssistantView extends WatchUi.Menu2 {
                 var confirm    = false                      as Lang.Boolean    or Null;
                 var pin        = false                      as Lang.Boolean    or Null;
                 var data       = null                       as Lang.Dictionary or Null;
+                var enabled    = true                       as Lang.Boolean    or Null;
+                var exit       = false                      as Lang.Boolean    or Null;
+                if (items[i].get("enabled") != null) {
+                    enabled = items[i].get("enabled");       // Optional
+                }
+                if (items[i].get("exit") != null) {
+                    exit = items[i].get("exit");             // Optional
+                }
                 if (tap_action != null) {
                     service = tap_action.get("service");
-                    confirm = tap_action.get("confirm"); // Optional
-                    pin     = tap_action.get("pin");     // Optional
-                    data    = tap_action.get("data");    // Optional
-                    if (confirm == null) {
-                        confirm = false;
+                    data    = tap_action.get("data");        // Optional
+                    if (tap_action.get("confirm") != null) {
+                        confirm = tap_action.get("confirm"); // Optional
+                    }
+                    if (tap_action.get("pin") != null) {
+                        pin = tap_action.get("pin");         // Optional
                     }
                 }
-                if (type != null && name != null) {
+                if (type != null && name != null && enabled) {
                     if (type.equals("toggle") && entity != null) {
-                        addItem(HomeAssistantMenuItemFactory.create().toggle(name, entity, content, confirm, pin));
-                    } else if ((type.equals("tap") && service != null) || (type.equals("info") && content != null) || (type.equals("template") && content != null)) {
+                        addItem(HomeAssistantMenuItemFactory.create().toggle(name, entity, content, exit, confirm, pin));
+                    } else if (type.equals("tap") && service != null) {
+                        addItem(HomeAssistantMenuItemFactory.create().tap(name, entity, content, service, data, exit, confirm, pin));
+                    } else if (type.equals("template") && content != null) {
                         // NB. "template" is deprecated in the schema and remains only for backward compatibility. All menu items can now use templates, so the replacement is "info".
-                        addItem(HomeAssistantMenuItemFactory.create().tap(name, entity, content, service, confirm, pin, data));
+                        // The exit option is dependent on the type of template.
+                        if (tap_action == null) {
+                            // No exit from an information only item
+                            addItem(HomeAssistantMenuItemFactory.create().tap(name, entity, content, service, data, false, confirm, pin));
+                        } else {
+                            // You may exit from template item with a 'tap_action'.
+                            addItem(HomeAssistantMenuItemFactory.create().tap(name, entity, content, service, data, exit, confirm, pin));
+                        }
+                    } else if (type.equals("info") && content != null) {
+                        // Cannot exit from a non-actionable information only menu item.
+                        addItem(HomeAssistantMenuItemFactory.create().tap(name, entity, content, service, data, false, confirm, pin));
                     } else if (type.equals("group")) {
                         addItem(HomeAssistantMenuItemFactory.create().group(items[i], content));
                     }