Adding third party or custom Cordova plugins to a hybrid app in SAP Web IDE

Updated 2 April 2020: added limitations.

In this blog I want to showcase a feature we’ve recently added to our Cloud Build Service: the capability to add custom or third-party Cordova plugins, instead of the publicly available plugins available in the npm repository.

When we phased out the HAT Local Add-on component from Hybrid Application Toolkit, we actually created a feature gap as custom plugins were supported only via a local build through HAT Local Add-on. When developing Cordova apps that include custom plugins, it actually makes more sense to develop the app completely in a local development environment. However, we were contacted by several customers who wanted to use custom or more importantly third-party plugins in our Cloud Build so they could develop their apps in a cloud environment. These third-party plugins are not distributed through a public repository. We’ve listened to this feedback and added this capability.

Before explaining how you can add custom plugins to your hybrid projects in SAP Web IDE, I have one important recommendation to share:

When you start developing a new mobile app, we strongly recommend that you consider developing this with either MDK (Mobile Development Kit) for cross platform applications, or our native SDKs (SAP Cloud Platform SDK for iOS or SAP Cloud Platform SDK for Android).

Adding a custom barcode scanner plugin to a Packaged app

In this section I am going to add a custom barcode scanner plugin to a Packaged Fiori app. This type of app has all web assets required for the container app packaged inside the app.

For this case, we will create a new project in SAP Web IDE based on the Fiori Master-Detail template. From the menu, please select File > New > Project from template. For the Neo environment, please select the SAP Fiori Master-Detail Application template, follow the wizard steps and make sure that for the Application Scenario you select the Standalone App type in the Template Customization step.

Once the project is created in your workspace, right-click and select Mobile > Enable as Hybrid Mobile Project. This will add the required code and configuration for building a Cordova app. This will also include a default set of Cordova plugins.

Before we add our custom plugin, you need to realise that the barcode scanner plugin is a special case. By default, we add the SAP Kapsel Barcode scanner plugin in Packaged Apps, which is SAP’s customised version of the plugin. To avoid conflicts between the plugins, we need to remove this from the list of plugins being included in the app. The main reason for picking this scenario is that we have customer case where they would like to use a third-party barcode scanner plugin.

Right-click on the project and in the context menu, select Mobile > Select Cordova Plugins > Kapsel. Find the kapsel-plugin-barcodescanner and unselect it. Save your changes.

Our Cloud Build Service will pick up custom plugins from a folder called plugins in the mobile folder of your project. Create a new folder called ‘plugins’ in the folder <projectname>/mobile.

We are going to add a customised version of the phonegap barcodescanner plugin. Open the github page for this plugin at https://github.com/phonegap/phonegap-plugin-barcodescanner and download the zip file of this plugin to your machine. You can also clone the git repo, but then you will have bit more work to create the zip file. Using a zip file makes it easy to import a large amount of files into your SAP Web IDE project.

Going back to the project in SAP Web IDE, right-click on the folder ‘plugins’ and select Import > File or Project. Browse to select the file you’ve downloaded.

It is important that the name of the plugin folder is exactly the same as the cordova id of the plugin specified in the plugin’s package.json. Our Cloud Build Service will determine which cordova plugin to add based on the name of the folder. If the name doesn’t match the Cordova id, the plugin will not be loaded.

In this case, the cordova id is phonegap-plugin-barcodescanner.

Rename the plugin folder to this (basically, you just remove the “-master” in case you selected a drop from the master branch).

Now, for the sake of this demonstration / blog, we are going to change the colours used in the barcode scanning interface for iOS. By default, you will see a slightly transparent green box and red horizontal line while scanning a barcode. We’ll change the colours to a yellow box with a blue horizontal line. You could potentially change the scanner UI drastically, but that is up to you.

For Android, you can modify something else (e.g. change success beep).

Open the file plugins/phonegap-plugins-barcodescanner/CDVBarcodeScanner.mm and search for ‘blue’. Modify the two lines where this is found and save your changes.

We will now add some code to the Fiori app to add a button that triggers the barcode scanner plugin.

To add a button in the header toolbar, go ahead and open the file <project>/webapp/view/Master.view.xml and add the following line after the searchfield:

<Button id="barcodeButton" icon="sap-icon://bar-code" tooltip="Barcode Scanner" press="onBarcodeScan"></Button>

This button will call the function onBarcodeScan when pressed. Let’s add this function in the master controller. Open the file <project>/webapp/controller/Master.controller.js and add the following code after the onInit function:

		onBarcodeScan: function () {
			var that = this;
			try {
				cordova.plugins.barcodeScanner.scan(
					function (result) {
						that.getView().byId("searchField").setValue(result.text);
						var sQuery = result.text;
						if (sQuery) {
							that._oListFilterState.aSearch = [new Filter("BusinessPartnerID", FilterOperator.Contains, sQuery)];
						} else {
							that._oListFilterState.aSearch = [];
						}
						that._applyFilterSearch();
					},
					function (error) {
						sap.m.MessageBox.show("Barcode scanning failed: ", error);
					}
				);
			} catch (e) {
				sap.m.MessageToast.show("Cordova plugin is not available.");
			}
		},

Since this piece of code is using sap.m.MessageBox, please add this to the dependencies listed at the start of Master.controller.js.

In the same file, please find the code !Device.system.phone and replace it with !sap.ui.Device.system.phone

 

Disclaimer: The above is a very simple and minimalistic implementation to showcase the use of a custom plugin. It is by no means a good example or best practice of how to add a barcode scanner to your Fiori app.

Now that we are done adapting the project, let’s go ahead and build the app in the cloud.

In the project context menu, select Mobile > Build Packaged App and go through the wizard steps. For most of the options you can simply leave the default settings. It is required to select a signing profile in the build settings.

When the build is done, you can use the hyperlink to download the app, or use the QR code to install the app over-the-air onto your device.

After starting the app, authenticating and setting up the passcode, you will be able to see the customized barcode scanner.

Adding a custom barcode scanner plugin to a custom Fiori Client app

Besides the Packaged app type, we also offer a container app that loads the required web assets from an online source and caches this. You can build this type of app in SAP Web IDE Full-Stack as well, as I’ve mentioned in this blog.

Before we create the client, lets first publish the sample application created above as a web application onto SAP Cloud Platform. From the project context menu, select Deploy > Deploy to SAP Cloud Platform and click Deploy. The web application is now hosted on SAP Cloud Platform.

Once deployed, we can open its url.

Now that the web application is deployed, we will create the custom Fiori Client.

In the workspace context menu, select New > Project for Template. For the Category, select Custom Fiori Client App. Select the template and click Next. Provide a name for this project and click Next.

Provide an App ID (e.g. com.company.customfioriclient) and click Next. Take note that in case the App ID is already defined in SAP Mobile Services, you will be required to change the App ID to a unique id.

For this demo, I will not select a Fiori Launchpad as Fiori Source. Instead, I will provide a Fiori Application URL, which is the URL of the application we’ve deployed to SAP Cloud Platform earlier.

The CustomFioriClient project is now created in your workspace.

By default, a set of Cordova and Kapsel SDK plugins are added in this project. Since we are going to add our custom barcode scanning plugin, we need to deselect the Kapsel Plugin Barcodescanner.

Similar as for the Packaged App, in the project’s context menu, select Mobile > Select Cordova Plugins > Kapsel and deselect the kapsel-plugin-barcodescanner and save the configuration.

Next, we’ll add the custom plugin. Select the plugins folder in the CustomBarcode project (the Packaged app / web app project created earlier) and select Edit > Copy in the context menu.

Go back to your CustomFioriClient project, select the www folder and Edit > Paste the plugins folder here.

We are now ready to build the Custom Fiori Client. Go to Mobile > Build Custom Fiori Client App.

You can change the app’s name, icon and splash screen to your needs and select a code signing profile. We’ll skip the Push Notification configuration for this case. Click Build and our Cloud Build Service will start building the app.

When the build is done, you can use the hyperlink to download the app, or use the QR code to install the app over-the-air onto your device.

After starting the app, setting up the passcode and authenticating, you will be able to see the customized barcode scanner. The first time you load your app, it will take a while to load. The client caches your app’s web assets, so the next time you open the app it will load significantly faster as most web assets have been cached. I could show the screenshot of the app below, but they look exactly the same as the screenshots shown for the Packaged App.

Limitations

There are limits to what our Cloud Build Service can do for you. Most developer won’t run into these, but you should be aware of the following:

• Custom plugins are supposed for builds using Mobile Services only (not Fiori Mobile)
• Custom plugins written in Swift are not supported
• Any plugin requiring any additional npm or cocoa dependencies is not supported
• The allowed maximum size of the source bundle (the project’s content) including plugins is 300MB.

If this feature/blog is useful for you, please leave a like.

Ludo Noens – SAP Digital Workplace