sap / openui5-docs

OpenUI5 Markdown Documentation

openui5-docs

Your place to contribute to the OpenUI5 documentation

Introduction

This repository contains the official OpenUI5 documentation from the OpenUI5 Demo Kit as markdown files. You have the chance to comment on and contribute to the documentation to improve it for the OpenUI5 community.

Please note: This repository reflects the current development status of the OpenUI5 documentation, it is not identical to the content of the OpenUI5 Demo Kit.

How Does It Work?

1. A daily job fills the docs folder of this repository from our content management system.

2. You can view the content in two ways:

   • OpenUI5 Markdown Documentation (raw)

     The docs folder contains an enriched markdown export of the official OpenUI5 documentation from the OpenUI5 Demo Kit. This is already quite usable to browse the documentation and find topics you want to improve.

   • OpenUI5 Markdown Documentation (docsify)

     This is a shinier version of the markdown documentation with better search options powered by docsify - Made with ❤️. The contents of the raw version and the docsified version are the same.

3. You can make suggestions and improve the content. Please check our contribution guidelines.

4. Our documentation team will review your contributions. Accepted changes will be visible in the OpenUI5 Nightly Demo Kit shortly after we have implemented them. With the next OpenUI5 release, these changes will also become part of the official OpenUI5 documentation in the Demo Kit.

Contributions Welcome!

We invite you to improve our documentation. If you're interested, please check our contribution guidelines.

License

Copyright (c) 2024 SAP SE or an SAP affiliate company. All rights reserved. This file is licensed under the Creative Commons Attribution-ShareAlike 4.0 International Public License except as noted otherwise in the LICENSE file.

openui5-docs's Issues

Section 'Integration Testing with One Page Acceptance Tests (OPA5) -> Simulating User Interactions on Controls' contains not working code

Hi Team,

the page: https://openui5.hana.ondemand.com/#/topic/8615a0b9088645ae936dbb8bbce5d01d
contains the section Choosing an Item from sap.m.Select in this section there is the sentence Here's an example showing how to choose an item from sap.m.Select or sap.m.ComboBox. But with Combobox this approach does not work.

See following code to achieve the selecting of an item of a combobox:
/**

• Selects the suggestion item of a sap.m.Combobox with the text mParameters.value on the control with the mParameters.controlId
• @param {object} mParameters The parameters
• @param {string} mParameters.controlId The id of the control
• @param {any} [mParameters.fragmentId] If the control is placed inside a fragment, the id of the fragment
• @param {string} mParameters.viewName The viewName
• @param {any} mParameters.value If also the value of the control should be checked, this is the expected value
• @returns {jQuery.promise} The promise to wait until it is resolved
  */
  iSelectComboBoxItemWithText: function (mParameters) {
  return this.waitFor({
  id: mParameters.controlId,
  viewName: mParameters.viewName,
  fragmentId: mParameters.fragmentId,
  actions: new Press(),
  success: function (oControl) {
  return this.waitFor({
  controlType: "sap.m.StandardListItem",
  searchOpenDialogs: true,
  matchers: [new Ancestor(oControl), new Properties({
  title: mParameters.value
  })],
  actions: new Press(),
  success: function () {
  Opa5.assert.ok(true, "Selected the item with text: " + mParameters.value + " on the control with id: '" + mParameters.controlId + "'");
  },
  errorMessage: "The select item with text " + mParameters.value + " could not be pressed."
  });
  },
  errorMessage: "The combox item can not be selected."
  });
  }

Difference between index.md, index.json, etc

What is the difference between the files below?

• 0index.md
• index.md
• index.json

I added a new page in my fork on those but I could only see the new page after adding it to sidebar.md

Could you please explain the purpose of each file? Specially inside the CONTRIBUTING page?

Versioning of SAPUI5: updating code snippet

In the SAPUI5 version of the topic Versioning of SAPUI5, it's still mentioning the deprecated sap.ui.getVersionInfo.

To access the SAPUI5 version at runtime, you can use the following code:

var oPromise = sap.ui.getVersionInfo({ async: true });
oPromise.then( function(oVersionInfo) { 
var oVersion = jQuery.sap.Version(oVersionInfo.version);
});

Instead, it should be something like this:

sap.ui.require([
    "sap/ui/VersionInfo",
    "sap/base/util/Version"
], function(VersionInfo, VersionUtil) {
    VersionInfo.load().then(function(oCurrentVersionInfo) {
        var oVersionUtil = new VersionUtil(oCurrentVersionInfo.version);
        // ...
    });
});

Additionally, I believe the above snippet could be also beneficial for OpenUI5 to be mentioned in the topic, not just for SAPUI5, in order to make use of the sap/base/util/Version module in the runtime.

Dead API Links to ODataListBinding Methods

The documentation page Accessing Data in Controller Code links a to a couple of APIs pages that lead to a "The requested resource was not found." page.

Samples:

• https://ui5.sap.com/1.81.1/#/api/sap.ui.model.odata.v4.ODataListBinding.create
• https://ui5.sap.com/1.81.1/#/api/sap.ui.model.odata.v4.ODataListBinding.requestContexts
• https://ui5.sap.com/1.81.1/#/api/sap.ui.model.odata.v4.ODataModel.bindList

Missing Deprecation Info for sap.ui.layout.form.GridLayout

GridLayout is listed as layout option for the SimpleFormLayout without any note about its deprecation:
https://openui5.hana.ondemand.com/api/sap.ui.layout.form.SimpleFormLayout

Not clear how to properly add new pages in the documentation

After forking and serving the documentation using a http-server npm package and inspecting the files in the docs folder, I am having a hard to to understand the right way to add new pages in the documentation.

The files have some strange suffixes - First I thought it was a commit ID but I don't think so.

Also, each page has a "loio" which is also not clear.

What convention should I use when creating a new page?

Central topic to learn about rendering in UI5

It would be nice if there is a central place to learn about how renderings are done in UI5 (Especially for new developers with experience in popular frameworks).

1. General understanding

For newcomers and researchers:

• Basics: what does "rendering" mean in the first place in the context of UI5? (I feel people often confound "rendering" with the paint event of the browser)
• When, in which situation, or by which actions do controls get invalidated to rerender in UI5?
• When rerendering, how is the DOM update in UI5 realized? String-based? VDOM? Incremental DOM / in-place DOM patching / semantic rendering? Using a third-party lib like lit-HTML (e.g. in case of UI5 Web Components)? Or something else? How does it work?
  And: how does the current rendering approach differ from other popular concepts? Is the rendering engine itself tree-shakable? Lower memory consumption? Any performance or complexity analysis (Big O)? Does UI5 require diffing the DOM trees to detect changes? Or is the DOM manipulation done directly without diffing?
• What other concepts does UI5 provide to optimize DOM manipulation?
  Linking to other resources like Extended Change Detection, InvisibleRenderer.render, etc…

2. Implementing renderers

For advanced UI5 developers:

• Moving Renderer Methods and Multiple ways to specify a renderer to Writing a Control Renderer?
• How to migrate from the legacy string-based rendering to the new semantic rendering?
  • Since the rendering behavior has changed, control developers might need to double-check their handling of focus, scroll position, ResizeHandler or other event registration in onAfterRendering. Simply replacing the legacy (now-deprecated) APIs with the new ones might be insufficient since the existing element in DOM will be reused with apiVersion 2 or higher.
    Sample commit: SAP/openui5@6525fed
  • How to deal with foreign non-HTMLElements, such as SVGs? (SO question #75424952)
    Related talk by @akudev: Embedding 3rd-party widget as UI5 control [video]
• What else should control developers keep in mind besides the standard quality criteria and avoiding deprecated APIs?
  • @abstract controls should have renderer: null assigned. Otherwise, MyControlRenderer.js can be accidentally fetched in some cases, leading to a 404 error. Abstract controls don't have renderers by definition.
    Sample commit: SAP/openui5@50da9ee
  • When instantiating some text-containing controls internally, either ManagedObject.escapeSettingsValue in the constructor settings object (since v1.52) or the mutator (e.g. setText) after the control instantiation should be used.
    Sample issues and fixes: https://github.com/SAP/openui5/issues?q=is%3Aissue+curly+escapeSettingsValue
  • When using RenderManager#icon, the renderer module for the control should require sap/ui/core/IconPool in order to avoid synchronous loading of the dependency.
    Sample commit: SAP/openui5@7dddccd
  • For inner elements, too, start with openStart and provide an ID as a 2nd argument (control.getId() + "-myInnerEl") instead of using attr("id", "...") so that the Patcher can reuse the existing DOM elements again when rerendering.
    Sample commit: SAP/openui5@3756b0e
  • Neither rerender nor invalidate is designed to be overwritten by controls, that intend to further manipulate the DOM there, which should be avoided in favor of onAfterRendering. Controls should not rely on rerender being called anyway since SAP/openui5@378b598.
  • Collection of available interfaces, mixins, and other stuff which control developers must incorporate in certain cases in order to align with the framework specification and behaviors.
  • …

Motivation

Currently, it's easy for new developers to get lost when trying to understand the above mentioned points. When going through the documentation:

• Information about rendering seems scattered in different topics.

• Code snippets in some topics still use the deprecated rendering APIs (write*(), add*(), …)
  Some use the new semantic rendering APIs (openStart(), class(), attr(), …)
  For beginners, it's not clear which one is new and which one is old.

• Code snippets with inconsistent renderer assignments:

  • renderer: { render: <fn> } (should include at least apiVersion: 2 or higher to enable the DOM-patching)
  • renderer: <fn> (should be avoided: #33)
  • renderer: "sap.m.SomeRenderer"
  • renderer: MyRequiredRenderer (Current best-practice AFAIK. Cf. SAP/openui5@ad5bc4e and SAP/openui5@f0fa93f)

• Code snippets with inconsistent renderer definitions:

  • In the control definition itself at renderer
  • A separate renderer module (e.g. MyControlRenderer.js)
    • Returning a plain object with bExport true (Not intended to be used for non-SAP developers)
    • Returning Renderer.extend(/*…*/); whereas Renderer is required from sap/ui/core/Renderer (Current best-practice AFAIK)

• One or two topics that explain all the above points would help people to grasp rendering in UI5 quickly. Additionally, the Best Practices for Developers section "Control rendering" should be also enhanced afterwards.

sap.m.Tokenizer Calculations based on desity mode incorrect

Hi Support Team,
I've got issues: The first part of some F4 fields is cut/not displayed completely --> When F4 fields have only 1 token

After multiple testing and deployment, it is determined that a certain change in the sapui5 library in version 1.94 is the cause of the issue, testing has been done and detected that the issue won’t happen if we use any sapui5 version between 1.90 and 1.93.

Please help me check this issue

Syntax inconsistencies in "Enabling Responsive Padding"

The topic Enabling Responsive Padding contains some syntax inconsistencies.

• Some class names are using em dash (—) instead of double hyphens (--) as a delimiter.
• According to SAP/openui5@d051788, sapM-Std-Padding* is renamed to sapUi-Std-Padding*

Double `#` in the URL on a link on `https://sdk.openui5.org/nightly`

If we check the description of sap.ui.core.Core.byId, we find out that this method is deprecated:

Deprecated as of version 1.119. Please use Element.getElementById instead.

We click on a proposed link and everything is OK.

However, in case of
https://sdk.openui5.org/nightly/#/api/sap.ui.core.Core%23methods/byId, the proposed link contains an extra #: https://sdk.openui5.org/nightly/#/#api/sap.ui.core.Element%23methods/sap.ui.core.Element.getElementById, and this link is wrong, leading to the error:

The requested resource was not found.

The correct link is:

https://sdk.openui5.org/nightly/#/api/sap.ui.core.Element%23methods/sap.ui.core.Element.getElementById

"Dates, Times, Timestamps, and Time Zones": missing sub header for JSONModel ↔ ODataModel

The content of the new topic "Dates, Times, Timestamps and Time Zones" is really top-notch and I believe it will be very helpful for application developers and customers understanding and learning best practices.

One thing I noticed is that the section "Best Practices" has several subsections for each one of the cases expectedly, except for the case regarding the JSON model ↔ OData model.

Current

### Best Practices

...

JSON models can also be used if the data is stored in the JSON model in the same way as in the corresponding OData model. [...]

Expected

It would be nice if the JSON model ↔ OData model case could also get a heading like the other subsections in within the "Best Practices" section. For example:

### Best Practices

...

#### sap.m.DatePicker with Edm.Date or Edm.DateTime (OK)

...

#### sap.m.TimePicker with Edm.TimeOfDay or Edm.Time (OK)

...

#### sap.m.DateTimePicker with Edm.DateTimeOffset (OK)

...

#### sap.m.DateRangeSelection with Edm.Date or Edm.DateTime (OK)

...

#### <Header for JSONModel ↔ ODataModel> (← missing)

JSON models can also be used if the data is stored in the JSON model in the same way as in the corresponding OData model. [...]
...

Alternatively (See @uhlmannm's reply below)

In my view, explaining how to "transfer" data between JSONModel ↔ ODataModel is questionable since the case doesn't really reflect current best practices but rather encourages anti-patterns such as requesting a large amount of entities via v2.ODataModel#read, storing the response in a JSONModel, then surgically manipulating the data manually instead of working with OData bindings.

The JSONModel ↔ ODataModel case should be removed completely.

`/sap.ui5/commands/shortcuts` description insufficient

In the topic Descriptor for Applications, Components, and Libraries section sap.ui5/commands, it says

Specifies provided commands with a unique key/alias. Contains:

• shortcut: String that describes a key combination. When the user presses the key combination, the command is triggered.

Unfortunately it is not enough to understand how it can be achieved exactly.

• Is the shortcut value space-sensitive or case-sensitive? (Yes and no, according to the current source code)
• Are single key commands allowed? (Yes, according to the source code)
• Are commands freely definable or is there a limited set of allowed commands?
  • List of already defined shortcuts categorized by UI5 controls: https://help.sap.com/docs/SAPUI5/bc5a64aac808463baa95b4230f221716/144d377d68784689a9b21565dfa14065.html
  • List of already defined shortcuts by SAP Fiori elements: https://github.com/SAP-docs/sapui5/blob/main/docs/06_SAP_Fiori_Elements/keyboard-shortcuts-0cd318c.md which states the following restrictions:

    • Don't use a keyboard shortcut for a custom button that is already defined as a standard shortcut by SAP Fiori elements. This results in unexpected behavior.

    • Keyboard shortcuts aren't supported for application-defined inline actions and inline navigation buttons in tables.

  • Current valid and list of disallowed shortcuts visible in the source code: sap/ui/core/util/ShortcutHelper.js
• Other limitations?
  • Document: adding <core:CommandExecution command="MyCommand"/> requires "MyCommand": { "shortcut": "..." } to exist in manifest.json. Otherwise, this will lead to the following error which prevents the app from being cleaned up:

    TypeError: Cannot read properties of null (reading 'shortcut')

    Fix: #90
  • Document: focus-independent or focus-less command execution is not allowed either (Cf. SAP/openui5#2788).
  • ...
• Brief documentation regarding the popup opened by the sap.ui.core.ShortcutHintsMixin and how the popup's behavior differs from the native tooltip. → There are cases where the native tooltip and the shortcut popup are both shown at the same time. According to some users, it's confusing since the popup and the native tooltip don't differ much in visual design (depending on the OS).

A link pointing to a dedicated topic would be nice so that readers can learn more if they intend to implement commands.

"OData-based: Requires manual modifications" not meaningful in OpenUI5

In Tables: Which One Should I Choose?, it says:

Feature Supported?	Responsive Table (sap.m.Table)	Grid Table (sap.ui.table.Table)	Analytical Table (sap.ui.table.AnalyticalTable)	Tree Table (sap.ui.table.TreeTable)
OData-based	Requires manual modifications	Requires manual modifications	Requires manual modifications	Requires manual modifications

What does "Requires manual modifications" exactly mean? What does "OData-based" mean in the first place?

Without the context of SmartTable concept, which is available only in SAPUI5, the above mentioned row is somewhat perplexing for OpenUI5 users. IMHO, that row can be removed / hidden in OpenUI5.

Assigning function directly to "renderer" should no longer be encouraged

Specifying the renderer without apiVersion: 2 (e.g. renderer: <fn>) causes falling back to the legacy string-based rendering even with semantic rendering APIs, i.e. no DOM-patching can be performed.

And according to SAP/openui5#2822, there won't be any implicit setting of the flag either.

Topics that mention renderer: <fn> should be all updated; informing that renderer: <fn> should no longer be used and that apiVersion: 2 should be explicitly set. E.g.:

renderer: function(oRM, oControl) {/*...*/}

renderer: {
  apiVersion: 2,
  render: function(oRM, oControl) {
    // ...
  }
}

Walkthrough's "Step 19: Reuse Dialogs" is now missing on https://openui5nightly.hana.ondemand.com

I've just paid attention that the Walkthrough's Step 19: Reuse Dialogs has been removed from the https://openui5nightly.hana.ondemand.com.

The Walkthrough on the stable version is a 38 steps manual, while the nightly version contains only 37 steps.

https://openui5nightly.hana.ondemand.com/topic/19453962b8074b7399372c65cbe05370 returns «Not found The requested resource was not found».

What's the reason of removing this step? Code reuse sounds quite critical for any framework.
It's interesting to get some details.

Contradicting guidelines about default aggregation in XML views/ fragments

In Keep Your Views Short and Simple, there is the suggestion to remove default aggregation tags:

Remove Clutter From Your Views

It's easy to save a few bytes and make your code a lot cleaner:

• Don't define properties that are set to their default values.
• Remove unused namespace aliases.
• Omit the content or items tag for controls that define default aggregations.
• Use self-closing XML tags for controls that don't define any aggregations.

On the other hand, the Walkthrough Step 11 says the following:

Conventions

• Do not make implicit use of default aggregations but always declare the aggregation names explicitly in the view. In the example above, the content aggregation could also be omitted as the Panel control declares it as a default, but it makes the view harder to read.

Would be nice if this contradiction could be addressed internally.

I personally agree with the 1st guideline; omitting default aggregation tags not only reduces the file size, it actually improves readability by reducing levels of indentation. Additionally, the 2nd guideline defies the whole purpose of defaultAggregation in control metadata.

Broken link to `sap.ui.mdc.sample.Field`

Looking for samples of valueHelp property:

I've got a result

sap.ui.mdc.sample.Field (samples):MDC...

with a link to https://openui5nightly.hana.ondemand.com/entity/sap.ui.mdc.sample.Field which is actually broken and returns:

The requested resource was not found.

OpenUI5: "1.96.0-SNAPSHOT (built at 2021/10/13 00:03h)"

Rendering of page broken since 1.98.0

Hi there,

the page Variant for Bootstrapping from Content Delivery Network is broken since 1.98.0.
Perhaps other pages are also affected, only here I noticed it.
https://openui5.hana.ondemand.com/1.98.0/#/topic/2d3eb2f322ea4a82983c1c62a33ec4ae

Still works in 1.97.0:
https://openui5.hana.ondemand.com/1.97.0/#/topic/2d3eb2f322ea4a82983c1c62a33ec4ae

Section "Common mistakes"

After reviewing many UI5 question in Stack Overflow, I believe most of the questions fall in one of the following buckets:

1. Lack of concepts like properties, aggregations and data binding
2. Do my job
3. Web IDE / SAP Gateway / oData questions
4. Very specific requirements which are hard to replicate
5. Annotation specific

---

I believe a section for "Common mistakes" could be beneficial. Maybe inside section "Coding Issues to Avoid"

What do you think about it?

Controller Code for Sample Input Checked does not work

This issue is moved from SAP-docs repository
Hi,

the sample for Input - Checked (https://ui5.sap.com/#/entity/sap.m.Input/sample/sap.m.sample.InputChecked) does not work.

In the Controller code https://ui5.sap.com/#/entity/sap.m.Input/sample/sap.m.sample.InputChecked/code/C.controller.js the function _validateInput needs to be corrected from:

_validateInput: function (oInput) {
	var sValueState = "None";
	var bValidationError = false;
	var oBinding = oInput.getBinding("value");

	try {
		oBinding.getType().validateValue(oInput.getValue());
	} catch (oException) {
		sValueState = "Error";
		bValidationError = true;
	}

	oInput.setValueState(sValueState);

	return bValidationError;
},

to:

_validateInput: function (oInput) {
	var sValueState = "None";
	var bValidationError = false;
	var oBindingInfo = oInput.getBindingInfo("value");

	try {
		oBindingInfo.type.validateValue(oInput.getValue());
	} catch (oException) {
		sValueState = "Error";
		bValidationError = true;
	}

	oInput.setValueState(sValueState);

	return bValidationError;
},

Kind regards,
Sebastian

Contradicting sentences about `core:require` in Fragments

In the end of the topic Require Modules in XML View and Fragment, it says the following:

core:require can be used in fragments and set on every element, including FragmentDefinition.

But then, it continues:

When a view with a fragment is preprocessed, the FragmentDefinition node is not part of the resulting view and this is why core:require on FragmentDefinition does not work as expected. Therefore, core:require works on all elements in fragment other than the FragmentDefinition node when the view which contains the fragment is preprocessed.

I think the latter text is not valid anymore since it's possible to make use of core:require in the FragmentDefinition node: https://jsbin.com/luzekib/edit?js,output

Step 27: Unit Test with QUnit

Walkthrough step 27 producing error:
Message: Diff suppressed as the expected and actual results have an equivalent serialization
TypeError: this.getOwnerComponent is not a function

Click link "You can view and download all files" which is served by openui5.org: https://sdk.openui5.org/entity/sap.m.tutorial.walkthrough/sample/sap.m.tutorial.walkthrough.27
the same error is observed.

Documentation consistency: `sap/ui/VersionInfo` vs. `sap.ui.Device`

A consistency issue: for the namespace sap/ui/VersionInfo slashes are used to separate the packages, while for other components dots are used instead, e.g.: sap/ui/VersionInfo vs. sap.ui.Device.

BTW, what's the difference between slashes and dots in the components' name?

is reference to SAP Web IDE required?

As far as I understand, Web IDE requires you to buy license for productive usage https://launchpad.support.sap.com/#/notes/0002554932
Supposedly, this guide is written for developers who want to try free of charge ui library from SAP. It would be fair to at least mention the license costs of SAP Web IDE or better mention the free of charge alternative

Link to UI Theme Designer disabled

On the "Tools" Tab there used to be a Link to the UI Theme designer, which no longer seems to be there.

If this is not an issue but intentional would it be possible to let me know why?

No mention of `sap.ui.Global` in the API reference

In the JavaScript Code Issues is written:

Commonly used names (However they can also be used as AMD references via sap/ui/Global)

However, when I try to check an API reference of sap/ui/Global or sap.ui.Global, I get «Not found».

Step 27. of the Walkthrough: Update webapp/localService/metadata.xml file

Hello,
The webapp/localService/metadata.xml file doesn't describe the "status" property that is used througout that step.
Would you add it?

This has been reported on the OpenUI5 repo: SAP/openui5#2992

Regards,
Georgi