Sitemaps: support Button widgets inside buttongrids

[jimtng]

Buttongrid can now contain Button widgets which allows each button to be linked to individual item, plus each being set to different color / visibility

openhab/openhab-core#4223

Currently, the "old" button option for buttongrid is still supported too, so it's backwards compatible with oh4.1

Adding buttons to a buttongrid with positional arguments

sitemaps.build do
  sitemap "remote" do
    buttongrid item: RCButton do
      button 1, 1, "BACK", "Back", "f7:return"
      button 1, 2, "HOME", "Menu", "material:apps"
      button 1, 3, "YELLOW", "Search", "f7:search"
      button 2, 2, "UP", "Up", "f7:arrowtriangle_up"
      button 4, 2, "DOWN", "Down", "f7:arrowtriangle_down"
      button 3, 1, "LEFT", "Left", "f7:arrowtriangle_left"
      button 3, 3, "RIGHT", "Right", "f7:arrowtriangle_right"
      button 3, 2, "ENTER", "Enter", "material:adjust"
    end
  end
end

Adding buttons to a buttongrid with keyword arguments

sitemaps.build do
  sitemap "remote" do
    buttongrid item: RCButton do
      # These buttons will use the default item assigned to the buttongrid (RCButton)
      button row: 1, column: 1, click: "BACK", icon: "f7:return"
      button row: 1, column: 2, click: "HOME", icon: "material:apps"
      button row: 1, column: 3, click: "YELLOW", icon: "f7:search"
      button row: 2, column: 2, click: "UP", icon: "f7:arrowtriangle_up"
      button row: 4, column: 2, click: "DOWN", icon: "f7:arrowtriangle_down"
      button row: 3, column: 1, click: "LEFT", icon: "f7:arrowtriangle_left"
      button row: 3, column: 3, click: "RIGHT", icon: "f7:arrowtriangle_right"
      button row: 3, column: 2, click: "ENTER", icon: "material:adjust"
    end
  end
end

Mixing positional and keyword arguments

sitemaps.build do
  sitemap "remote" do
    buttongrid item: RCButton do
      button 1, 1, click: "BACK", icon: "f7:return"
      button 1, 2, click: "HOME", icon: "material:apps"
      button 1, 3, click: "YELLOW", icon: "f7:search"
      button 2, 2, click: "UP", icon: "f7:arrowtriangle_up"
      button 4, 2, click: "DOWN", icon: "f7:arrowtriangle_down"
      button 3, 1, click: "LEFT", icon: "f7:arrowtriangle_left"
      button 3, 3, click: "RIGHT", icon: "f7:arrowtriangle_right"
      button 3, 2, click: "ENTER", icon: "material:adjust"
    end
  end
end

openHAB 4.2+ supports assigning different items to buttons, along with additional features

sitemaps.build do
  sitemap "remote" do
    buttongrid item: RCButton do
      button 1, 1, click: "BACK", icon: "f7:return"
      button 1, 2, click: "HOME", icon: "material:apps"
      button 1, 3, click: "YELLOW", icon: "f7:search", icon_color: "yellow"
      button 2, 2, click: "UP", icon: "f7:arrowtriangle_up"
      button 4, 2, click: "DOWN", icon: "f7:arrowtriangle_down"
      button 3, 1, click: "LEFT", icon: "f7:arrowtriangle_left"
      button 3, 3, click: "RIGHT", icon: "f7:arrowtriangle_right"
      button 3, 2, click: "ENTER", icon: "material:adjust", icon_color: "red"

      # These buttons will use the specified item, only supported in openHAB 4.2+
      button 4, 3, click: ON, icon: "switch-on", visibility: "TVPower!=ON", item: TVPower
      button 4, 3, click: OFF, icon: "switch-off", visibility: "TVPower==ON", item: TVPower
    end
  end
end

[ccutrer]

Seems like it would be nice if you could use the 4.1 syntax in 4.2 and vice versa to make an easy transition (as long as you don't specify an item or release when on 4.1)z

[jimtng]

4.2 supports both widget and non-widget implementation, so both syntaxes are supported.

Using 4.2 syntax, without item or release, on 4.1 is doable. I'll make the changes and push.

[jimtng]

After pondering about it further, I don't think it's a good idea.

If we supported kwargs in 4.1 (without item), e.g.:

button row: 4, column: 1, click: ON, label: "ON", icon: "switch-on"

when user upgrades to 4.2, this will be created as non-widget button (the same as it was in 4.1), however, this means we can't warn / raise an error when item is missing when the user intended to create a widget button.

The check for missing item isn't currently implemented, and perhaps it should be. However, we could also explore another direction: #button with kwargs with omitted item arg could default to the item specified in the parent buttongrid, hence it is again implemented as widget. This inferencing may be implemented in core, or if not, in Ruby. I'm waiting to see how it develops in core, and I have mentioned it here

So, long story short, perhaps we should leave it as is for now. It makes a clear distinction: array args => non widget, vs kwargs => widget.

[ccutrer]

except item isn't required (openhab/openhab-core#4241) on a button. by supporting both styles of params, you could change ButtongridBuilder#initialize to not have buttons itself, just call buttons.each { |b| button *b }, and have ButtonBuilder#initialize support array style as well. Then you could add a private children(parent) method to LinkableWidgetBuilder that defaults to parent.children, but on ButtongridBuilder on 4.1, it returns parent.buttons. It really unifies things so you don't have two completely different codepaths that are not really disjoint, making it hard to reason about.

I don't think users of openHAB really care if their button is a true Button widget, or just part of the Buttongrid, since the former is a superset of the latter. I'd be more worried if say the iOS app only supported 4.1 style buttongrids, and choked on actual widgets, with no forthcoming fix. But it doesn't support button grids at all! BasicUI on the web supports both fully. And I expect the Android app, if it doesn't already, to soon support both fully.

[jimtng]

So you're saying that in 4.2, implement both array style and kwargs style as widgets, ignoring the non-widget version completely? Currently the Android app doesn't yet support button widgets though, so doing this will break android on 4.2.

[jimtng]

I've refactored it to your suggested/requested change. However, it doesn't work on android app with oh 4.2 because the app hasn't implemented button widgets.