Skip to content

Latest commit

 

History

History
474 lines (319 loc) · 13.5 KB

Stable_IDs_All_You_Need_to_Know_f51dbb7.md

File metadata and controls

474 lines (319 loc) · 13.5 KB
loio
f51dbb78e7d5448e838cdc04bdf65403

view on: demo kit nightly build | demo kit latest release

Stable IDs: All You Need to Know

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.

Background

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="sap.m"
	xmlns:mvc="sap.ui.core.mvc">
	<Page>
		<content>
			<Table>
			</Table>
		</content>
	</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 visible property to false.

How to Set IDs Manually to Keep Them Stable

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 descriptor for applications, components, and libraries

    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 and Manifest (Descriptor for Applications, Components, and Libraries).

    Example:

    {
"sap.ui5": {
	"rootView": {
		"viewName": "<your namespace>.view.Root",
		"id" : "rootView",
		"async": true,
		"type": "XML"
	}
	...
	"routing": {
		...
		"targets": {
			"myTarget": {
				"type": "View",
				"viewType": "XML",
				"name": "MyView",
				"id": "myView"
				}
			}
		}
	}
}

  • Embedded views

    If you embed your view, set its ID (such as myEmbeddedView).

    Example:

    <mvc:View xmlns="sap.m"
	xmlns:mvc="sap.ui.core.mvc">
	<Page id="page">
		<mvc:XMLView id="myEmbeddedView" viewName="MyView" async="true" />
	</Page>
</mvc:View>

  • Programmatic creation

    If you create the view programmatically, provide the ID as one of the parameters to the constructor or factory function. Make sure to prefix the view ID with the component ID using the createId method of the owner component.

    Example:

    // "XMLView" required from module "sap/ui/core/mvc/XMLView"
XMLView.create({
	id: <component>.createId("myProgrammaticView"),
	viewName : "<your namespace>.view.ProgrammaticView"
}).then(function(oView){
	// code
});

    For more information, see namespace sap.ui.

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.

    If the following XML view is instantiated using the ID myView, the contained page and table would have the IDs myView--page and myView--table at runtime:

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

  • Programmatic creation

    For JavaScript views and JavaScript-generated controls you must use the createID method of the view or component. Here's how it could look like when you're creating a control directly in the control code:

    // "Button" required from module "sap/m/Button"
new Button({
	id : oView.createId("ConfirmButton"),
	text : "Confirm"
});

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.

For example, if you instantiate a component inside an HTML page, set the ID of the component as shown below. The reason for this is that components could be displayed more than once on a page. 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. As described above, for the programmatically generated components, you must do it yourself.

Example:

// "Shell" required from module "sap/m/Shell"
new Shell({
   app: new ComponentContainer({
      height : "100%",
      name : "sap.ui.demo.worklist",
      settings: {
         id: "worklist"
      }
   })
}).placeAt("content");

Note:

Only if there's more than one component in an app, the component container requires a stable ID by setting the component container to autoPrefixId. For more information, see sap.ui.core.ComponentContainer.

Embedded Components

If you want to add an embedded component with a stable ID, you have two options:

  1. Option: Add a component re-use entry in the application component's manifest.json. Let's say you want to add an embedded component with the name embeddedComponent.name. You define it as follows in the application component's manifest.json file:

    "sap.ui5": {
   "componentUsages": {
      "reuseName": {
         "name": "embeddedComponent.name",
         "settings": {
            "id": "embeddedComponentID"
         }
      }
   }
}

    Now you can use the re-use entry name defining the component container in XML:

    <core:ComponentContainer
   usage="reuseName"
   async="true"
   id="embeddedComponentContainerID"
   propagateModel="true" //to propagate models from the application component
/>

  2. Option: Add an embedded component independently from the manifest and mention the correct namespace using the name property. Also, when instantiating the component, make sure that the id property is set during component instance creation:

    <core:ComponentContainer
   name = "embeddedComponent.name"
   async="true"
   id="embeddedComponentContainerID"
   propagateModel="true" //to propagate models from the application component
/>

    Inside the embedded component's constructor() (with the embeddedComponent.name namespace) add :

    [...]
constructor: function() {
    arguments[0].id = "embeddedComponentID";
    UIComponent.prototype.contructor.apply(this, arguments);
}
[...]

    Alternatively, you could use sap.ui.core.Component.create() and specify the id property as part of the arguments. For more information, see the API Reference: sap.ui.core.Component/methods/sap.ui.core.Component.create.

Note:

In order to support SAPUI5 flexibility features, all embedded components should have a stable ID.

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 loadFragment function on your sap.ui.core.mvc.Controller instance.

Example using the controller function loadFragment:

// "this" is the controller instance
this.loadFragment({
	// note: no ID prefix needed
	name: "my.fragment.SampleFragment"
});

Example using the generic function sap.ui.core.Fragment.load:

// "Fragment" required from module "sap/ui/core/Fragment"
// "this" is the controller instance
Fragment.load({
	// note: ID prefix needed
	id: this.getView().getId(),
	name: "my.fragment.SampleFragment"
});

How to Name Stable IDs

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 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 a component called 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

How to Check If All Your IDs Are Stable

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:

  1. Open your app in a browser.
  2. Enter the shortcut [Ctrl] + [Shift] + [Alt] /[Option] + [P] to start the Support Assistant.
  3. In the Technical Information Dialog, choose Activate Support Assistant.
  4. In the table on the left, deselect all rules.
  5. Click on the Rules column.
  6. Filter for stable and choose Enter.
  7. Select the Stable control IDs are required for SAPUI5 flexibility services rule.
  8. Choose Analyze.

If any generated IDs are found, set the IDs for these controls manually as described here.

Related Information

Support Assistant