Search code examples
sapui5ui5-tooling

UI5 parameters: data-sap-ui-xx-waitfortheme and data-sap-ui-xx-componentpreload

The UI5 HTML-bootstrapper has two parameters which I don't really understand:

  • data-sap-ui-xx-componentpreload
  • data-sap-ui-xx-waitfortheme

I've checked the official documentation and didn't get some straightforward description.

My questions:

  1. When should I use data-sap-ui-xx-componentpreload and what are its benefits?

  2. When should I use data-sap-ui-xx-waitfortheme and what are its benefits?

Solution

  • ⚠️ First things first ...

    xx- options are experimental. They may be removed in future UI5 versions or their behavior may change in an incompatible way.

    Option sap-ui-xx-componentPreload

    By default, UI5 requests the app bundle Component-preload.js automatically when creating ComponentContainer (e.g. via data-sap-ui-oninit="module:sap/ui/core/ComponentSupport").

    The bundle is generated by UI5 tooling for deployment so that users finally use the optimized version of the app. Therefore, avoid shipping the standalone app with data-sap-ui-xx-componentpreload in index.html! Otherwise, users will end up using unnecessarily the unminified, unbundled developer version of the app.

    Options in index.html (data-sap-ui-*) don't affect typical Fiori launchpad (FLP) apps as FLP uses its own HTML page.

    Using sap-ui-xx-componentPreload makes only sense for previewing, testing, or demo scenarios where there is no Node.js environment (unable to use UI5 tooling) so that 404-errors can be avoided. SAP Web IDE, for example, used to append the option sap-ui-xx-componentPreload=off in the URL so that the preview runs without the 404-error.

    Values

    • async or sync by default depending on the sap-ui-preload / sap-ui-async settings.
    • off to load Component.js instead of Component-preload.js despite having a ComponentContainer.

    Option sap-ui-xx-waitForTheme

    The xx-waitForTheme option helps to avoid FOUC (Flash Of Unstyled Content) and, in some cases, to reduce sync XHRs. The option tells the app to postpone certain tasks until the theme has been loaded and applied.

    Values (since UI5 1.63)

    • init waits for the theme → executes Core's init handler (attachInit(fn)) → renders the app.
      Use this if some controls try to access theme-dependent parameters via sap/ui/core/theming/Parameters.get synchronously (deprecated) too soon.
    • rendering (formerly true until 1.62) executes Core's init handler first → waits for the theme → initializes the rendering.

    If there is no value set, Core's init and initial rendering are executed immediately without waiting for the theme → FOUC.

    For more options and information, see Configuration Options and URL Parameters and its parent topics.