Adaptation Project: Get to know how to extend a Fiori Elements app
In this blog post, we will understand what are the different types of users of Fiori applications and what options are available to them to create their own extensions. We will also learn in detail on how to create an Adaptation project, and get to know how customers can create their own extensions to standard fiori apps without creating modifications.
Different Personas and their needs
There are different types of users for Fiori applications. Each type of user has their own requirements, and they can be broadly classified into the following categories.
Extensibility options in S/4HANA
S/4HANA provides different options for creating extensions based on the kind of user.
S/4HANA provides Runtime Extensibility option for Key Users (Business Experts).
Key Users of Fiori applications can extend an application and incorporate additional changes at runtime.
This can be achieved using the Adapt UI option in Fiori Launchpad.
S/4HANA also provides Design Time Extensibility option for Developers, which provides additional freestyle capabilities compared to the Adapt UI option.
SAPUI5 flexibility uses Layering concept to store the UI changes.
The changes are stored in Layered Repository (LREP) in respective layers.
Understand more about Layering concept here.
Type of changes
|USER||Customer||End users||User Personalization settings|
|CUSTOMER||Key users||UI Changes to adapt apps for all users|
|End users||Views that the end user saves as Public|
|CUSTOMER_BASE||Developers||UI changes made with SAPUI5 Visual Editor|
|VENDOR||SAP||SAP||Example: Update of an app|
Design Time Adaptation (DTA) for extending Fiori Elements Application
How can customers extend a Fiori Elements application and add custom logic to it which is modification-free?
As of S/4HANA 1809, this can be achieved with…… Adaptation Project!!
When an Adaptation Project is created, a new variant of the existing application is created. The app variant has a reference to the original application but contains only changes created in the adaptation project. Hence, any new changes made in the original application are automatically available in the adaptation project as well. The changes made in the variant are applied on top of the original application.
Some key features of Adaptation Project are:
- Semantic changes can be done to applications (Ex. Hide a field based on certain condition)
- Control properties and bindings can be changed (Ex. Enable or disable Excel Export for Smart Table)
- Custom XML fragments can be added to extend views (Ex. Open a custom dialog on click of a button)
- Extend I18n texts (Ex. Translation for labels of custom buttons)
- Move controls/sections (Ex. Place a custom field in between 2 standard fields in object page)
How is Adaptation project different from Break-outs (template extensions)?
- Break-outs are a part of the actual application. Hence, if an application development team creates a Fiori elements app, and a customer wants to add custom logic via break-outs, then that would be a modification.
- Break-outs are extensions to the smart template and are a part of the original application, whereas adaptation project is an “extension” of the application!
Creating an Adaptation Project
An Adaptation project can be created in WebIDE, by selecting a source application which needs to be extended.
Provide the requested details and follow the configuration in the wizard.
Open the project using SAPUI5 Visual Editor.
We can Preview and Edit the application. When in Safe mode, only semantic changes (changes possible during the application runtime) can be made.
Safe mode provides less freestyle capabilities but allows you to stay fully compatible with a future upgrade of the source application.
Click on Safe mode button and then disable the safe mode. Once Safe mode is disabled, it cannot be enabled again.
If you use the SAPUI5 Visual Editor without Safe mode, you are responsible for any changes that you make to the project.
Once the app is deployed to the system, changes made using the Visual Editor are saved in the Layered Repository (LREP).
Use case: Add a custom button to open an email
In the Visual Editor, disable the Safe Mode and go to Advanced Mode.
Click on Edit button to make the changes.
- The Outline tab shows the hierarchy of the controls in the screen.
- The Changes tab shows the currently applied changes.
- The right side pane shows the properties that can be changed for the selected control.
Select the control where the button is to be added.
The custom button needs to be added in the table toolbar of the list report. So the table toolbar should be selected.
Click on Add fragment.
Select the Target aggregation and position where the new fragment needs to be added.
Click on Create new to create a new fragment.
Provide a fragment name and click on Create.
The new fragment is created.
Add the XML logic to add a button. Use Stable IDs in the XML code.
A changes folder gets created in the project. The fragment is saved in fragments folder.
A change file is created to apply the XML fragment on top of the source application.
The layer property in the change file indicates the layer at which the change was made.
Save the changes made and click on Preview. The newly added button would be visible.
Now let us extend the controller to handle the click of the button.
Click on Edit button. Click on the newly created button and select Extend with Controller.
Provide a controller name and click on Extend.
A coding folder is created, under which the extension controller file is saved.
A change file is created to apply the extension controller logic on top of the source application.
In the controller extension file, add a function and write the logic to open an email.
Add the press event to the button in the XML fragment.
Ensure that the event handler is provided correctly. It has to begin with .extension.
Save the changes.
Run the Adaptation_index.html to execute the application in WebIDE.
Click on Send email button.
An email opens in outlook!!
Deploying the application
Now let us deploy the application to the ABAP repository.
Right click on the project > Deploy > Deploy to SAP NW Application Server ABAP
Follow the steps prompted.
Provide the Package and TR details if you are using one.
In this case, let us go ahead with a local object.
Click on Finish to deploy.
Once the deployment is successful, success message is displayed!
The application would be saved in the Layered repository. It can be opened using transaction SUI_SUPPORT.
Provide the application variant ID and click on execute.
The list of files would be displayed from the Layered Repository.
Fiori Launchpad Tile configuration
A new tile can be configured using the Fiori Launchpad Designer (Transaction Code /UI2/FLPD_CUST or /UI2/FLPD_CONF).
Open the catalog where the tile is to be added.
Add the details for the tile and target mapping.
Provide the ID from the manifest app descriptor in the project.
- The recommended way is to use the same Semantic Object as the source application, but a different Action. This ensures that whenever there is a navigation implemented using CDS annotations, then both (the source application and the variant) appear in a popup.
- Another way is to use the same semantic object and action as that of the source application, along with the sap-appvar-id parameter.
Add the tile to the required group.
The tile will appear in the Fiori Launchpad.
With this, the adaptation project has been deployed to the system and it can be accessed from the Fiori Launchpad.
Currently, few of the limitations of Adaptation Project are listed below:
- Supports Fiori Elements applications. Not all Free style apps are supported.
- Supports only smart controls.
- Not all properties of a control can be changed.
- App to App navigation is not supported in WebIDE.
- Other Reuse components cannot be embedded in an Adaptation project.
- Not all properties of a table Column can be changed.
- It is not possible to change the OData service that is used in the source application.
(Some of these limitations might be addressed in future).
With a vast range of freestyle capabilities, Adaptation project is a go to option for customers to implement their own custom extensions to standard Fiori applications.
The following links would help you to understand more about Adaptation project.