Stable IDs: What? When? Why?

Stable IDs are IDs that you set yourself as opposed to IDs that are generated by SAPUI5.

Why Do I Need to Set IDs?

By default SAPUI5 generates IDs for instantiated controls. E.g. the page and the table in this XML view could have the IDs __view0--__page0 and __view0--__table0 at runtime.

<mvc:View
   xmlns="sap.m"
   xmlns:mvc="sap.ui.core.mvc">
   <Page>
      <content>
         <Table>
         </Table>
      </content>
   </Page>
</mvc:View>

These generated IDs change whenever the application’s control structure changes. This can cause problems to other functions when being used against your app:

SAPUI5 Flexibility Services allow you to extend your apps based on your requirements, for example, by creating your own variants or adapting the user interface at runtime. Stable IDs are used to identify the controls that are to be adapted.
Automated tests check the behavior of the application at runtime. To do this, they find controls on a runtime screen by searching for stable IDs. The amount of stable IDs required depends on the chosen framework. If you use OPA in SAPUI5, you'll be 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 display application help directly in the application and might also depend on stable IDs.

The solution for this is that application developers must set the IDs manually. For example, the page and the table in the following XML view would have the ID myView--page and myView--table at runtime.

<mvc:View
   id="myView"
   xmlns="sap.m"
   xmlns:mvc="sap.ui.core.mvc">
   <Page id="page">
      <content>
         <Table id="table">
         </Table>
      </content>
   </Page>
</mvc:View>

The XML view prefixes the control IDs with its own ID. This allows you to use the same control ID on different views and to use the same view multiple times. For more information about this, see Support for Unique IDs (Note: In the case of JavaScript views, the view's createID method needs to be used for this purpose).

Caution

After a software upgrade, if some of the controls have disappeared or the way in which they can be identified has changed, this will have a direct impact on functions such as SAPUI5 flexibility services, automated tests and inline help tools as outlined above. For this reason, these IDs must be kept stable over the lifecycle of the application. They are part of the public API of the application.

When Used with Routing

Ideally, you create your views with routing targets and declare the view ID in the manifest instead of setting it yourself in the view. For more information, see Routing and Navigation and Descriptor for Applications, Components, and Libraries.

{
   "sap.ui5": {
      "routing": {
         "targets": {
            "myTarget": {
               "viewName": "MyView",
               "viewId": "myView"
            }
         }
      }
   }
}

When Used with Multiple Applications

When running multiple applications in a single html page, the stable ID needs to be included in the application ID, which can be achieved by setting the component’s ID. This is done automatically if the app is running in SAP Fiori launchpad. For details of how to set the ID if the app is not running in SAP Fiori launchpad, see Handling IDs in UI Components.

Not Possible for Bound Aggregations

Because it's not actually possible to have stable IDs for controls in bound aggregations, you do not set IDs for such controls. For instance, the items in the table below are generated along the bound data and therefore cannot have stable IDs:

<mvc:View
   id="myview"
   xmlns="sap.m"
   xmlns:mvc="sap.ui.core.mvc">
   <Table
      id="table"
      items="{/ProductCollection}">
      <items>
         <!-- no ID is set for controls in the bound 'items' aggregation -->
         <ColumnListItem/>
            …
         </ColumnListItem>
      </items>
   </Table>
</mvc:View>

When Not to Set Stable IDs

Only set IDs on those controls that you want to be used by other functions like SAPUI5 flexibility services, automated tests or inline help tools . For instance, the layout control in the sample below could be assumed as not relevant:

<mvc:View
   xmlns="sap.m"
   xmlns:layout="sap.ui.layout"
   xmlns:mvc="sap.ui.core.mvc">
   <Page id="page">
      <content>
         <!-- no ID is set for this layout control -->
         <layout:HorizontalLayout>
            <Image src="..." id="firstImage"/>
            <Image src="..." id="secondImage"/>
         </layout:HorizontalLayout>
      </content>
   </Page>
</mvc:View>

Admittedly it's not always easy to decide if a stable ID is required. The best solution may therefore be to set IDs on each and every control, but remember you'll have to keep every one of those IDs stable.

How to Name Stable IDs

When giving names to stable IDs, choose IDs that describe the semantics of your views and controls. For example, if you're building an app using the Worklist Template, the following IDs are generated:

myProducts--worklist--page
myProducts--worklist--table
myProducts--product--page
myProducts--product--objectHeader