Using Additional Assets
Most UI5 Web Components packages offer additional assets. This section explains what these are and how to use them.
What Are Additional Assets​
These are themes, text translations, locale data etc. that are not shipped as part of the components/icons themselves, but can be loaded separately, if needed.
These assets are important for accessibility and globalization.
Importing Additional Assets​
Import the dist/Assets.js
file of the respective NPM package:
import "@ui5/<PACKAGE-NAME>/dist/Assets.js
import "@ui5/<PACKAGE-NAME>/dist/Assets-fetch.js
** Note: read "Techcnocal aspects" below on how to choose which one to use**
*
Only listed for completeness, included automatically by other packages.
For example:
import "@ui5/webcomponents/dist/Assets.js";
and use:
<ui5-date-picker></ui5-date-picker>
with another language and another theme:
import { setLanguage } from "@ui5/webcomponents-base/dist/config/Language.js";
import { setTheme } from "@ui5/webcomponents-base/dist/config/Theme.js";
setLanguage("es");
setTheme("sap_fiori_3_hcb");
The ui5-date-picker
component will have all translatable texts in Spanish, and the Spanish format settings (e.g. date format) will be used, and will be rendered with the sap_fiori_3_hcb
accessibility theme instead of the default theme.
Technical Aspects​
Additional assets are .json
files with the respective data.
There are two ways to reference them.
Assets.js​
When you import the dist/Assets.js
file of a given package, assets are only registered, but not yet fetched. When they are needed, they are loaded on the fly with dymamic imports, and then used. This only works with bundlers which copy the JSON file as a JS file and rewrite the import URL to the correct location.
One drawback with this is that it doesn't work with CDN usage when the JSON files are hosted directly as JSON - the import expects a JS file and the browser gets a JSON content-type back with leads to an error.
Use this approach only with a bundler.
Assets-fetch.js​
When you import the dist/Assets-fetch.js
file of a given package, assets are only registered, but not yet fetched. When they are needed, they are loaded on the fly with fetch, and then used.
The issue is how to get the correct URL for the fetch to work and this is solved by using import.meta.url
to resolve a relative path from a module to a JSON file
The approach can be used with a bundler and for CDN usage.