Stable IDs are IDs for controls, elements, or components that you set yourself in the respective id property or attribute as opposed to IDs that are generated by OpenUI5. Stable means that the IDs are concatenated with the application component ID and do not have any auto-generated parts.
If you don’t define IDs, OpenUI5 generates them dynamically. These IDs are not static and might differ from program run to program run. For example, the page and table in the following XML view could have the generated IDs "__page0" and "__table0" at runtime:
<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m">
<Page>
<Table>
</Table>
</Page>
</mvc:View>
The generated IDs change whenever the control structure of the app changes. The sequence of instantiation also plays a role: If there are two views with unstable IDs in the app, depending on the order the views are opened, they get the generated IDs "__view0" and "__view1". This is an issue for the following features that require stable IDs:
Automated tests
To check the behavior of apps at runtime, these tests find controls by searching for stable IDs. If you use OPA in OpenUI5, you’re able to find controls via other criteria like control type, display name and others. For more information, see Integration Testing with One Page Acceptance Tests (OPA5).
Inline help tools
These tools display user assistance information directly in the app and depend on stable IDs (example: SAP Companion).
Tip:
Stable IDs are an important prerequisite for SAPUI5 flexibility services, automated testing, and inline help tools. Apps with stable IDs are of high quality and offer customers more functionality. Therefore, we strongly recommend that you use stable IDs whenever possible (some technical controls don’t need stable IDs, such as
CustomData).
Caution:
If some controls have disappeared after a software upgrade or the way in which they can be identified has been changed, this has a direct impact on the functions that depend on stable IDs. These stable IDs are part of the public API of the app, and therefore must be kept stable over the life cycle of the app.
Do not delete any control that has a stable ID. If you need to remove a control from an app, set the control’s
visibleproperty tofalse.
Tip:
Using the rule Stable control IDs are required for SAPUI5 flexibility services in the Support Assistant, you can check whether all controls use stable IDs. For more information, see How to Check If All Your IDs Are Stable.
| **Views** |
- Views in the manifest
The standard use case is that you use stable IDs for the view that the router navigates to. Ideally, instead of creating the views yourself, you create them with routing targets and declare the view ID in the manifest.json file as shown in the example below. For more information, see [Routing and Navigation](/docs/04_Essentials/routing-and-navigation-3d18f20.html) and [Manifest \(Descriptor for Applications, Components, and Libraries\)](/docs/04_Essentials/manifest-descriptor-for-applications-components-and-libraries-be0cf40.html).
Example:
```json
"sap.ui5": {
"rootView": {
"id": "myRootView",
"viewName": "my.app.view.Root",
"...": "..."
},
"routing": {
"targets": {
"myTarget": {
"id": "myView",
"name": "MyView",
"...": "..."
}
}
}
}
```
- Embedded views
If you embed your view, set its ID.
Example:
```xml
|
| **Extension points** | If you use extension points, use stable IDs for nested views and prefixes for nested controls of a fragment. |
| **Controls** |
- Controls in XML views
The XML view prefixes the control IDs \(only the defined IDs, not the automatically created ones\) with its own ID. This allows you to use the same control ID for different views and the same view multiple times. For more information, see [Support for Unique IDs](/docs/04_Essentials/support-for-unique-ids-91f28be.html).
If the following XML view is instantiated using the ID `"myView"`, the contained page and table would have the IDs `"myView--myPage"` and `"myView--myTable"` at runtime:
```xml
|
| **Components** | > ### Note: > The following is only relevant if you do not use the SAP Fiori launchpad because it instantiates components for you and provides IDs. If you instantiate a component inside an HTML page, set the ID of the component as shown below. To get unique IDs for the views and controls inside the component, they must be prefixed with the component ID. All views in the component that are created by the framework are automatically prefixed with the component ID. Examples \(Standalone App scenario\): ```html ``` For more information, see [`sap/ui/core/ComponentSupport`](https://ui5.sap.com/#/api/module:sap/ui/core/ComponentSupport). Alternatively, when creating a `ComponentContainer` manually: ```js // ComponentContainer required from "sap/ui/core/ComponentContainer" new ComponentContainer({ id: "myRootAppComponentContainer", autoPrefixId: true, name: "my.app", manifest: true, settings: { // Component settings id: "myRootAppComponent" }, height: "100%" }).placeAt("content"); ``` |
| **Embedded Components** |
Let's say you want to embed a component with the package name `my.embedded`. You define it as follows in the manifest and use the registered `componentUsages` entry in `ComponentContainer` settings, for example.
```json
"sap.ui5": {
"componentUsages": {
"myReuseComponent": {
"name": "my.embedded",
"lazy": false
}
}
}
```
> ### Note:
> While the `componentUsages` configuration technically allows defining a component ID via `settings: { id: "..." }` directly in manifest.json, doing so can lead to ID conflicts at runtime when the framework instantiates the target `Component` **more than once** through the same `componentUsages` configuration. To avoid this, the component `id` can be specified in the [`Component#createComponent`](https://ui5.sap.com/#/api/sap.ui.core.Component%23methods/createComponent) call or within the `settings` property of the `ComponentContainer`, as shown below.
```xml
|
| **XML fragments** |
If you use XML fragments in your app, make sure they are instantiated with the correct view ID prefix. To simplify this, you can use the [`sap/ui/core/mvc/Controller.loadFragment`](https://ui5.sap.com/#/api/sap.ui.core.mvc.Controller%23methods/loadFragment) API.
Example using the controller function `loadFragment`:
```js
// this == Controller instance
this.loadFragment({
// id: view ID as prefix by default
name: "my.app.view.SampleFragment"
});
```
Alternatively, when using the generic function `sap/ui/core/Fragment.load` manually:
```js
// Fragment required from sap/ui/core/Fragment
// this == Controller instance
this.getOwnerComponent().runAsOwner(() => Fragment.load({
id: this.getView().getId(), // view ID as prefix needed
name: "my.app.view.SampleFragment",
controller: this
})).then((createdFragment) => {
// ...
});
```
You can also define individual IDs \(and prefixes\) for each instance of a fragment.
```js
// Here we deactivate the default prefixing and pass a custom ID for the fragment instance
this.loadFragment({
id: this.createId("myFragment1"),
autoPrefixId: false,
name: "my.app.view.SampleFragment"
});
// or via generic factory:
this.getOwnerComponent().runAsOwner(() => Fragment.load({
id: this.createId("myFragment1"),
name: "my.app.view.SampleFragment",
controller: this
})).then((createdFragment) => {
// ...
});
```
```xml
|
Choose names for your stable IDs that describe the semantics of your views and controls, such as page or table.
Note:
For the allowed sequence of characters, see the namespace
sap.ui.core.ID. But bear in mind not to use hyphens (-) as separators in your names as they would interfere with the ones that are added automatically by the framework.
Example:
Let’s say you’re building an app with the component ID "myProducts". You’re using stable IDs for the views and contained views. Here’s what the concatenated IDs that are generated at runtime look like:
| Component | Views | Contained Views | Concatenated IDs |
|---|---|---|---|
| `"myProducts"` | `"worklist"` | `"page"` | `"myProducts---worklist--page"` |
| `"table"` | `"myProducts---worklist--table"` | ||
| `"product"` | `"page"` | `"myProducts---product--page"` | |
| `objectHeader` | `"myProducts---product--objectHeader"` |
With the Support Assistant, you can analyze whether there are any issues with the stable IDs used in your app. Here’s how you can check this:
stable and choose Enter.If any generated IDs are found, set the IDs for these controls manually as described here.
Related Information