Skip to content

Commit 93bbee1

Browse files
oblomov-devoblomov-dev
authored
Merge pull request #106 from abap2UI5/claude/sleepy-bell-FvTXu
Expand and reorganize setup documentation with bootstrap attributes
2 parents 1cb7e95 + 026178f commit 93bbee1

8 files changed

Lines changed: 238 additions & 31 deletions

File tree

‎docs/.vitepress/config.mjs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -305,8 +305,8 @@ export default defineConfig({
305305
collapsed: true,
306306
items: [
307307
{ text: "Theme", link: "/configuration/setup/theme" },
308-
{ text: "UI5 Bootstrapping", link: "/configuration/setup/ui5_bootstrapping" },
309-
{ text: "Title", link: "/configuration/setup/title" },
308+
{ text: "Bootstrapping", link: "/configuration/setup/ui5_bootstrapping" },
309+
{ text: "Bootstrap Attributes", link: "/configuration/setup/bootstrap_attributes" },
310310
{ text: "Style / CSS", link: "/configuration/setup/style_css" },
311311
{ text: "Logon Language", link: "/configuration/setup/logon_language" },
312312
],

‎docs/configuration/setup.md‎

Lines changed: 28 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,40 @@ outline: [2, 4]
33
---
44
# Setup
55

6-
You can run abap2UI5 with a variety of custom configurations. The default setup works out of the box. To customize it, implement the `z2ui5_if_exit` interface:
6+
Every UI5 application has an `index.html` that bootstraps the framework, picks a theme, defines the page title and so on. With abap2UI5 you don't maintain that file by hand — the framework generates it on every page load. To change what ends up in it, implement the `z2ui5_if_exit` interface in your own ABAP class:
77

88
```abap
99
CLASS zcl_a2ui5_user_exit DEFINITION PUBLIC.
1010
1111
PUBLIC SECTION.
12-
INTERFACES z2ui5_if_exit.
12+
INTERFACES z2ui5_if_exit.
13+
14+
ENDCLASS.
15+
16+
CLASS zcl_a2ui5_user_exit IMPLEMENTATION.
17+
18+
METHOD z2ui5_if_exit~set_config_http_get.
19+
" your configuration goes here
20+
ENDMETHOD.
1321
1422
ENDCLASS.
1523
```
1624

17-
See the following pages for specific options:
18-
- [Theme](/configuration/setup/theme)
19-
- [UI5 Bootstrapping](/configuration/setup/ui5_bootstrapping)
20-
- [Title](/configuration/setup/title)
21-
- [Style / CSS](/configuration/setup/style_css)
22-
- [Logon Language](/configuration/setup/logon_language)
25+
`set_config_http_get` is called once per page request — i.e. when the browser asks for the HTML shell. The changing parameter `cs_config` holds every value that ends up in the generated `index.html`.
26+
27+
## What You Can Configure
28+
29+
| Page | Field on `cs_config` | Affects in `index.html` |
30+
|-------------------------------------------------------------------|------------------------------|-------------------------|
31+
| [Theme](/configuration/setup/theme) | `theme` | `data-sap-ui-theme` on the bootstrap script |
32+
| [Bootstrapping](/configuration/setup/ui5_bootstrapping) | `src` | `src` of the bootstrap script (UI5 version + delivery channel) |
33+
| [Bootstrap Attributes](/configuration/setup/bootstrap_attributes) | `t_add_config` | Additional `data-sap-ui-*` attributes |
34+
| [Style / CSS](/configuration/setup/style_css) | `styles_css` | Inline `<style>` block in the page `<head>` |
35+
| [Language](/configuration/setup/logon_language) | URL parameter `sap-language` | SAP session language + UI5 locale |
36+
37+
Security-relevant headers and the Content Security Policy meta tag are configured separately — see [Security](/configuration/security).
38+
39+
## See Also
40+
41+
- Official SAP documentation on [UI5 bootstrapping](https://sapui5.hana.ondemand.com/#/topic/91f2cebe7c8e4d289fd80a4f0c0bd2ca) and [configuration options](https://sapui5.hana.ondemand.com/#/topic/91f2d03b6f4d1014b6dd926db0e91070).
42+
- The [User Exit](/advanced/extensibility/user_exits) page documents every hook on `z2ui5_if_exit`.

‎docs/configuration/setup/bootstrap_attributes.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
outline: [2, 4]
3+
---
4+
# Bootstrap Attributes
5+
6+
The UI5 bootstrap script tag in `index.html` accepts a long list of `data-sap-ui-*` attributes — they control asynchronous loading, the compatibility version, clickjacking protection, locale, preloaded libraries and many more. abap2UI5 already sets sensible defaults:
7+
8+
```html
9+
<script id="sap-ui-bootstrap"
10+
src="…/sap-ui-core.js"
11+
data-sap-ui-theme="sap_horizon"
12+
data-sap-ui-resourceroots='{ "z2ui5": "./" }'
13+
data-sap-ui-oninit="onInitComponent"
14+
data-sap-ui-compatVersion="edge"
15+
data-sap-ui-async="true"
16+
data-sap-ui-frameOptions="trusted"
17+
data-sap-ui-bindingSyntax="complex">
18+
</script>
19+
```
20+
21+
## Add or Override Attributes
22+
23+
To add an attribute — or override one of the defaults — append a row to `cs_config-t_add_config`. Each row contributes one `name='value'` pair to the script tag:
24+
25+
```abap
26+
METHOD z2ui5_if_exit~set_config_http_get.
27+
28+
cs_config-t_add_config = VALUE #(
29+
( n = `data-sap-ui-libs` v = `sap.m,sap.ui.table` )
30+
( n = `data-sap-ui-language` v = `en` )
31+
( n = `data-sap-ui-frameOptions` v = `allow` )
32+
( n = `data-sap-ui-preload` v = `async` ) ).
33+
34+
ENDMETHOD.
35+
```
36+
37+
## Useful Attributes
38+
39+
| Attribute | Purpose |
40+
|---------------------------------|---------|
41+
| `data-sap-ui-libs` | Comma-separated list of UI5 libraries to preload (e.g. `sap.m,sap.ui.table`). Trade load time against startup speed. |
42+
| `data-sap-ui-language` | UI5 locale; overrides the browser language. See [Language](/configuration/setup/logon_language). |
43+
| `data-sap-ui-compatVersion` | Compatibility version, controls UI5 behaviour for deprecated APIs. abap2UI5 defaults to `edge`. |
44+
| `data-sap-ui-async` | Asynchronous module loading. Default `true` — only change for legacy reasons. |
45+
| `data-sap-ui-preload` | Module preloading strategy: `async`, `sync` or empty (off). |
46+
| `data-sap-ui-frameOptions` | Clickjacking protection: `trusted`, `allow`, `deny`. Default `trusted`. |
47+
| `data-sap-ui-allowlistService` | Endpoint for the URL allowlist service. |
48+
| `data-sap-ui-bindingSyntax` | Binding syntax: `complex` (default) or `simple`. abap2UI5 expressions require `complex`. |
49+
| `data-sap-ui-resourceroots` | Additional resource roots for custom libraries. |
50+
| `data-sap-ui-xx-componentpreload` | Component-preload strategy for very large apps. |
51+
52+
Attributes set by abap2UI5 by default can be overridden — a row with the same name wins over the framework default.
53+
54+
## See Also
55+
56+
- Official UI5 [configuration options and URL parameters reference](https://sapui5.hana.ondemand.com/#/topic/91f2d03b6f4d1014b6dd926db0e91070) — the authoritative list of every supported attribute.
57+
- [Bootstrapping](/configuration/setup/ui5_bootstrapping) — how to change the bootstrap script source.

‎docs/configuration/setup/logon_language.md‎

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,47 @@
11
---
22
outline: [2, 4]
33
---
4-
# Logon Language
4+
# Language
55

6-
To pick the logon language, use the `sap-language` URL parameter. For other URL parameters, see the [SAP documentation](https://help.sap.com/doc/saphelp_nw75/7.5.5/en-US/8b/46468c433b40c3b87b2e07f34dea1b/content.htm?no_cache=true).
6+
abap2UI5 picks the user's logon language automatically from the SAP session — every translated text retrieved via `z2ui5_cl_util=>trans_get_text( )`, every OData/CDS label, every message class is returned in that language. For most applications no extra configuration is required.
7+
8+
## Override the Backend Language
9+
10+
To force a specific SAP logon language at startup, append the `sap-language` URL parameter:
11+
12+
```
13+
…/z2ui5/sample?sap-language=EN
14+
…/z2ui5/sample?sap-language=DE
15+
```
16+
17+
The value is a one- or two-character SAP language key (typically ISO 639-1, e.g. `EN`, `DE`, `FR`, `JA`). The server sets the user's session language for this request, so backend reads, OData calls and translated texts all use that locale.
18+
19+
## Override the UI5 Frontend Locale
20+
21+
The UI5 framework keeps a *separate* locale for date and number formatting, control labels ("Search", "Cancel", …) and the calendar week. By default UI5 derives it from the browser. You can pin it with the URL parameter `sap-ui-language`:
22+
23+
```
24+
…/z2ui5/sample?sap-ui-language=de
25+
```
26+
27+
Most apps don't need this — the browser locale and the SAP logon language agree in practice. Set it explicitly when you need full control, e.g. in test environments.
28+
29+
## Forcing the Frontend Locale at Startup
30+
31+
You can also pin the UI5 locale via the bootstrap, instead of relying on a URL parameter:
32+
33+
```abap
34+
METHOD z2ui5_if_exit~set_config_http_get.
35+
36+
cs_config-t_add_config = VALUE #(
37+
( n = `data-sap-ui-language` v = `en` ) ).
38+
39+
ENDMETHOD.
40+
```
41+
42+
See [Bootstrap Attributes](/configuration/setup/bootstrap_attributes) for more on this mechanism.
43+
44+
## See Also
45+
46+
- [SAP URL parameter reference](https://help.sap.com/doc/saphelp_nw75/7.5.5/en-US/8b/46468c433b40c3b87b2e07f34dea1b/content.htm?no_cache=true) — full list of supported parameters.
47+
- Official UI5 documentation on [language and locale](https://sapui5.hana.ondemand.com/#/topic/91f21f176f4d1014b6dd926db0e91070).

‎docs/configuration/setup/style_css.md‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,36 @@ outline: [2, 4]
33
---
44
# Style / CSS
55

6-
To set custom styles or CSS:
6+
UI5 supports app-specific CSS in addition to the theme. abap2UI5 injects whatever string you assign to `cs_config-styles_css` directly into a `<style>` block in the page `<head>`, so any selector you write is applied to your application.
7+
78
```abap
89
METHOD z2ui5_if_exit~set_config_http_get.
910
10-
cs_config-styles_css = `<<own css>>`.
11+
cs_config-styles_css =
12+
|body \{ background-color: #f5f5f5; \}| &&
13+
|.myRedButton \{ color: red; font-weight: bold; \}|.
1114
1215
ENDMETHOD.
1316
```
17+
18+
In the XML view you then reference your class via the `class` property:
19+
20+
```abap
21+
view->button( text = `Delete` class = `myRedButton` ).
22+
```
23+
24+
## When to Use Custom CSS
25+
26+
- Tweak spacing, colours or fonts that the theme does not expose as a control property.
27+
- Style abap2UI5 features that don't have a built-in option (e.g. a corporate background image).
28+
- Override the SAP control look in edge cases.
29+
30+
For larger visual changes — corporate fonts, brand colours, custom logo — prefer the official [UI Theme Designer](https://sapui5.hana.ondemand.com/#/topic/be8f7c61bb2444299b3f3429b986e8be). It produces a self-contained theme that you can host yourself and assign via `cs_config-theme`. This keeps your styles maintainable across UI5 upgrades.
31+
32+
## Tips
33+
34+
- Be careful with selectors that target UI5 internals (`.sapMBtn`, `.sapUiTableCell`, …). They are not part of UI5's public API and may change between versions.
35+
- Wrap rules in a parent class (e.g. `.myApp .sapMTitle`) to limit their reach.
36+
- Inside ABAP string templates (`| … |`), the curly braces `{` and `}` must be escaped as `\{` and `\}`.
37+
38+
See the [UI5 styling documentation](https://sapui5.hana.ondemand.com/#/topic/9c9e14990d864bb799d70d2bc6c7d4f7) for guidance on what is safe to customise.

‎docs/configuration/setup/theme.md‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,49 @@ outline: [2, 4]
33
---
44
# Theme
55

6-
To change the theme:
6+
The theme defines the look and feel of every UI5 control — colours, fonts, paddings, spacings. In a hand-written `index.html` it is set via the `data-sap-ui-theme` attribute on the bootstrap script. In abap2UI5 you set it from ABAP:
7+
78
```abap
89
METHOD z2ui5_if_exit~set_config_http_get.
910
1011
cs_config-theme = `sap_horizon_dark`.
1112
1213
ENDMETHOD.
1314
```
15+
16+
If you leave the field empty, abap2UI5 falls back to `sap_horizon`.
17+
18+
## Available Themes
19+
20+
The themes shipped with current UI5 versions are:
21+
22+
| Theme name | Description |
23+
|----------------------|--------------------------------------|
24+
| `sap_horizon` | Default Horizon (light) |
25+
| `sap_horizon_dark` | Horizon dark |
26+
| `sap_horizon_hcb` | Horizon high-contrast black |
27+
| `sap_horizon_hcw` | Horizon high-contrast white |
28+
| `sap_fiori_3` | Quartz Light (previous default) |
29+
| `sap_fiori_3_dark` | Quartz Dark |
30+
| `sap_fiori_3_hcb` | Quartz high-contrast black |
31+
| `sap_fiori_3_hcw` | Quartz high-contrast white |
32+
| `sap_belize` | Belize (older, blue) |
33+
| `sap_belize_plus` | Belize Plus (older, grey background) |
34+
35+
See the official [list of available themes](https://sapui5.hana.ondemand.com/#/topic/4cfe7eff3001447a9d4b0abeaba95166) for the most up-to-date catalogue.
36+
37+
## End-User Override
38+
39+
The user can override the theme at runtime with the URL parameter `sap-ui-theme`:
40+
41+
```
42+
…/z2ui5/sample?sap-ui-theme=sap_horizon_dark
43+
```
44+
45+
This is convenient for trying out a theme without redeploying.
46+
47+
## Custom Themes
48+
49+
For brand-specific colours, fonts or logos use the SAP [UI Theme Designer](https://sapui5.hana.ondemand.com/#/topic/be8f7c61bb2444299b3f3429b986e8be) to generate a self-contained theme. Host it on your SAP system or any web server and point `cs_config-theme` to its theme ID (the bootstrap source must reach it via the standard UI5 theme loader).
50+
51+
See the official [theming documentation](https://sapui5.hana.ondemand.com/#/topic/91f2cebe7c8e4d289fd80a4f0c0bd2ca) for the bigger picture.

‎docs/configuration/setup/title.md‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎docs/configuration/setup/ui5_bootstrapping.md‎

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,53 @@
11
---
22
outline: [2, 4]
33
---
4-
# UI5 Bootstrapping
4+
# Bootstrapping
5+
6+
Bootstrapping is the process of loading the UI5 runtime into the browser. abap2UI5 generates a `<script src="…/sap-ui-core.js">` tag in the page `<head>`; the URL decides which UI5 version is loaded, from which delivery channel (CDN or your own server) and whether the cache-buster is active.
7+
8+
## Pick a Bootstrap Source
59

6-
To pick the source for bootstrapping UI5:
710
```abap
811
METHOD z2ui5_if_exit~set_config_http_get.
912
1013
cs_config-src = `https://ui5.sap.com/1.116.0/resources/sap-ui-core.js`.
1114
1215
ENDMETHOD.
1316
```
14-
See the bootstrapping variants and SAP limitations, documented in the [SAP UI5 docs](https://sapui5.hana.ondemand.com/#/topic/2d3eb2f322ea4a82983c1c62a33ec4ae).
17+
18+
Without an override, abap2UI5 uses the OpenUI5 cache-buster URL — i.e. the latest stable OpenUI5 build.
19+
20+
## Common Sources
21+
22+
| URL | When to use it |
23+
|---------------------------------------------------------------------------|----------------|
24+
| `https://sdk.openui5.org/resources/sap-ui-cachebuster/sap-ui-core.js` | OpenUI5 latest, cache-buster enabled — the abap2UI5 default |
25+
| `https://sdk.openui5.org/1.120.0/resources/sap-ui-core.js` | OpenUI5, pinned version |
26+
| `https://ui5.sap.com/resources/sap-ui-core.js` | SAPUI5 latest |
27+
| `https://ui5.sap.com/1.120.0/resources/sap-ui-core.js` | SAPUI5, pinned version |
28+
| `https://sapui5.hana.ondemand.com/1.120.0/resources/sap-ui-core.js` | SAPUI5 legacy host name (still works, but `ui5.sap.com` is the preferred alias) |
29+
| `/sap/public/bc/ui5_ui5/resources/sap-ui-core.js` | Locally hosted UI5 on the same SAP system |
30+
31+
### OpenUI5 vs SAPUI5
32+
33+
- **OpenUI5** (`sdk.openui5.org`) is the Apache-licensed open-source subset of UI5. It contains all libraries a typical abap2UI5 app uses: `sap.m`, `sap.ui.core`, `sap.ui.layout`, `sap.ui.table`, `sap.ui.unified`, `sap.uxap`, `sap.f`, `sap.tnt`, `sap.viz`.
34+
- **SAPUI5** (`ui5.sap.com`) is the SAP-licensed superset. It adds e.g. `sap.ui.comp` (Smart Controls, `ValueHelpDialog`), `sap.suite.ui.commons`, `sap.ui.generic.app` and the Fiori Elements floorplans.
35+
36+
If you only need controls available in OpenUI5 — which covers the vast majority of abap2UI5 apps — stick with `sdk.openui5.org`. Switch to `ui5.sap.com` only when you genuinely need a `sap.ui.comp.*` control or a SAPUI5-only library.
37+
38+
### Pinning a Version
39+
40+
Hard-coding a version (`/1.116.0/`) keeps your app stable when SAP ships a new patch. Without a version the CDN serves the current "evergreen" release, which is convenient but can break the app the next time SAP rolls out a change. For productive apps, pin the version explicitly.
41+
42+
### Cache-Buster
43+
44+
URLs containing `sap-ui-cachebuster` append a versioned token to every asset URL, so the browser cache is invalidated automatically whenever SAP releases a new build. Use it when you intentionally stay on the latest release.
45+
46+
### Local Hosting
47+
48+
If your gateway has the UI5 ABAP repository (`/sap/public/bc/ui5_ui5/resources/`) installed, you can serve UI5 from your own SAP system instead of a CDN. This is faster on the intranet, works offline and avoids any external dependency, but you need a basis admin to keep the UI5 version current. See [UI5 Version](/configuration/ui5_versions) for the available approaches.
49+
50+
## See Also
51+
52+
- Official SAP documentation on [bootstrapping variants](https://sapui5.hana.ondemand.com/#/topic/2d3eb2f322ea4a82983c1c62a33ec4ae) and [the supported tags](https://sapui5.hana.ondemand.com/#/topic/91f2cebe7c8e4d289fd80a4f0c0bd2ca).
53+
- [Bootstrap Attributes](/configuration/setup/bootstrap_attributes) — how to add extra `data-sap-ui-*` parameters next to `src`.

0 commit comments

Comments
 (0)