From 2b7bf7248c89f8b42c2e2b8efd23e9be7c7292a6 Mon Sep 17 00:00:00 2001 From: ilhan007 Date: Thu, 9 Jul 2026 15:43:46 +0300 Subject: [PATCH 1/4] docs: add SAPUI5 framework integration guide Add a new article under Frameworks describing how to use UI5 Web Components inside a SAPUI5 (and OpenUI5) application: when to use them, how to scaffold and integrate a project via ui5-tooling-modules, the API mapping to SAPUI5 concepts, and the build-once-reuse-everywhere strategy. --- docs/3-frameworks/05-SAPUI5.md | 115 +++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 docs/3-frameworks/05-SAPUI5.md diff --git a/docs/3-frameworks/05-SAPUI5.md b/docs/3-frameworks/05-SAPUI5.md new file mode 100644 index 0000000000000..7b62cab67b3ef --- /dev/null +++ b/docs/3-frameworks/05-SAPUI5.md @@ -0,0 +1,115 @@ +# UI5 Web Components & SAPUI5 + +UI5 Web Components are first-class citizens in SAPUI5 (and OpenUI5). A UI5 Web Component can be required and used like a regular SAPUI5 control — its properties map to SAPUI5 properties, its slots to aggregations, and its events to SAPUI5 events. This means you can drop a Web Component into an XML view or a controller and use it side-by-side with the SAPUI5 controls you already know. + +## Build once, reuse across frameworks + +The idea is to build each UI element once as a UI5 Web Component and reuse it everywhere — React, Angular, Vue, SAPUI5, and any other framework or plain HTML page. + +New or selected UI elements, over time, will be delivered as UI5 Web Components to avoid duplication and exposed as SAPUI5 controls. When that happens, the integration is done by SAPUI5 itself — application developers don't need to install a Web Component package or change their code. You keep using the SAPUI5 control the way you always have, and it transparently benefits from the shared UI5 Web Components implementation underneath. + +## How to Integrate + +The full, up-to-date instructions live in the SAPUI5 documentation: [Using Web Components](https://ui5.sap.com/#/topic/1c80793df5bb424091954697fc0b2828). A working sample project is also available in the [UI5 ecosystem showcase (`ui5-tsapp-webc`)](https://github.com/ui5-community/ui5-ecosystem-showcase/tree/main/showcases/ui5-tsapp-webc). Here is a short summary. + +### Step 1. Create a SAPUI5 app + +If you don't already have one, scaffold a SAPUI5 (TypeScript) app with the community generator: + +```bash +npx generator-easy-ui5 project +``` + +Answer the prompts (project name, namespace, TypeScript support, etc.). For more scaffolding options and details, see the [Easy UI5 generator](https://github.com/SAP/generator-easy-ui5) and the [SAPUI5 TypeScript tutorial](https://sap.github.io/ui5-typescript/). + +### Step 2. Install the UI5 tooling extension + +The [`ui5-tooling-modules`](https://www.npmjs.com/package/ui5-tooling-modules) CLI extension resolves and bundles Web Components modules during development and build. + +```bash +npm install ui5-tooling-modules --save-dev --ignore-scripts=false -rte=ui5.yaml,ui5-local.yaml,ui5-deploy.yaml +``` + +The `-rte` (register-tooling-extension) flag registers the custom task and middleware in your `ui5*.yaml` files automatically. If your project has only `ui5.yaml`, use `-rte` without a value. + +### Step 3. Install the Web Components packages you need + +```bash +npm install @ui5/webcomponents +npm install @ui5/webcomponents-fiori +npm install @ui5/webcomponents-ai +# ... +``` + +Add them as **dependencies** (not `devDependencies`) so `ui5-tooling-modules` can resolve them at build time. + +### Step 4. Use the components in XML views + +Declare a namespace for the package and use the Web Component's class name as an XML node: + +```xml + + + + + + + + + + +``` + +Data binding, formatters, and event handlers work exactly like they do for any other SAPUI5 control. + +### Step 5. Use the components in controllers + +Require the Web Component classes just like SAPUI5 modules. Don't forget to include the `Assets` module of each `@ui5/webcomponents-*` package you use — it registers the theme styles and translations at runtime. + +```js +sap.ui.define([ + "@ui5/webcomponents/Panel", + "@ui5/webcomponents-ai/Button", + "@ui5/webcomponents-ai/ButtonState", + "@ui5/webcomponents-icons/ai", + "@ui5/webcomponents/dist/Assets", + "@ui5/webcomponents-ai/dist/Assets", + "@ui5/webcomponents-fiori/dist/Assets" +], (Panel, AIButton, AIButtonState) => { + "use strict"; + // ... +}); +``` + +## When to Use + +SAPUI5 already ships a large library of controls, so we don't recommend replacing them one-by-one with the equivalent UI5 Web Component. Our guidance is: + +- **Recommended** — use UI5 Web Components in SAPUI5 for components that don't exist there, not as a wholesale replacement for the SAPUI5 control library — for example, the AI-related components in `@ui5/webcomponents-ai` (`Button`, `PromptInput`, …). +- **Not recommended** — using a UI5 Web Component to replace a basic SAPUI5 control that already exists (e.g. a plain button, input, or list). Mixing two implementations of the same primitive adds complexity without benefit. + +## API Mapping + +For quick reference, this is how UI5 Web Components APIs surface in SAPUI5: + +| UI5 Web Components | SAPUI5 | Notes | +|--------------------|---------------|-------------------------------------------------------------------------------------------| +| properties | properties | Standard UI5 getters/setters, e.g. `Button#getText()`, `Button#setText()` | +| readonly properties| getters | Camel-cased getter, e.g. `AvatarGroup#getColorScheme()` — no setter | +| slots | aggregations | Standard UI5 aggregations with `add*`, `get*`, `remove*` accessors | +| events | events | Standard UI5 events; dashed names become camelCase (e.g. `selected-item` → `selectedItem`)| +| methods | methods | Any Web Component API is available, e.g. `Tree#walk()` | +| — | associations | SAPUI5-only concept; any Web Component property that takes an element `id` is exposed as an association | + +A few additional naming differences: + +- The DOM `disabled` attribute is exposed as the SAPUI5 property `enabled`. +- The default slot is exposed as the `content` aggregation. +- Web Components that allow native text content expose a bindable `text` property. + +For all details, edge cases, and the most current guidance, refer to the [SAPUI5 documentation topic on Using Web Components](https://ui5.sap.com/#/topic/1c80793df5bb424091954697fc0b2828). From 98174705a4e09b8b0c6bf48c4a8bbfbdd79f1ed9 Mon Sep 17 00:00:00 2001 From: ilhan007 Date: Thu, 9 Jul 2026 16:15:34 +0300 Subject: [PATCH 2/4] docs: correct SAPUI5 app scaffolding command Verified the integration guide end-to-end against a real scaffolded app. Fixes found during verification: - Step 1: 'npx generator-easy-ui5 project' fails ('could not determine executable to run') because generator-easy-ui5 is a Yeoman generator with no npx bin. Use 'npx -p yo -p generator-easy-ui5 yo easy-ui5 project' instead (no global install needed). - Drop the 'TypeScript' wording since the default template scaffolds a JS app; point to the UI5 CLI Getting Started guide. - Use the canonical ui5-community/generator-easy-ui5 repo link. - Relax the -rte note: missing yaml files are skipped, so the multi-file form is safe even with only ui5.yaml. --- docs/3-frameworks/05-SAPUI5.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/3-frameworks/05-SAPUI5.md b/docs/3-frameworks/05-SAPUI5.md index 7b62cab67b3ef..54f8411c7fab9 100644 --- a/docs/3-frameworks/05-SAPUI5.md +++ b/docs/3-frameworks/05-SAPUI5.md @@ -14,13 +14,13 @@ The full, up-to-date instructions live in the SAPUI5 documentation: [Using Web C ### Step 1. Create a SAPUI5 app -If you don't already have one, scaffold a SAPUI5 (TypeScript) app with the community generator: +If you don't already have one, scaffold a SAPUI5 app with the community [Easy UI5 generator](https://github.com/ui5-community/generator-easy-ui5). It runs on top of [Yeoman](https://yeoman.io/), so you can invoke it without a global install: ```bash -npx generator-easy-ui5 project +npx -p yo -p generator-easy-ui5 yo easy-ui5 project ``` -Answer the prompts (project name, namespace, TypeScript support, etc.). For more scaffolding options and details, see the [Easy UI5 generator](https://github.com/SAP/generator-easy-ui5) and the [SAPUI5 TypeScript tutorial](https://sap.github.io/ui5-typescript/). +Answer the prompts (project name, namespace, framework, etc.). For more scaffolding options and details, see the [Easy UI5 generator](https://github.com/ui5-community/generator-easy-ui5) and the [UI5 CLI Getting Started guide](https://ui5.github.io/cli/stable/pages/GettingStarted/). ### Step 2. Install the UI5 tooling extension @@ -30,7 +30,7 @@ The [`ui5-tooling-modules`](https://www.npmjs.com/package/ui5-tooling-modules) C npm install ui5-tooling-modules --save-dev --ignore-scripts=false -rte=ui5.yaml,ui5-local.yaml,ui5-deploy.yaml ``` -The `-rte` (register-tooling-extension) flag registers the custom task and middleware in your `ui5*.yaml` files automatically. If your project has only `ui5.yaml`, use `-rte` without a value. +The `-rte` (register-tooling-extension) flag registers the custom task and middleware in your `ui5*.yaml` files automatically. Any listed file that doesn't exist is simply skipped, so the command above is safe even if your project only has `ui5.yaml` — you can also pass `-rte` without a value to target just that file. ### Step 3. Install the Web Components packages you need From f88c631957948bf06b830fad801f81128b30b76c Mon Sep 17 00:00:00 2001 From: ilhan007 Date: Fri, 10 Jul 2026 09:36:11 +0300 Subject: [PATCH 3/4] docs(sapui5): use global-install scaffold command as primary Switch Step 1 to the officially documented 'npm install -g yo generator-easy-ui5 && yo easy-ui5 project' form, matching the npm readme and UI5 CLI Getting Started guide. Keep the npx one-liner as a subtle inline fallback for those who prefer no global install. --- docs/3-frameworks/05-SAPUI5.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/3-frameworks/05-SAPUI5.md b/docs/3-frameworks/05-SAPUI5.md index 54f8411c7fab9..b5eddffc5cc0d 100644 --- a/docs/3-frameworks/05-SAPUI5.md +++ b/docs/3-frameworks/05-SAPUI5.md @@ -14,13 +14,14 @@ The full, up-to-date instructions live in the SAPUI5 documentation: [Using Web C ### Step 1. Create a SAPUI5 app -If you don't already have one, scaffold a SAPUI5 app with the community [Easy UI5 generator](https://github.com/ui5-community/generator-easy-ui5). It runs on top of [Yeoman](https://yeoman.io/), so you can invoke it without a global install: +If you don't already have one, scaffold a SAPUI5 app with the community [Easy UI5 generator](https://github.com/ui5-community/generator-easy-ui5), a [Yeoman](https://yeoman.io/)-based generator: ```bash -npx -p yo -p generator-easy-ui5 yo easy-ui5 project +npm install --global yo generator-easy-ui5 +yo easy-ui5 project ``` -Answer the prompts (project name, namespace, framework, etc.). For more scaffolding options and details, see the [Easy UI5 generator](https://github.com/ui5-community/generator-easy-ui5) and the [UI5 CLI Getting Started guide](https://ui5.github.io/cli/stable/pages/GettingStarted/). +Answer the prompts (project name, namespace, framework, etc.). To run it without a global install, you can also use `npx -p yo -p generator-easy-ui5 yo easy-ui5 project`. For more scaffolding options and details, see the [Easy UI5 generator](https://github.com/ui5-community/generator-easy-ui5) and the [UI5 CLI Getting Started guide](https://ui5.github.io/cli/stable/pages/GettingStarted/). ### Step 2. Install the UI5 tooling extension From 37acddb6453e4cd32b070e3f2c22eec00a9a37a8 Mon Sep 17 00:00:00 2001 From: ilhan007 Date: Fri, 10 Jul 2026 10:30:27 +0300 Subject: [PATCH 4/4] docs(frameworks): add 'build once, reuse everywhere' to landing page Move the framework-agnostic 'build once, reuse everywhere' idea to the common Frameworks landing page, where it applies to all frameworks. Trim the SAPUI5 article's intro to a single sentence about components being delivered as Web Components to avoid duplication. --- docs/3-frameworks/05-SAPUI5.md | 6 +----- docs/3-frameworks/README.md | 4 ++++ 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/3-frameworks/05-SAPUI5.md b/docs/3-frameworks/05-SAPUI5.md index b5eddffc5cc0d..c2d017619e6c2 100644 --- a/docs/3-frameworks/05-SAPUI5.md +++ b/docs/3-frameworks/05-SAPUI5.md @@ -2,11 +2,7 @@ UI5 Web Components are first-class citizens in SAPUI5 (and OpenUI5). A UI5 Web Component can be required and used like a regular SAPUI5 control — its properties map to SAPUI5 properties, its slots to aggregations, and its events to SAPUI5 events. This means you can drop a Web Component into an XML view or a controller and use it side-by-side with the SAPUI5 controls you already know. -## Build once, reuse across frameworks - -The idea is to build each UI element once as a UI5 Web Component and reuse it everywhere — React, Angular, Vue, SAPUI5, and any other framework or plain HTML page. - -New or selected UI elements, over time, will be delivered as UI5 Web Components to avoid duplication and exposed as SAPUI5 controls. When that happens, the integration is done by SAPUI5 itself — application developers don't need to install a Web Component package or change their code. You keep using the SAPUI5 control the way you always have, and it transparently benefits from the shared UI5 Web Components implementation underneath. +New or selected UI elements, over time, will be delivered as UI5 Web Components to avoid duplication. ## How to Integrate diff --git a/docs/3-frameworks/README.md b/docs/3-frameworks/README.md index 39faaa5a673eb..cbfef0dd18cad 100644 --- a/docs/3-frameworks/README.md +++ b/docs/3-frameworks/README.md @@ -4,3 +4,7 @@ In this section, you can find framework-specific tutorials on how to get started We have created a bunch of tutorials that cover the integration of UI5 Web Components with some of the most popular existing frameworks. In these tutorials, you will find some framework-specific features & learn how to use them. You might want to check them before you start active development. + +## Build once, reuse everywhere + +The idea is to build each UI element once as a UI5 Web Component and reuse it everywhere — React, Angular, Vue, SAPUI5, and any other framework or plain HTML page. Instead of reimplementing the same control for each framework, you maintain a single implementation and consume it wherever you need it.