Sitemap Future Considerations

Sitemaps. I still find that even in OH 3 they are useful. I hardly use the Main UI since I use OH via Apple Home or the iOS App. It’s nice that Main UI has some good customization options now, getting better over time - but I still find myself using Sitemaps especially remotely and on a small screen. Framework 7 performs well on my XS but it doesn’t match the performance and consistency of the native UI and people have to know a bit about framework 7 and CSS/Web Design to design UI at the moment.

It would be nice to overhaul the sitemap into a version 2 or “Next Generation”. Adding new functionality like, for example:

  • Improve colouring to support straight HEX colours instead of colour names and depends on dark/light mode for a device.
  • Adding new “widgets” like text input or buttons (ie, buttons that aren’t selected once tapped – non-state buttons like a switch button you get on iOS when you have a single item in the mapping attribute – or a whole row of buttons – no label – like media playback controls)
  • Adding Swiper Slider containers or potentially support widgets that can be placed horizontally, supporting scroll when they extend past the device edge.
  • Bluetooth beacon support, whether its a widget container or a widget itself. Allows you to setup an area for context sensitive item. Offering to lock front door or control garage door when you are next to them in the UI.
  • Icons improvements, so that you can use different icons depending on device and light/dark modes.
  • Implement the Apache ECharts or some form of it for the charting widget instead of the legacy charting option. I still use Grafana for charting, but it would be nice for others to be able to use the Main UI charting in sitemaps.
  • Be able to hide and show widgets based on more variables - like if on local connection or myopenhab.

A new Sitemap format could be a good consideration, whether it follows the same format or moves to something like yaml. The current sitemap system is used by at least 4 different openhab apps all with different developers and resources so this would be more of a “openHAB 4” or later kind of thing since there would a bit of work involved and not really on the priority list for many. Maybe this is a redundant suggestion now with Main UI.


Just a personal information to support Cossey.
My personal interaction with Openhab 3 Enviroment is approximativelly

80% Sitemap via Smartphone or Web Browser
15% Voice via Smart Speackers (aka Alexa)
5% Main UI (Great to visualize immediately an information you need but sometimes heavy to interact with)

so, do not discontinue sitemaps in future releases for me is a main topic!


Similar situation in my house:

80% via Alexa,
19% via sitemap,
1% main ui.

I love sitemaps and their simplicity and hope that they will be supported in the future.

@Muplex, @xxthunder, I don’t think anyone is thinking about sitemaps going away any time in the foreseeable future.

However, there also isn’t a lot of work being done on Sitemaps by any of the current set of maintainers. Unless @Cossey or someone else is volunteering to start work on these additions I’m afraid nothing will come of them. The current maintainers are mostly focused on MainUI.


As Rich said, there is not a lot of work done at the moment on this, which is understandable. Happy to put some time into this, might be good to start with a discussion about the specification and use cases. At the very least, I would be able to do a “Basic UI” implementation, and a Windows Desktop app implementation, though unfortunately I have no experience writing Android and iOS apps.

The question is whether this should be a completely new sitemap specification or whether or not we should look at extending existing specification. At first I was thinking about a new specification but to be honest if we extend the existing spec, improvements could be made slowly over time which would make it more appealing for maintainers of the various projects to implement.

Some of these improvements could happen server side too - ie - the icons based on platform or light/dark mode - there’ll only be minimal changes to the API url fetching.

As it was decided since OH3 to have a unique UI, I don’t think a new sitemap specification would be welcome as it would mean requirement for new UIs.
The reasonable option is to enhance the current sitemap specification (without any breaking changes), hoping the new features will be implemented in each existing UI, that is Basic UI, iOS app, Android app, …

1 Like

Thanks @Lolodomo I agree with enhancing the current specification.

I haven’t had a chance to look at the sitemap code just yet, but I notice the Sitemap API endpoint /sitemaps/{sitemapname} has a type parameter. I wonder what this is used for?

There could be parameters passed to the API from the apps for Platform, Theme, Type and Connection. This way more things can be done server side before the sitemap JSON is sent to the app/consuming service. Hopefully it would be trivial for Android/iOS/Windows store apps to modify their URL parameters to add these extra parameters, even if the sitemap system doesn’t act on this information yet.

Different icons or widgets could be displayed based on the OS or theme, different urls for the image link (think grafana and its theme=dark parameter) as well as different icons (better contrasting icons depending on dark and light backgrounds). Having the ability to know if you are connecting via cloud could help hide widgets like the video (which don’t work over cloud connection) or hide/show specific widgets when viewing your instance remotely.

Some of the above might be redundant if you are able to specify a sitemap type/category for each connection - that way for example, sitemaps could show basic widgets for my partner and kids on their devices, and when I specify a type of advanced for my devices, it will return an “all of the things” widgets and debug/maintenance sitemaps (which they don’t need to see).

I agree with @Lolodomo, I doubt a wholly new specification would be welcome. It would be too much all at once and it would break everything related to sitemaps.

I would recommend taking it one step at a time to carefully add new features little by little. Some of the things mentioned, like the stuff having to do with icons, is going to have impacts on core as well and might be quite a bit more involved than you might think right now.

I’m not sure this one has anything to do with BasicUI at all. This is going to be strictly something implemented by the phone apps. For all intents and purposes, BasicUI is a web page, nothing more.

This might not be as unachievable as one might first think. A sitemap can be created through MainUI which then gets stored as JSON in the JSONDB. Whether the sitemap is defined via the UI or from .sitemap files, the REST API returns the sitemap as JSON. So I’m not sure it would be all that disruptive over all to move to some sort of YAML format for defining the sitemap as an alternative (not necessarily replacement). But that almost certainly would be more involved than augmenting the current syntax.

Also don’t forget, since MainUI can create sitemaps, any additions/changes to the sitemap syntax will have impacts there too.

1 Like

As much as I love the OH3 main UI, I also still use sitemaps extensively in the mobile app.
There is support for creating sitemaps in the main UI, but there ware features missing that were supported with sitemap files. I just submitted 2 PR’s (#1487 and #3075) to make the support in the UI feature complete.

This does not add any extra functionality. I also feel it is getting quite cumbersome to do so consistently in all places where it nees to be configured (core and UI, parsers in both XText and javascript nearly…) and all UI’s. I don’t have the knowledge to do it consistently everywhere.

Looks like it is not used except in a log entry. This log mentions “media type”. No idea what was the original idea when defining this query parameter.

I wonder if it was to determinate the connecting application/device type? Will have to follow up with whoever wrote that part to see.

This topic was automatically closed 41 days after the last reply. New replies are no longer allowed.