Configuring and Instantiating Components

Components are independent and reusable parts used in SAPUI5 applications. They facilitate the encapsulation of closely related parts of an application. This makes the structure of an application and its code easier to understand and to maintain.

SAPUI5 provides the following two types of components:

• Faceless components (class: sap.ui.core.Component)

  Faceless components have no user interface and are used for coding when no UI elements are needed, such as for a service that provides data from a back-end system.

• UI components (class: sap.ui.core.UIComponent)

  UI components extend faceless components and add rendering functionality to the component. They represent a screen area or element on the UI along with the respective settings and metadata. This component type will be covered in the course.

A component has a component controller (Component.js) and a descriptor (manifest.json). Only the component controller is mandatory, but it is recommended to also use the descriptor file. The descriptor then contains the component metadata, and also expresses the component dependencies and configuration (see below).

All required and optional resources of a component are organized in a unique namespace. The namespace of the component equals the component name.

Optional resources of a component are, for example, CSS, js, or i18n files, views, and controllers.

The figure, Structure of a Component, gives an example of the folder structure of a component.

The descriptor provides a central, machine-readable, and easy-to-access location for storing metadata associated with a component.

The data of the descriptor is stored in JSON format in the manifest.json file.

The existence of the manifest.json file must be declared in the metadata defined in the Component.js file (see below). The declaration in the component metadata makes the component load the manifest.json file and read the relevant entries for SAPUI5.

The content of the descriptor is structured using namespaces, amongst others, the sap.app, sap.ui, and sap.ui5 namespaces (see the figure Structure of the Descriptor):

• The sap.app namespace provides application-specific attributes.
• The sap.ui namespace provides UI-specific attributes.
• The sap.ui5 namespace provides SAPUI5-specific attributes.

Each new SAPUI5 version implies a new version of the descriptor. This descriptor format version is described by the value of the mandatory _version property at root level of the descriptor (see the figure Structure of the Descriptor). How the value of this property is exactly related to the SAPUI5 version, and the descriptor version can be found in the documentation.

The figure, sap.app Namespace, shows some attributes from the sap.app namespace. A complete listing of all attributes can be found in the documentation.

The id attribute is a mandatory attribute that must be provided in dot notation and specifies a unique Id for the project. It must match the namespace provided in the corresponding Component.js file.

If the component controller is created there, for example, via

1
UIComponent.extend("sap.training.exc.Component", { . . . });

the id attribute must have the value sap.training.exc.

The title and description of the project are maintained using the title and description attributes of the sap.app namespace. To make the attribute values language dependent, a key value is specified in double curly braces: {{key}}

The specified keys are maintained in a file with the extension .properties. The i18n attribute can then be used to specify the URL to this file. The URL is interpreted relative to the manifest.json file. The way in which the maintained texts can be made available in other languages will be discussed later in the course.

The texts referenced in the descriptor for title and description can be read by the SAP Fiori launchpad, for example.

The figure, sap.ui5 Namespace, shows some attributes from the sap.ui5 namespace.

The dependencies attribute contains the external dependencies to libraries and components that are loaded by the SAPUI5 core during the initialization phase of the component. Everything referenced here can be used directly in the component's code.

The libs property contains the libraries that the SAPUI5 core should load for use in the component. In the example, among others, the sap.ui.core and the sap.m library are loaded initially.

The minUI5Version property specifies the minimum SAPUI5 version that the component requires. Since SAPUI5 does not currently enforce the use of the correct version, minUI5Version is used for informational purposes only. If the minimum SAPUI5 version criterion is not met, a warning is issued in the console log.

The rootView attribute specifies the root view to open. The value of this attribute can be the view name as a string for XML views, or the view configuration object with viewName for the view name and type for the view type, id, async and other properties of sap.ui.core.mvc.View.

In the example shown, the XML view with the module name sap.training.exc.view.App is set as the root view of the component. It is loaded asynchronously via the module system and has the id App. This means that when the component is instantiated and embedded in the UI, the App view is automatically displayed as the initial view.

To render UI components, you must wrap them in a sap/ui/core/ComponentContainer. You cannot use the placeAt method to place UI components directly in a page.

The component container separates the application and the nested component. It is an SAPUI5 control that can be nested at any place within the SAPUI5 control tree.

To load and create a UI component, you can use the following options:

• Create a new component instance asynchronously before creating the container using the create method of sap.ui.core.Component. The separately created component instance can then be passed to the constructor of sap.ui.core.ComponentContainer.
• Create a new component instance asynchronously when creating the container using the constructor of sap.ui.core.ComponentContainer (see the following example).

In the figure, Creating a Component Instance, a component instance is instantiated together with the component container. For this reason, the module in which instantiation takes place is dependent on sap/ui/core/ComponentContainer. The constructor of ComponentContainer is passed a settings object with the following properties:

• id

  This property is used to pass the Id for the component container instance to be created.

• name

  The name property contains the name of the component to be instantiated.

• manifest

  Via manifest: true the so called "manifest first" function is used. This allows SAPUI5 to load and evaluate the manifest.json descriptor before the component controller. This is recommended because it improves the performance of the initial load. The loading process can be parallelized and optimized this way. After the descriptor is loaded, the component factory can load the dependencies (SAPUI5 libraries and other dependent components) in parallel with the component preload.

• async

  async: true is used to specify that the component should be created asynchronously.

• settings

  The settings object is passed to the component instance when it is created. In the example, it is used to set the component instance Id.

After the component container is created, the placeAt method is called on it to add it to a UI area.