Adaptation Projects: A Tutorial

In prior blogs, I gave a high level overview of Adaptation Projects and presented a video demo.  If your interest is piqued, follow along with today’s blog to create your own application variant using Adaptation Projects.

Pre-requisites:

When creating an Adaptation Project, you must have access to an ABAP on premise system that contains some applications made with SAP Fiori elements. For this tutorial, you will need a SAP Cloud Platform Cockpit account, access to SAP Web IDE and access an SAP demo system, ES5.

1. Don’t have access to Web IDE and SAP Cloud Platform Cockpit? Follow the instructions here to get an account.
2. Next, sign up for a demo account on ES5 here.
3. Next, in SAP Cloud Platform Cockpit you have to create a destination using the following data:

#
#Tue Dec 05 14:36:33 UTC 2017
Description=SAP Gateway Demo System
Type=HTTP
TrustAll=true
Authentication=NoAuthentication
WebIDEUsage=odata_abap, bsp_execute_abap, odata_gen, dev_abap
Name=ES5
WebIDEEnabled=true
CloudConnectorVersion=2
URL=https\://sapes5.sapdevcenter.com
ProxyType=Internet
sap-client=002
WebIDESystem=ES5

You can simply create a text file that contains the above mentioned data and import the destination as follows:

1. Log in to the SAP Cloud Platform Cockpit.
2. Select your account.
3. Click Connectivity.
4. Click Destinations.
5. Click Import Destination.
6. Select your destination configuration file and click Open.
7. Select Save.

Exercise

Now that you’re configured, let’s create an Adaptation Project.

Scenario: you are one of Santa’s elves and you had a heck of a time finding the right sized boxes as you were wrapping gifts last Christmas.  You’d like to search for products that fit in Small, Medium and Large sized boxes to help organize your packaging when the crush happens next time around.

To do this, you are going to extend the Manage Products application that resides on ES5. This application allows users to search for products and look at the details of those products. This application was created using the SAP Fiori elements List Report and Object Page.

When you create an Adaptation Project, you are creating a new variant of an existing application. The app variant refers to the original application but contains a separate set of changes created in the adaptation project. Also, if the original application is changed, the variant will incorporate those changes.  A new application ID is defined for the variant and the variant will need to be registered in SAP Fiori launchpad in order for users to access it.

1. Open SAP Web IDE.
2. Create a new adaptation project: File -> New -> Adaptation Project
3. Now you need to enter a project name and application title.
   Project Name: adapt.listreport.products
   Application Title: Adapted Manage Products
   Namespace: <accept the default value>
4. Select Next.
5. Now we need to select a system and source application upon which to base this variant.Select SAP Gateway Demo System (that’s ES5). You may need to enter your user name and password for that system.Select the application with the Description Manage Products and select Finish.
6. A new project is created and shows you a working application based on the source application. Any changes we make in this variant are not going to change the code of the source application.Next, let’s open up this project in the SAPUI5 Visual Editor, where we can preview what the application looks like.Right click on the project and Select SAPUI5 Visual Editor*Note: You might be prompted for a user name and password. If so, enter your user name and password for the ES5 system, which you created in the 1st pre-requisite step.
7. You see that you can do a search for products based on a number of filters. Do a search where you filter on price range to see how it works.
8. Let’s add another filter – one that searches on shipping box sizes.Before we start editing, let’s disable Safe Mode.When in Safe Mode, the developer can only make changes that Key Users can make in Adaptation at Runtime, and those are changes that will always work when the source application is updated.  In Safe Mode you can move sections, rename labels, etc.  However, we want to make more changes than that…Select Safe Mode
9. De-select the Enable Safe Mode checkbox to disable it and select Apply.
10. Go to Edit mode.
11. In order to add a new filter, you need to add a new fragment.Right click in the filter area and select + Add Fragment menu item.
12. Here we are going to create a new Control Configuration named boxFilter.
    From the Target Aggregation dropdown, select controlConfiguration.Select the Create new In the Add Fragment dialog box, enter a Fragment Name of BoxFilter and select Create.
13. Now we have a new Boxfilter XML file that’s blank and we need to add some code. Copy the following code and paste it in to the boxFilter.fragment.xml in your SAP Web IDE. Then Save.

    <!-- Use stable and unique id's!-->
    <core:FragmentDefinition xmlns:core='sap.ui.core' xmlns='sap.ui.comp.smartfilterbar' xmlns:m='sap.m'>
    	<ControlConfiguration
    	id="boxFilter"
    	key="boxFilter"
    	index="20"
    	label="{i18n>BOX_FILTER}"
    	groupId="_BASIC"
    	visibleInAdvancedArea="true"
    	filterType="multiple"
    	>
    		<customControl>
    			<m:ComboBox id="boxTypes">
    				<core:Item id="smallBox" key="small" text="{i18n>SMALL_BOX}" />
    				<core:Item id="mediumBox" key="medium" text="{i18n>MEDIUM_BOX}" />
    				<core:Item id="largeBox" key="large" text="{i18n>LARGE_BOX}" />
    			</m:ComboBox>
    		</customControl>
    	</ControlConfiguration>
    </core:FragmentDefinition>

     

14. Go back to the Visual Editor tab and accept the message that says changes were made outside the editor and let it reload the editor.  You may be asked if you want to save unsaved changes in the editor – if so, select Save.
15. To get your new filter configured for localization, you can add keys to the i18n.properties file.   In the tree view of Web IDE, double-click on the i18n.properties for the ListReport of this project to open it in the editor.
16. Copy the following code and replace the contents of i18n.properties and then select the Save button:

    #Make sure you provide a unique prefix to the newly added keys in this file, to avoid overriding of SAP Fiori application keys.
    
    BOX_FILTER=Box Size
    SMALL_BOX=Small
    MEDIUM_BOX=Medium
    LARGE_BOX=Large

     

17. Go back to the Visual Editor tab and accept the message that says changes were made outside the editor and let it reload the editor.  You’ll see the new filter, but there is still no code there to control how it works.
18. Select Edit, right click in the SmartFilter area and select Extend with Controller.
19. Enter a name of ListReportControllerExtension and select Extend.
20. Now you are looking at a new file, ListReportControllerExtension.js. Notice this is not an empty file, inside the comments you find documentation about which methods you can extend. There is a lot of documentation on controller extensions in the SAPUI5 documentation.For now, replace the contents with the following code and select the Save button:

    /***
    @controller Name:sap.suite.ui.generic.template.ListReport.view.ListReport,
    *@viewId:nw.epm.refapps.st.prod.manage::sap.suite.ui.generic.template.ListReport.view.ListReport::SEPMRA_C_PD_Product
    */
    sap.ui.define([
    		"sap/ui/core/mvc/ControllerExtension",
    		"sap/ui/model/Filter",
    		"sap/ui/model/FilterOperator"
    	],
    	function (
    		ControllerExtension,
    		Filter,
    		FilterOperator
    	) {
    		"use strict";
    
    		//hard coded list of shipping box sizes:
    		var BOX_SIZES = {
    			small: new Filter({
    				filters: [
    					new Filter({
    						path: "Height",
    						operator: FilterOperator.BT,
    						value1: 0,
    						value2: 10
    					}),
    					new Filter({
    						path: "Width",
    						operator: FilterOperator.BT,
    						value1: 0,
    						value2: 10
    					}),
    					new Filter({
    						path: "Depth",
    						operator: FilterOperator.BT,
    						value1: 0,
    						value2: 10
    					})
    				],
    				and: true
    			}),
    			medium: new Filter({
    				filters: [
    					new Filter({
    						path: "Height",
    						operator: FilterOperator.BT,
    						value1: 10,
    						value2: 20
    					}),
    					new Filter({
    						path: "Width",
    						operator: FilterOperator.BT,
    						value1: 10,
    						value2: 20
    					}),
    					new Filter({
    						path: "Depth",
    						operator: FilterOperator.BT,
    						value1: 10,
    						value2: 20
    					})
    				],
    				and: true
    			}),
    			large: new Filter({
    				filters: [
    					new Filter({
    						path: "Height",
    						operator: FilterOperator.GT,
    						value1: 20
    					}),
    					new Filter({
    						path: "Width",
    						operator: FilterOperator.GT,
    						value1: 20
    					}),
    					new Filter({
    						path: "Depth",
    						operator: FilterOperator.GT,
    						value1: 20
    					})
    				],
    				and: true
    			})
    		};
    
    		return ControllerExtension.extend("customer.adapt.listreport.products.ListReportControllerExtension", {
    
    			// this section allows to extend lifecycle hooks or override public methods of the base controller
    			override: {
    				// 	override public methods of the ListReport controller and its members like templateBaseExtension
    				templateBaseExtension: {
    					/**
    					 * Can be used to add filters. They will be combined via AND with all other filters
    					 * sControlId is the ID of the control on which extension logic to be applied.
    					 * For each filter the extension must call fnAddFilter(oControllerExtension, oFilter)
    					 * oControllerExtension must be the ControllerExtension instance which adds the filter
    					 * oFilter must be an instance of sap.ui.model.Filter
    					 */
    					addFilters: function (fnAddFilter, sControlId) {
    						var oComboBox = this.byId("boxTypes");
    						var sSelectedBoxType = oComboBox.getSelectedKey();
    						//lookup the filters from the definition
    						var oFilter = BOX_SIZES[sSelectedBoxType];
    						if (oFilter) {
    							fnAddFilter(this, oFilter);
    						}
    					}
    				}
    			}
    		});
    	});

     

21. Now go ahead and preview as a web application.  Select Run-> Run as Web Application. If asked which configuration to use, select the Adaptation_index.html.

Congratulations, now you’re running your application! Try filtering on the box sizes and note the different results when you select Small, Medium or Large boxes.  If you like, you can customize the table to show the dimension columns to see whether the products will really fit in to the box sizes indicated.

Your variant of the Manage Products application is now complete and ready to deploy!  Unfortunately, the ES5 system does not allow the general public to deploy to it, so I cannot give you instructions for doing that part of the project. However, if you are curious about how to deploy a SAPUI5 application to SAP Fiori launchpad, here is an excellent tutorial that details the steps.

If you found this tutorial helpful and interesting, keep an eye out for a new OpenSAP course on SAPUI5 in early 2019. The new course will include some lessons on Adaptation Projects and other flexibility functionality.

Helpful Links:

SAPUI5 Visual Editor

Adaptation Projects for Fiori Elements Applications

Extending Delivered Apps Using Adaptation Extensions

Adaptation Extension Example: Adding a Button to the Table Toolbar in List Report

About the authors Jessica Merz and Sebastian Wennemers

	Jessica is the Product Manager for SAPUI5 flexibility functionality and is always looking for ways to improve the user experience of SAPUI5 based applications.  With a background of nearly 20 years of user research and UX design, she enjoys helping people make their applications intuitive and delightful.
	As Development Architect for SAPUI5 flexibility functionality Sebastian enables several people, from end users to developers, to get the best out of existing SAPUI5 apps. With the work of his team they can adapt these apps with easy to use tooling in a lifecycle stable and modification-free way, so that the apps fit best to their processes and needs.