Sitemap DSL and YAML serialization #4945

mherwege · 2025-08-06T12:37:04Z

In OH 5.0, DSL serialization for items and things was introduced.

This PR extends this to serialize sitemap definitions into DSL and YAML. This is a basis to be able to remove the specific sitemap parser from the UI in the future, and use a REST call instead.

To make this work for DSL, I had to do a change that has a broader impact. The current sitemap syntax contains a number of unnamed lists, such as:

('labelcolor=[' (LabelColor+=ColorArray (',' LabelColor+=ColorArray)*) ']')?

These do not serialize well and a separate labelcolor=[...] entry is created for each definition. I tried getting around this by writing a custom serializer but did not succeed. I therefore modified the grammar to explicitely name these lists, like:

('labelcolor=' labelColor=ColorArrayList)?

and

ColorArrayList returns ColorArrayList:
    '[' elements+=ColorArray (',' elements+=ColorArray)* ']'
;

This does not change the syntax from a user perspective, but it does introduce an extra named level in the created Java objects. All calls to retrieve an array in the code needed to be adapted. This PR already includes the required core changes. I have the code to also adjust BasicUI and CometVisu. With this grammar change, the sitemap grammar serializes without issues.

The grammar was too big with the above change. To resolve that, I moved the variable sequence of unique properties out of the syntax and built extra validation checks to cope with this. XText is apparantly very bad at these variable sequences (using the & symbol). It also had a lot of unexpected consequences in the formatting of the result.

I now also force the use of the serializer, so sitemaps created programatically and not from a file get formatted properly. save does not always call the formatter. This had impact on the items and things serialization as well, requiring an extra parameter.

@lolodomo What do you think?

Signed-off-by: Mark Herwege <[email protected]>

mherwege · 2025-08-06T13:55:29Z

It looks like my change to the grammar made the grammar too big the the Language Server. All else looks like it is working.

Signed-off-by: Mark Herwege <[email protected]>

mherwege · 2025-08-07T10:59:17Z

The grammar being too big has been resolved. I move the variable sequence of unique properties out of the syntax and build extra validation checks to cope with this. XText is apparantly very bad at these variable sequences (using the & symbol). It also had a lot of unexpected consequences in the formatting of the result.

I now also force the use of the serializer, so sitemaps created programatically and not from a file get formatted properly. save does not always call the formatter. This had impact on the items and things serialization as well, requiring an extra parameter.

Signed-off-by: Mark Herwege <[email protected]>

mherwege · 2025-08-07T13:32:21Z

Feature verification fails when running a parallel build. It succeeds when running locally with a sequential build. I don't know how to solve that.

Signed-off-by: Mark Herwege <[email protected]>

mherwege · 2025-08-08T13:12:56Z

The last commit adds YAML serialization.

Here is an example output:

version: 1
sitemap:
  demo:
    label: Demo Sitemap
    widgets:
      - Frame:
          label: Demo Items
          widgets:
            - Text:
                item: DemoContact
                label: "Contact [MAP(en.map):%s]"
            - Text:
                item: DemoString
                label: "Message [%s]"
            - Text:
                item: DemoDateTime
                label: "Date [%1$tA, %1$td.%1$tm.%1$tY]"
            - Group:
                item: DemoSwitchGroup
                icon: icon1
      - Frame:
          label: Magic Test Items
          widgets:
            - Colorpicker:
                item: MagicColor
            - Switch:
                item: MagicOnOff
            - Slider:
                item: MagicDimmer
      - Frame:
          label: Location
          widgets:
            - Mapview:
                item: DemoLocation
                height: 10
  demo1:
    label: My home automation
    widgets:
      - Frame:
          label: Date
          widgets:
            - Text:
                item: Date
      - Frame:
          label: Demo
          widgets:
            - Switch:
                item: Lights
                icon: light
            - Text:
                item: LR_Temperature
                label: "Livingroom [%.1f °C]"
            - Group:
                item: Heating
            - Text:
                item: LR_Multimedia_Summary
                label: "Multimedia [%s]"
                icon: video
                staticIcon: true
                widgets:
                  - Selection:
                      item: LR_TV_Channel
                      mappings:
                        - cmd: 0
                          label: "off"
                        - cmd: 1
                          label: DasErste
                        - cmd: 2
                          label: BBC One
                        - cmd: 3
                          label: Cartoon Network
                  - Slider:
                      item: LR_TV_Volume
  stringtest:
    widgets:
      - Switch:
          item: licht_nachthal
          label: "This is a very long label that should make the line wrap. So let us make it even longer to get beyond 250. Argh, just not there yet. I need even more."
          mappings:
            - cmd: "ON"
              label: Aan
            - cmd: "OFF"
              label: Uit
            - cmd: "NULL"
              label: '-'
          labelColor:
            - conditions:
                - value: "ON"
              argument: yellow
            - conditions:
                - value: "OFF"
              argument: red
  uicomponents_button_test:
    label: Button Test
    widgets:
      - Buttongrid:
          widgets:
            - Button:
                item: DemoNumber
                row: 1
                column: 1
                stateless: true
                cmd: 1
            - Button:
                item: DemoNumber
                row: 1
                column: 2
                stateless: true
                cmd: 2
            - Button:
                item: DemoNumber
                row: 1
                column: 3
                stateless: true
                cmd: 3
            - Button:
                item: DemoNumber
                row: 2
                column: 1
                stateless: true
                cmd: 4
            - Button:
                item: DemoNumber
                row: 2
                column: 2
                stateless: true
                cmd: 5
            - Button:
                item: DemoNumber
                row: 2
                column: 3
                stateless: true
                cmd: 6
            - Button:
                item: DemoNumber
                row: 3
                column: 1
                stateless: true
                cmd: 7
            - Button:
                item: DemoNumber
                row: 3
                column: 2
                stateless: true
                cmd: 8
            - Button:
                item: DemoNumber
                row: 3
                column: 3
                stateless: true
                cmd: 9
            - Button:
                item: DemoNumber
                row: 4
                column: 2
                stateless: true
                cmd: 0
  uicomponents_page_bc256a2142:
    label: Icon Tests
    widgets:
      - Switch:
          item: licht_nachthal
          label: Nachthal
          icon: if:mdi:lightbulb
  uicomponents_page_fd4c4e14a6:
    label: Nesting test
    widgets:
      - Frame:
          widgets:
            - Text:
                label: Text1
            - Text:
                label: Text2
            - Buttongrid:
                label: ButtonGrid
                widgets:
                  - Button:
                      item: Alarm
                      label: Button1
                      row: 1
                      column: 1
                      cmd: "ON"
                  - Button:
                      item: Alarm
                      label: Button2
                      row: 2
                      column: 1
                      cmd: "OFF"

Copilot

Pull Request Overview

This PR extends DSL serialization capabilities from items and things to include sitemap definitions, enabling serialization to both DSL and YAML formats. This change serves as a foundation for potentially removing the specific sitemap parser from the UI and using REST calls instead.

The key changes include:

Modified sitemap grammar to use named lists instead of unnamed lists for better serialization
Updated all existing code to work with the new list wrapper objects
Added DSL and YAML file converters for sitemaps
Enhanced validation and formatting for sitemaps

Reviewed Changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
`ItemUIRegistryImplTest.java`	Updated tests to work with new list wrapper objects
`ItemUIRegistryImpl.java`	Modified to access elements through list wrapper objects
`UIComponentSitemapProvider.java`	Updated parameter types and element access patterns
`YamlSitemapFileConverter.java`	New YAML converter for sitemap serialization
`YamlWidgetDTO.java`	New DTO for YAML widget serialization
`YamlSitemapDTO.java`	New DTO for YAML sitemap serialization
`YamlRuleDTO.java`	New DTO for YAML rule serialization
`YamlMappingDTO.java`	New DTO for YAML mapping serialization
`DslSitemapFileConverter.java`	New DSL converter for sitemap serialization
`SitemapFormatter.xtend`	Enhanced formatting rules for sitemap DSL
`Sitemap.xtext`	Modified grammar to use named list containers
`SitemapValidator.xtend`	Enhanced validation with line number reporting
Various other files	Updated to work with new serializer infrastructure

Copilot · 2025-08-08T17:18:53Z

...del.sitemap/src/org/openhab/core/model/sitemap/formatting/SitemapIndentationInformation.java

@@ -0,0 +1,10 @@
+package org.openhab.core.model.sitemap.formatting;


This file is missing the standard copyright header that is present in all other files in the project.

Copilot · 2025-08-08T17:18:53Z

...org.openhab.core.ui/src/main/java/org/openhab/core/ui/internal/items/ItemUIRegistryImpl.java

        } else if (w instanceof Switch sw) {
            StateDescription stateDescr = i.getStateDescription();
-            if (sw.getMappings().isEmpty() && (stateDescr == null || stateDescr.getOptions().isEmpty())) {
+            if ((sw.getMappings() == null || sw.getMappings().getElements().isEmpty())


The null check pattern for getMappings() is repeated multiple times. Consider extracting this into a helper method like hasMappings(Switch sw) to reduce code duplication.

There is only a single call to this in the class.

Copilot · 2025-08-08T17:18:54Z

...org.openhab.core.ui/src/main/java/org/openhab/core/ui/internal/items/ItemUIRegistryImpl.java

+    private @Nullable String processColorDefinition(Widget w, @Nullable ColorArrayList colorArrayList,
+            String colorType) {
+        if (colorArrayList == null) {
+            return null;
+        }
+        List<ColorArray> colorList = colorArrayList.getElements();
        // Sanity check


The null check and getElements() pattern is repeated across multiple methods (processColorDefinition, getVisiblity, getConditionalIcon). Consider creating a utility method to safely get elements from these list wrapper objects.

Suggested change

private @Nullable String processColorDefinition(Widget w, @Nullable ColorArrayList colorArrayList,

String colorType) {

if (colorArrayList == null) {

return null;

}

List<ColorArray> colorList = colorArrayList.getElements();

// Sanity check

/**

* Utility method to safely get elements from a list wrapper object.

* Returns an empty list if the wrapper is null or contains no elements.

*/

private <T> List<T> safeGetElements(@Nullable Object wrapper) {

if (wrapper == null) {

return Collections.emptyList();

}

if (wrapper instanceof ColorArrayList) {

List<ColorArray> list = ((ColorArrayList) wrapper).getElements();

return list != null ? list : Collections.emptyList();

} else if (wrapper instanceof VisibilityRuleList) {

List<VisibilityRule> list = ((VisibilityRuleList) wrapper).getElements();

return list != null ? list : Collections.emptyList();

} else if (wrapper instanceof IconRuleList) {

List<IconRule> list = ((IconRuleList) wrapper).getElements();

return list != null ? list : Collections.emptyList();

}

return Collections.emptyList();

}

private @Nullable String processColorDefinition(Widget w, @Nullable ColorArrayList colorArrayList,

String colorType) {

List<ColorArray> colorList = safeGetElements(colorArrayList);

getElements does not return List, but EList so this suggestion does not work.

Copilot · 2025-08-08T17:18:54Z

...va/org/openhab/core/model/yaml/internal/sitemaps/fileconverter/YamlSitemapFileConverter.java

+        dto.icon = widget.getStaticIcon() != null ? widget.getStaticIcon()
+                : (widget.getIconRules() == null ? widget.getIcon() : null);
+        IconRuleList iconRuleList = widget.getIconRules();
+        if (iconRuleList != null && iconRuleList.getElements() != null && iconRuleList.getElements().size() > 0) {


Use !iconRuleList.getElements().isEmpty() instead of iconRuleList.getElements().size() > 0 for better readability and performance.

Suggested change

if (iconRuleList != null && iconRuleList.getElements() != null && iconRuleList.getElements().size() > 0) {

if (iconRuleList != null && iconRuleList.getElements() != null && !iconRuleList.getElements().isEmpty()) {

Copilot · 2025-08-08T17:18:54Z