Skip to content

Mention ability to define several sitemaps in a file #2714

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lolodomo wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Mention ability to define several sitemaps in a file #2714

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
71342f1
Mention ability to define several sitemaps in a file
lolodomo May 5, 2026
01baffd
Update sentence about number of sitemap definitions
lolodomo May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions ui/sitemaps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ This page is structured as follows:

[[toc]]

Sitemaps are text files with the `.sitemap` extension, and are stored in the `$OPENHAB_CONF/sitemaps` directory.
Sitemaps are text files with the `.sitemap` or `.sitemaps` extension, and are stored in the `$OPENHAB_CONF/sitemaps` directory.
They can contain one or several sitemap definitions.
Copy link
Copy Markdown
Contributor

@dilyanpalauzov dilyanpalauzov May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this sentence They can contain one or several sitemap definitions. is not necessary. .items files can also contain zero or more items, and this flexibility is nowhere stated.

Copy link
Copy Markdown
Contributor

@dilyanpalauzov dilyanpalauzov May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strictly speaking the sentence is also not correct. In openHAB 5.1.4 when I create an empty .sitemap file the system logs DSL model 'a.sitemap' is either empty or cannot be parsed correctly! With openHAB 5.2.0 build 5369 there is no such warning, so apparetly the .sitemap files can also contain zero or more sitemap definitions.

Copy link
Copy Markdown
Contributor

@mherwege mherwege May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It used to be one and exactly one. We changed it to allow any number of sitemaps. Like you can have an empty .items file, you can now also have an empty .sitemap(s) file. It doesn’t make much sense but it is possible.
I think it is good to be explicit for sitemaps that it can be multiple. It was always 1 single one since OH 1.0, so being explicit about it to make the point is worth it.

Copy link
Copy Markdown
Contributor Author

@lolodomo lolodomo May 12, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will adjust the sentence as it is true that it can now contain 0 sitemap.
Similar to .items and .things and .rules files.

Copy link
Copy Markdown
Contributor

@dilyanpalauzov dilyanpalauzov May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text was underspecified. Like it was not mentioned that .persistence files must contain strategy{} even if contains no definitions. And likewise for DSL Rules it was not stated, that global variables cannot use previously defined global variables. DSL Scripts have not documented, that from Xbase “Collection literals” could not be used in openHAB, but now there is no point to writing explicitly, that collection literals can be used.

These restrictions were not documented, so it is strange to write now down, that the restrictions do not exist. I just see no need to spell explicitly that a restriction does not exist, if the assumption is, that the restriction (arbitrary number of sitemap defintions in a file) does not exist.

Users, which have one sitemap definition per file, do not have to change anything, or to worry.

Copy link
Copy Markdown
Contributor

@dilyanpalauzov dilyanpalauzov May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Irrespective of this change, the release notes for 5.2. could state, that .sitemap files can contain zero or more sitemap definitions.

Sitemaps follow the syntax described in this article.

For easy editing of sitemap definition files, we suggest to use one of the [openHAB supporting editors]({{base}}/configuration/editors.html).
Expand Down Expand Up @@ -111,13 +112,13 @@ The `sitemap` element is **mandatory** in a Sitemap definition.
This element shall be the first line in the sitemap file, and the following code block comprises the entire Sitemap definition.

```java
sitemap <sitemapname> label="<title of the main screen>" {
sitemap <sitemapname> [label="<title of the main screen>"] {
[all sitemap elements]
}
```

- `sitemapname` shall always be equal to the Sitemaps file name, e.g. the `sitemapname` in a sitemap file named `demo.sitemap` must be "demo"
- `label` is free text and will be shown as the title of the main screen.
- `sitemapname` is the identifier of the Sitemap definition.
Comment thread
lolodomo marked this conversation as resolved.
- `label` is an optional free text and will be shown as the title of the main screen.
Comment thread
lolodomo marked this conversation as resolved.

(Note that the element `sitemap` is written with a lower case "s".)

Expand Down