Importing HTML and JavaScript

There are two ways to import HTML and JavaScript with a component.

By using the annotations @JavaScript and @HtmlImport

Java

  1. @Tag("div")
  2. @JavaScript("/js/script.js")
  3. @HtmlImport("/html/htmlimport.html")
  4. static class HtmlComponent extends Component implements HasText {
  5.   // implementation omitted
  6. }

Both annotations are repeatable and you can add multiple annotations for both to the component.

Another way of adding imports are the addHtmlImport(String url) and addJavaScript(String url) methods from the Page class. The functionality is the same as for the annotations.

Java

  1.   private void addDependencies() {
  2.     UI.getCurrent().getPage().addHtmlImport("/html/htmlimport.html");
  3.     UI.getCurrent().getPage().addJavaScript("/js/script.js");
  4.   }
Note

For every class that imports dependencies, import order is guaranteed for dependencies of the same type only. No guarantees are given regarding numerous classes’ dependencies’ import order, same as no guarantees are given on import order of dependencies of not the same type.

Example:

  1. @JavaScript(“1.js”)
  2. @StyleSheet(“1.css”)
  3. @HtmlImport(“1.html”)
  4. @JavaScript(“2.js”)
  5. @StyleSheet(“2.css”)
  6. @HtmlImport(“2.html”)
  7. static class OrderedDependencies extends Div {
  8. }

In this case, 1.js will be imported before 2.js, 1.css before 2.css, 1.html before 2.html, but no other guarantees can be made.

If you want to enforce an order between dependencies of a different type, you can add html import with imports in it. For example, if htmlimport4.html should be run before htmlimport4-js.js then you should import an html that has the correct load order:

  1. <link rel=”import” href=”htmlimport4.html”>
  2. <script src=”htmlimport4-js.js”></script>

You can place your static resources in any folder inside your WAR file except for /VAADIN which is reserved for framework internal use. VaadinServlet handles static resource requests if you have mapped it to /* . Otherwise, the servlet container will take care of static resource requests.

By using relative URLs you are not dependent on whether the application is deployed in the root context (e.g. [http://mysite.com/](http://mysite.com/)) or in a sub context (e.g. [http://mysite.com/myapp/](http://mysite.com/myapp/)).

Relative URLs are resolved using the page base URI, which is always set to match the servlet URL.

Tip

If you are using a servlet path for the servlet, e.g. http://mysite.com/myapp/myservlet/ then you will need to take the servlet path into account when including resources. This is needed because the base URI is http://mysite.com/myapp/myservlet/ but static resources are deployed in http://mysite.com/myapp/.

You can use the special protocol context:// with e.g. Page.addHtmlImport to ensure a URL relative to the context path but this is only supported when including resources.

When you configure an element, e.g setting the src attribute for an <img>, you cannot use the context:// protocol. Your options are then:

  • Cancel out the servlet path, e.g. ../images/logo.png.

  • Use an absolute URL, e.g. /myapp/images/logo.png

  • Deploy your static resources in a directory matching the servlet path, e.g. /myservlet/.

Tip

There is a possibility to define which dependencies are loaded first, refer to Ways of importing the dependencies for details.