How to use custom Cordova plugins with SAP Web IDE and Hybrid Application Toolkit

Introduction

As of the Hybrid Application Toolkit version 1.8.2, you have the capability to add to your applications “custom Cordova plugins“. This is a very nice feature because you can enrich the functionalities of your Hybrid applications developed using SAP Web IDE. In this blog I’m going to show you how to “enable” this feature and how to use it. I’ll create a very basic hybrid application which includes a couple of custom plugins like the AppInfo plugin (danmichaelo/cordova-plugin-appinfo · GitHub) and the Email Composer plugin (katzer/cordova-plugin-email-composer · GitHub). Of course this is just an example and you can choose your own plugins to be included in your hybrid application.

NOTE: The steps reported here have been tested on a MAC platform, but it should be the same for PC workstations.

This blog is split in two parts:

1. Installation of custom Cordova plugins
2. Use of custom Cordova plugins within a hybrid application

Prerequisites

• SAP Web IDE 1.15
• Hybrid Application Toolkit 1.8.2+
• A mobile device to test the results

Limitations

There is just one limitation at moment with custom Cordova plugins. If you have already added some plugins to your Companion App and you need to add one more, then you have to perform the HAT installation again in order to be able to see the new plugin added to the Companion App. This limitation will be hopefully eliminated in the future.

Let’s get started!

Part1: Installation of custom Cordova plugins

1) Create a local folder on your drive which will host all the custom Cordova plugins you want to make available for your applications. In my case I have created a folder named “custom_cordova_plugins” directly in my user folder

2) Once you have decided which are the plugins you want to install, simply clone them into this folder by using the “git clone” command. At moment the plugins must be stored locally in order to be taken by HAT installation

3) Start the installation of HAT and, when you reach the point “Configure path for Custom Plugins“, just enter the complete path to the folder hosting all the plugins and click on Save. Your path of course might look different if you have a PC

4) At the next screen screen, when you have to Edit Companion App Build Configuration, choose the plugins you want to include in your companion app and click on Save

5) Proceed with the Hybrid Application toolkit installation as usual

Part 2: Use of custom Cordova plugins within a hybrid application

1) Start the Hybrid Application Toolkit

2) Open SAP Web IDE and create a new application starting for example from the SAPUI5 Mobile Kapsel App Project

3) Enter a project name

4) Define the view type, the namespace and the view name

5) Click on Finish

6) If you run the app, you should get just a blank app

7) Right click on the project name and choose Project Settings

8) Select Device Configuration and define your settings; then in the Plugins section select the available plugins you want to include (i.e. Device Information) and then click on the Custom button

9) Choose the custom plugins you want to include in this application and click on OK. In my case I’m choosing both the AppInfo and the EmailComposer plugins

10)  You should have added now 2 new plugins. Click on Save

11) Locate the file Main.view.xml in your project, right click on it and choose Open With > Layout Editor

12) From the Container pane on the left add two HBox components to the view and for each one of them add a Button component taken from the Action pane. Set the two buttons in the middle of the related HBox components and change the title for the view and for the two buttons. You should get something like this. Then save the file

13) Reopen the same Main.view.xml file, this time by double clicking on it. The file is opened in the editor. Add the press events for the two buttons and save the file.

...
<Button text="Show application info" width="200px" id="__button2" press="onappinfo">
...
<Button text="Send an email" width="150px" id="__button4" press="onsendemail">
...

14) Double click on the Main.controller.js file to open it in the editor. Add the following code just after the first row and save the file

onappinfo: function() {
    navigator.appInfo.getAppInfo(function(appInfo) {
          jQuery.sap.require("sap.m.MessageBox");
          sap.m.MessageBox.show('Device Model: '
              + device.model
              + '\nApp Identifier: '
              + appInfo.identifier + '\nVersion: '
              + appInfo.version + '\nBuild: '
              + appInfo.build, {
                    icon: sap.m.MessageBox.Icon.INFORMATION,
                    title: "Information",
                    actions: [sap.m.MessageBox.Action.OK],
                    styleClass: (!sap.ui.Device.support.touch ? "sapUiSizeCompact" : "")
          });
    }, function(err) {
          alert(err);
    });
},
onsendemail: function() {
    navigator.appInfo.getAppInfo(function(appInfo) {
          var sInfo = '<b>Device Model:</b> '
              + device.model + '<br><b>App Identifier:</b> '
              + appInfo.identifier + '<br><b>Version</b>: '
              + appInfo.version + '<br><b>Build:</b> '
              + appInfo.build;
          cordova.plugins.email.open({
              to:      '<a_valid_email_address>',
          subject: 'Application details',
          body:    sInfo,
          isHtml:  true
          });
    }, function(err) {
          alert(err);
    });
}

where “<a_valid_email_address>” is the recipient you want to send the message to.

Let me just spend a few words on this code. This is the code for the two buttons. When you press the button to get the app info the “onappinfo” event is fired and its code executed; when you click on the button to send an email the “onsendemail” code is executed.

For the first button we require the application info to the plugin and they are stored in the “appInfo” variable which is then displayed in message box.

Quite the same happens with the “Send an email” button: the only difference is that instead of displaying the information retrieved in a message box I use them to compose an email with the EmailComposer plugin.

15) Your application is complete. If you want, you can test it using the companion app. In my case I just want to run it on the mobile device, so let’s deploy it to local HAT. In SAP Web IDE, right click on the project name and choose Deploy > Deploy to local App Toolkit

16) When the previous step finishes, right click on the index.html file in your project and choose Run > Run on > iOS (Android) device. The application will be executed on your device

17) Click on the first button to show the application info. As you can see here we have either the information regarding the device model coming from the Device Plugin, either the application information coming from the AppInfo custom plugin. Click on OK to close the message

18) Click on the second button named Send an email

19) A new email is created with the same information we have seen before and it’s ready to be sent.

NOTE: At this point you can also send this email, but it only works if you have an email account configured on your device/emulator.

20) Congratulations! You have successfully included and used some custom Cordova plugins!