Ways of Importing the Dependencies

Sections Including Style Sheets and Importing html/javascript are describing ways to include style sheets and import HTML/JavaScript.

Every annotation @StyleSheet, @JavaScript and @HtmlImport has a loadMode parameter which is LoadMode.EAGER by default, but can be changed to any other possible value.

The same can be done programmatically via the overloaded methods of the Page class:

  • addStyleSheet(String url, LoadMode loadMode)

  • addHtmlImport(String url, LoadMode loadMode)

  • addJavaScript(String url, LoadMode loadMode)

Currently, Flow allows the following ways of importing the dependencies:

  • LoadMode.EAGER

Used for all dependencies by default. If you don’t know which mode to use to load the dependency, most probably this will be the most suitable.

This mode guarantees that every eager dependency for the corresponding component is loaded as soon as possible and before the page is fully initialized by the framework.

  • LoadMode.INLINE

This mode has the same guarantees as eager does, but instead of adding urls to dependencies, this mode tries to fetch the dependencies and inline those in the body of the corresponding web page. This eliminates the roundtrip needed to get the dependency. If it’s impossible to fetch the contents to be inlined, an exception is thrown and the loading is stopped.

Note

Please pay attention to urls that are used in inlined dependencies: those would not be changed and, most probably, they will be incorrect after inlining.

  • LoadMode.LAZY

This mode is suitable when you need to load the dependency, but you don’t care when. Dependencies loaded with this mode, are loaded in background, after all eager and inline dependencies are loaded.

Note

It is guaranteed, that all eager and inline dependencies are loaded before any of the lazy dependencies. For the dependencies with the same load mode, the order is guaranteed too: each eager dependency is applied in the order they were added to the component, same is true for inline and lazy dependencies.

But no guarantees are made on the order of dependencies between groups: for instance, if your component has both lazy and inline dependencies, both groups of dependencies will be loaded simultaneously.

An example

Let’s assume you have some additional functionality for your component which is optional and is not required for your application. For instance it can be a JavaScript which adds some animation to the component: /js/animation.js. This animation may be applied at any time later on for the component so that we can postpone its loading. Then the component can be declared as:

@Tag("div")
@HtmlImport("/html/layout.html") // same as @HtmlImport("/html/layout.html", loadMode = LoadMode.EAGER)
@StyleSheet(value = "/css/big_style_file.css", loadMode = LoadMode.INLINE)
@JavaScript(value = "/js/animation.js", loadMode = LoadMode.LAZY)
public class MainLayout extends Component {
    // implementation omitted
}

In this example the /html/layout.html will be loaded and injected before the client side structure is created for the MainLayout component regardless of availability of the /js/animation.js script.

  public MainLayout() {
      UI.getCurrent().getPage().addHtmlImport("/html/layout.html", LoadMode.EAGER);
      UI.getCurrent().getPage().addStyleSheet("/css/big_style_file.css", LoadMode.INLINE);
      UI.getCurrent().getPage().addJavaScript("/js/animation.js", LoadMode.LAZY);
  }
}
Note
See corresponding tutorials Including Style Sheets and Importing html/javascript about static resource paths and URLs.