-
Notifications
You must be signed in to change notification settings - Fork 273
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add migration guides, update docs (#977)
- Loading branch information
1 parent
eeeb414
commit bdfeb78
Showing
6 changed files
with
234 additions
and
41 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| # Assets and JSON module imports | ||
|
|
||
| UI5 Web Components aim to be feature rich and with a minimal code footprint at the same time. In order to achieve this, | ||
| most UI5 Web Components packages ship their assets as `.json` files while also providing respective public module imports for them. | ||
|
|
||
| The assets in question could be i18n texts, icons, additional themes parameters, CLDR, etc... | ||
|
|
||
| Currently our npm packages follow the scheme: | ||
|
|
||
| `@ui5/<PACKAGE_NAME>/dist/assets/*` | ||
| (for the assets themselves) | ||
|
|
||
| `@ui5/<PACKAGE_NAME>/dist/json-imports/*` | ||
| (for the modules that provide the assets) | ||
|
|
||
| <a name="packages"></a> | ||
| ## Packages | ||
|
|
||
| ### `base` package | ||
|
|
||
| Asset type | Asset path | Public Module Import | ||
| ------|------------------|--- | ||
| CLDR | `@ui5/webcomponents-base/dist/assets/cldr/*` | `@ui5/webcomponents-base/dist/json-imports/LocaleData.js` | ||
|
|
||
| Usually you don't need to import the CLDR assets from the `base` package, but rather from the package(s) containing the actual web components. | ||
|
|
||
| ### `main` package | ||
|
|
||
| Asset type | Asset path | Public Module Import | ||
| ------|------------------|--- | ||
| i18n | `@ui5/webcomponents/dist/assets/i18n/*` | `@ui5/webcomponents/dist/json-imports/i18n.js` | ||
| Additional themes | `@ui5/webcomponents/dist/assets/themes/*` | `@ui5/webcomponents/dist/json-imports/Themes.js` | ||
| CLDR | N/A | `@ui5/webcomponents/dist/json-imports/LocaleData.js` | ||
|
|
||
| The `main` package does not have any additional CLDR assets besides the CLDR assets of the `base` project. | ||
|
|
||
| ### `fiori` package | ||
|
|
||
| Asset type | Asset path | Public Module Import | ||
| ------|------------------|--- | ||
| i18n | `@ui5/webcomponents-fiori/dist/assets/i18n/*` | `@ui5/webcomponents-fiori/dist/json-imports/i18n.js` | ||
| Additional themes | `@ui5/webcomponents-fiori/dist/assets/themes/*` | `@ui5/webcomponents-fiori/dist/json-imports/Themes.js` | ||
|
|
||
| ### `icons` package | ||
|
|
||
| Asset type | Asset path | Public Module Import | ||
| ------|------------------|--- | ||
| i18n | `@ui5/webcomponents-fiori/dist/assets/i18n/*` | `@ui5/webcomponents-fiori/dist/json-imports/i18n.js` | ||
| All icons | `@ui5/webcomponents-fiori/dist/assets/icon-collections/*` | `@ui5/webcomponents-fiori/dist/json-imports/Icons.js` | ||
|
|
||
| Normally applications are expected to import only the individual icons that are going to be used, for example: | ||
|
|
||
| `import "@ui5/webcomponents-icons/dist/icons/add.js`";` | ||
|
|
||
| However, sometimes it makes sense to import all icons, hence the `@ui5/webcomponents-fiori/dist/json-imports/Icons.js` JSON import. | ||
|
|
||
| Since some icons have translatable tooltips, you might need the `i18n` JSON import as well. | ||
|
|
||
| <a name="bundling"></a> | ||
| ## Efficient asset bundling | ||
|
|
||
| You may notice that JSON imports, for example: | ||
|
|
||
| `import "@ui5/webcomponents/dist/json-imports/i18n.js"` | ||
|
|
||
| or | ||
|
|
||
| `import "@ui5/webcomponents/dist/json-imports/Themes.js"` | ||
|
|
||
| will produce warning messages in the browser's console, such as for example: | ||
| > Inefficient bundling detected: consider bundling i18n/theme proeprties imports as URLs instead of inlining them. | ||
| > See rollup-plugin-url or webpack file-loader for more information. | ||
| > Suggested pattern: "assets\/.*\.json" | ||
| What this means is that it's recommended to instruct your source code bundling software | ||
| (some of the most popular being Webpack and Rollup) not to include all the asset files or theming related files | ||
| (files that match the <code>assets\/.*\.json</code> pattern) in your applications's javascript bundle, | ||
| but rather to leave them out. At runtime, they will be fetched on demand, if ever requested. | ||
|
|
||
| [How to do it with Webpack](https://github.com/webpack-contrib/file-loader) | ||
|
|
||
| [How to do it with Rollup](https://github.com/rollup/rollup-plugin-url) | ||
|
|
||
| Rollup example: | ||
|
|
||
| ```js | ||
| import url from "rollup-plugin-url"; | ||
| ... | ||
| plugins.push(url({ | ||
| limit: 0, | ||
| include: [ | ||
| /.*assets\/.*\.json/, | ||
| ], | ||
| emitFiles: true, | ||
| fileName: "[name].[hash][extname]", | ||
| publicPath: YOUR_APPLICATION_PUBLIC_PATH + "/resources/", | ||
| })); | ||
| ``` | ||
|
|
||
| Please note that the code above is just sample snippet, and will not work on its own. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| # Migration guides | ||
|
|
||
| ## Migrating from `1.0.0-rc.4` to `1.0.0-rc.5` | ||
|
|
||
| ### New npm package: `@ui5/webcomponents-icons` | ||
|
|
||
| All individual icons were moved to a new npm package called `@ui5/webcomponents-icons`. | ||
|
|
||
| If you are using icons in your project: | ||
|
|
||
| 1. Add the new package as a dependency to your project | ||
|
|
||
| `npm i @ui5/webcomponents-icons --save` | ||
|
|
||
| or | ||
|
|
||
| `yarn add @ui5/webcomponents-icons` | ||
|
|
||
| depending on your package manager. | ||
|
|
||
| 2. Change the imports for the individual icons (if you were importing them one by one): | ||
|
|
||
| Current code | Change to | ||
| -----|---- | ||
| `@ui5/webcomponents/dist/icons/add.js` | `@ui5/webcomponents-icons/dist/icons/add.js` | ||
| `@ui5/webcomponents/dist/icons/search.js` | `@ui5/webcomponents-icons/dist/icons/search.js` | ||
| etc... | etc... | ||
|
|
||
| *Note:* The `ui5-icon` web component is not affected by this change, it is still in the `@ui5/webcomponents` package. Only the icons themselves (the icon assets) have been moved. | ||
|
|
||
|
|
||
| ### New npm package: `@ui5/webcomponents-fiori` | ||
|
|
||
| The `ui5-shellbar` and `ui5-shellbar-item` web components were moved to a new npm package called `@ui5/webcomponents-fiori`. | ||
|
|
||
| If you are using `ui5-shellbar` in your project: | ||
|
|
||
| 1. Add the new package as a dependency to your project | ||
|
|
||
| `npm i @ui5/webcomponents-fiori --save` | ||
|
|
||
| or | ||
|
|
||
| `yarn add @ui5/webcomponents-fiori` | ||
|
|
||
| depending on your package manager. | ||
|
|
||
| 2. Change the imports: | ||
|
|
||
| Current code | Change to | ||
| -----|---- | ||
| `@ui5/webcomponents/dist/ShellBar.js` | `@ui5/webcomponents-fiori/dist/ShellBar.js` | ||
| `@ui5/webcomponents/dist/ShellBarItem.js` | `@ui5/webcomponents-fiori/dist/ShellBarItem.js` | ||
|
|
||
| ### `ui5-icon` | ||
|
|
||
| The `src` property was renamed to `name` and accepts icon name (such as `add`) instead of icon src (such as `sap-icon://add`). | ||
| Note: the `src` property will continue to work until the next release due to the impact of the change, but will produce a warning in the console. | ||
|
|
||
| Current code | Change to | ||
| -----|---- | ||
| `<ui5-icon src="sap-icon://add">` | `<ui5-icon name="add">` | ||
|
|
||
| ### `ui5-card` | ||
|
|
||
| The `avatar` property was removed. | ||
| Use the `avatar` slot instead - pass an icon(`<ui5-icon>`) or an image(`<img>`). | ||
| Example: | ||
|
|
||
| Current code | Change to | ||
| -----|---- | ||
| `<ui5-card avatar="sap-icon://add"></ui5-card>` | `<ui5-card><ui5-icon name="add" slot="avatar"></ui5-icon></ui5-card>` | ||
| `<ui5-card avatar="http://url/to/my/image"></ui5-card>` | `<ui5-card><img src="http://url/to/my/image" slot="avatar"/></ui5-card>` | ||
|
|
||
| ### `ui5-shellbar` | ||
|
|
||
| In addition to the fact that `ui5-shellbar` was moved to `@ui5/webcomponents-fiori`, the `icon` slot was renamed to `startButton`. | ||
|
|
||
| The `ui5-shellbar` CoPilot is now a static SVG by default. In order to have the animated SVG again, you need to manually import the following feature: | ||
| ```js | ||
| import "@ui5/webcomponents-fiori/dist/features/CoPilotAnimation.js"; | ||
| ``` | ||
|
|
||
|
|
||
| ### `ui5-shellbar-item` | ||
|
|
||
| In addition to the fact that `ui5-shellbar-item` was moved to `@ui5/webcomponents-fiori`, the `src` property was renamed to `icon` and accepts icon name (such as `add`) instead of icon src (such as `sap-icon://add`) | ||
|
|
||
| Current code | Change to | ||
| -----|---- | ||
| `<ui5-shellbar-item src="sap-icon://add">` | `<ui5-shellbar-item icon="add">` | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters