How to Open an .htm Help Page within War file in Vaadin 23

I’m migrating an application from PrimeFaces to Vaadin 23. I’m using DrExplain help system to generate context sensitive help, and I’ve not had much luck finding anything on how to open and display an .htm file within the war file of the application. Each page has a “page help” button which when clicked should open the relevant .htm file. There’s also a “Main Help” button which should pull up the application’s main help page. The code below shows a navigation to a Vaadin view page with the route named “notimplemented”.

Can you tell me what should go in place of this line, to open a help screen called “mainhelp.htm” on a separate browser tab?

    this.btnMainHelp = new Button();
    btnMainHelp.addClickListener(e -> {
        btnMainHelp.getUI().ifPresent(ui -> {

It depends on how and where you’re showing the HTML content. Do you want to show the help pages within your Vaadin application, or are you navigating to a separate help site?

The htm files will exist within our application. I can place them into our “src/main/java/resources” folder, “src/main/java/resources/META-INF/resources” folder, or wherever they need to be so my code can access them as an internal page.

Yes, but are you showing them inside your Vaadin UI or as separate HTML pages?

I want to open these help files as separate htm pages, not as part of a Vaadin screen. Our legacy application opens the help screens in a separate browser window, and each screen contains relative links to other help screens, and my team would like the help screens under Vaadin to behave the same way.

First of all, you need to put the files in the right folder considering the packaging. Check Loading Resources | Advanced Topics | Vaadin Docs for the right place. For HTML files, you’re looking for the “Static files such as images, icons (including the favicon) and documents, directly requested from the browser” section.

Second of all, instead of navigating you open the wanted resource with its URL. For example, if your HTML file “page1.html” is under the subdirectory “html”:

        Button button = new Button("Click me",
                event -> UI.getCurrent().getPage().open("/html/page1.html", "_blank"));

The second parameter “_blank” is the same as the target attribute in a link, see: <a>: The Anchor element - HTML: HyperText Markup Language | MDN

In fact, using Anchor instead of open is a better way to go, as it’s more understandable for screen reader users:

        Anchor anchor = new Anchor("/html/page1.html", "Page 1", AnchorTarget.BLANK);

I’ve just given this a try, and after placing a very simple .htm file into “[project]/src/main/resources/html”, and coding both the button 's click event and the anchor as you’ve instructed, whereas I can view the file in my browser by double-clicking it from Explorer, in my Vaadin application I get the following: “Could not navigate to ‘html/simple.htm’”. I’m also getting this message when I rename the file extension to “html”. Can you advise?

You didn’t put your file in the right location.

In addition to Olli’s comment, you also need to set the router-ignore attribute on the anchor, to prevent Vaadin router from intercepting the navigation.

anchor.getElement().setAttribute("router-ignore", true);

At least in my sample project (GitHub - OlliTietavainenVaadin/my-webapp) router-ignore is not needed; maybe because it’s serving it with StaticFileHandler (like a static image) and not a dynamic service call that returns HTML.

One additional note: if there’s a security configuration, it needs to have the path to the HTML document(s) set to allowed.


Gentlemen, thank you both. My takeaway is that any “htm” or “html” file need to be placed into "[project]\src\main\webapp\html" pathfor the .open() call to find them. After placing my simple.htm file into this path, my Vaadin app successfully opened it, from both the toolbar button, and the anchor, without any further modification. Thank you again.