This repository contains code samples that illustrate how to write a VC UI Extension. It also includes a mock runtime to test VC UI Extensions locally without having the need to build and deploy an archive.
The Advanced Variant Configuration UI displays Characteristics in a responsive Grid. Initially 30 Characterics are shown. If more are available, a 'See more' button at the bottom is available to load the next chunk. The Product Configuration Modeler can make use of Characteristic Groups to distribute Characteristics over different tabs.
While this approach is sufficient for a lot of 'standard' use-cases, there are also other cases that need a more flexible UI that gives the modeler the freedom to arrange the Characteristics in a free manner dependent on the way how the configuration should be carried out to the internal end-users. This can mean that Characteristics are arranged arround a product image (they occur at the location where somehting needs to be configured) or that different sections within a group are created that the configuation follows a specific flow, even totally different layouts may be useful depending on the case.
With an UI Extension it is possible to replace the standard view for a Characteristic Group (the previously mentioned Grid to display the Characteristics) with an own implementation. An implementation basically leverages two custom controls of the Variant Configuration re-use Library to place Characteristics in freely defined Layout Containers. The Characteristics are addressed with their name. Furthermore it is also possible to use available UI5 Controls for own Characteristic representations.
This template project can be used to create VC UI Extensions that run with Advanced Variant Configruation on SAP S/4HANA 2302. For development this project requires a local installation of an active NodeJS LTS (Long Term Support) version and associated supported NPM version. See https://nodejs.org. Additionally the UI5 CLI Tools must be installed globally npm install --global @ui5/cli
.
If you wish to contribute code, offer fixes or improvements, please send a pull request. Due to legal reasons, contributors will be asked to accept a DCO when they create the first pull request to this project. This happens in an automated fashion during the submission process. SAP uses the standard DCO text of the Linux Foundation.
Refer to CODE OF CONDUCT file.
Copyright (c) 2022 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the LICENSE file.
Prerequisites
As mentioned in the Requirements section, the following must be installed:
- Node JS Active LTS (v16)
- UI5 CLI Tools - Global installation happens with the following command:
npm install --global @ui5/cli
The project is initialized by running the command npm install
to resolve the given npm dependencies. It consists of two sample views (webapp/view/robot_reach.view.xml
and webapp/view/robot_commonData.view.xml
) that illustrate how to use the StandardCharacteristic and CustomCharacteristic. The views make use of mockdata stored in the mockdata
folder and images that reside in the img
folder. The mock runtime is started with command ui5 serve
. Then in the Browser the page http://localhost:8080/index.html can be opened. It shows for each view (UI Extension), that is configured in the manifest, a button via which it can be launched. Event handlers are called and value assignments are written to the data model (in memory - not on disk), however any logic inmplemented in the origin Product Configuration Model can not be tested in the mock runtime mode. This can first be seen after the UI Extensions have been deployed and properly configured.
A new View can be copied from an existing sample view or created from scratch. In order to be able launch it from the initial Application page, it must be maintained in the routing targets section in the manifest.json
file. Note that the ui5 server has a livereload capability that whenever the sources change it autoamtically reloades the page.
The mockdata file to use must be specified in the targets
section in the manifest.json
file for each view separately (as it can be seen for the provided sample views). The data which needs to be provided to use the mock runtime mode is less then what is normally exchanged. See also the schema for the Characteristic
and CharacteristicValue
entity. In case of bigger mock data amounts it is beneficial to obtain the data from the original $batch
requests using the network tab in the browser developer tools when running the Simulation App.
See the Implementation description for more details on how to use the StandardCharacteristic and CustomCharacteristic controls.
For deployment the project needs to be built using ui5 build
. The result is then written to the dist
folder in the project.
Attention
- Be aware that you do not share the namespace over different UI extension projects. Running multiple UI Extensions from different deployment units with the same namespace at the same time (within one Product Configuration Model) is not possible.
- The provided sample views refer to the product
AVC_RBT_ROBOT2
which is part of the 'SAP Best Practices for SAP S/4HANA Cloud' package. In order to make use of the product in the Simulate Configuration Models app, it must be activated.- The sources in the
libs
folder of the template project are necessary to provide the mock runtime for local usage - they are excluded from the build.- The
Component.js
file in the root of the project is also only used in local mock runtime mode - it must not be changed and is not relevant at "real" runtime (only the view which is specified within an UI Extension registration is injected into the valuation screen).
The necessary steps for deployment depends on the installation type:
In the On-Premise scenario, the dist
folder can be directly uploaded to the Frontend System with the report /UI5/UI5_REPOSITORY_LOAD
. The user needs to have developer permissions.
In the S4 Cloud scenario the deployment is only possible via BTP. Therefore the S4 Cloud system needs to be connected to BTP. With the Business Application Studio (BAS) it is then possible to upload to the S4 Cloud System. As setting up this deployment channel consists of several steps with a lot of details, you ideally look at the following tutorial: Create a SAP Fiori App and Deploy it to SAP S/4HANA Cloud.
An UI Extension is registered by creating an UI Extension Object for it in the Maintain VC UI Extensions app. Each UI Extension object has a logical name and can have multiple versions, but only one version can be set as active. The active version is the one which is in general shown whenever the AVC Configuration UI is embedded by other applications. For testing purposes, the Product Config Modeler can choose between the available versions of an UI Extension in the Simulation Environment.
After the UI Extension Object has been saved, it can be attached to a Characteristic Group using the Manage Characteristic Groups app. The AVC Configuration UI displays now instead of the standard grid with Characteristics for a Characteristic Group the UI Extension. In case of problems while loading the UI Extension, an Error Page is shown.
The generic Event Handlers of the sap.i2d.lo.lib.vchclf.api.valuation.controller.CustomCharacteristicGroupBase
controller can be applied to most of the UI5 Control events. However there may be situations in which none of the generic handlers can be applied properly. In these cases an own event handler implementation becomes necessary. This can be done in an own controller derived from the CustomCharacteristicGroupBase controller - see the samples.
Create an issue in this repository if you find a bug or have questions about the content.
Copyright (c) 2023 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the LICENSE file.