SAPUI5 - Patch-Level Independent Bootstrap

pmuessig · ‎04-14-2022

Patch-Level Independent Bootstrap

We listen to your feedback! A while back we got the feedback to make the bootstrap URL more stable and in dedicated feedback rounds, we evaluated that this should apply especially to the bootstrap URLs of long-term maintenance versions. With the introduction of the removal of outdated versions, this feature becomes even more relevant! As we also want to get rid of outdated patches of long-term maintenance versions, having an “evergreen” bootstrap URL would help to keep your migration efforts as minimal as possible.

With the availability of the latest SAPUI5 cloud runtime version we are going to introduce the patch-level independent bootstrap a.k.a. evergreen version. The patch-level independent bootstrap works starting from 1.71. The benefit of the patch-level independent bootstrap is to point to a major.minor release and automatically profit from patches which happens under the hood. Your application can be kept stable and the underlying SAPUI5 runtime will be kept up to date.

📣📣📣 UPDATE 2023-03-30: the feature is now also available for OpenUI5.

How it works

To use the patch-level independent bootstrap for your standalone SAPUI5/OpenUI5 application, first select a long-term maintenance version from the version overview of SAPUI5 or OpenUI5. Then, in your bootstrap script tag you refer the major.minor version instead of major.minor.patch. This feature requires to control the bootstrap script tag and therefore doesn’t work in the context of the SAP Fiori launchpad or SAP Cloud Portal service (both have individual mechanism to manage the UI5 version). The following code snippet illustrates the usage of the patch-level independent bootstrap:

<script id="sap-ui-bootstrap"

    type="text/javascript"

    src="https://ui5.sap.com/1.96/resources/sap-ui-core.js"

    data-sap-ui-theme="sap_fiori_3"

    data-sap-ui-async="true"

    data-sap-ui-onInit="module:sap/ui/core/ComponentSupport"

    data-sap-ui-libs="sap.m"></script>

The corresponding bootstrap URL for OpenUI5 above would be: https://sdk.openui5.org/1.96/resources/sap-ui-core.js

The snippet above is using the sap/ui/core/ComponentSupport to bootstrap the Component. This requires to declare the Component via a <div> tag in the <body> of the HTML page:

  <div data-sap-ui-component

    data-name="my.app"

    data-settings='{ "id": "myRootComponent" }'

  ></div>

More details can be found in the documentation: Declarative API for Initial Components.

There is one basic requirement: the bootstrap script requires to be asynchronous and therefore enable asynchronous loading for your application (by adding the attribute to your bootstrap script). This also comes with the advantage that you are going to benefit from future performance bootstrapping improvements. Keep in mind: without the bootstrap must be async, otherwise it is going to fail with an error in the console. The async flag must be set explicit to be able to switch easily between specific versions and the evergreen versions by just adopting the version segment of the bootstrap source.

Remark: When using the full asynchronous bootstrap you must use the data-sap-ui-onInit callback as described in the documentation "Standard Variant for Bootstrapping". The sap.ui.getCore() is not available directly after using the patch-level independent bootstrap URL. In this case the best option is to use the Declarative API for Initial Components and let the framework start your application (root component).

Technical Flow

When using the patch-level independent bootstrap you will notice an additional request to the sap-ui-core.js file. One for the evergreen version and one for the specific version which is finally booting SAPUI5. This is mandatory because the evergreen request is somehow a cache buster request. The server responds a little script which configures SAPUI5 to load the resources from the latest patch of the corresponding version, i.e., when booting SAPUI5 1.96 as of today 1.96.8.

The evergreen request only works for dedicated bootstrap files, such as:

resources/sap-ui-core.js

resources/sap-ui-core-nojQuery.js

resources/sap-ui-integration.js

All other scripts will not be handled as evergreen request and the server will return a 404 response for them.

Bonus: Usage of Patch-Level Independent URLs for Documentation

Besides using the major.minor versions in the URL for the patch-level independent bootstrap we added some more bonus material. You can also use patch-level independent URLs for the documentation, i.e., https://ui5.sap.com/1.96/. This will redirect you to the latest version of the documentation https://ui5.sap.com/1.96.8/. The same works for OpenUI5 with the following URL: https://sdk.openui5.org/1.96/.

Related Questions

Q: The debug mode doesn't work anymore. What can I do?

TL/DR: Instead of using "sap-ui-debug=true" use "sap-ui-debug=sap/". This will ensure that all modules from the sap/* namespace will be loaded as debug resources. If you also want to load the debug resources from you namespace, you can include it as well: "sap-ui-debug=sap/,xyz/app/".

Background: The first request to the bootstrap script of UI5is a cache buster request - as explained in the technical flow above. The real bootstrap with the concrete version will be loaded afterwards. As the required script tag is created dynamically, the bootstrap file is then loaded asynchronously. The debug mode normally interrupts the load of the bootstrap script and includes the debug bootstrap script. This only works, when the bootstrap script is loaded as part of the documents head section. With using namespaces, only the modules which are required after the bootstrap and map to the defined namespace will be loaded as debug sources. This is btw also a good practice to only load the necessary debug resources from debugging performance perspective.

Wrap-up

Now, you are able to consume long-term maintenance SAPUI5 versions from the cloud by just specifying the major.minor version. This is one step ahead to reduce your maintenance for your applications and it also allow us to have more freedom deleting outdated versions from the cloud. Additionally, the asynchronous loading allows us to improve the performance of the bootstrap behind the scenes.

Thanks to all people involved in developing this idea and special thanks to the SAP Mentors providing us feedback and guiding us towards the final solution.