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:
- Installation of custom Cordova plugins
- 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!
Hello Simmaco,
Thank you for this blog, I have found it well explained and very useful !
Best regards !
Edgar Martínez.
Hey Simmaco,
thanks for the explaination, but I have one big problem with custom plugins:
If I use cordova plugins from the list (like "Network Connection") and add custom plugins only first of the custom plugins where added. Any ideas? I'm not able to combine "local" and "custom" plugins like you did.
Thanks and best regards,
Sebastian
Hi Sebastian,
could you please confirm that, as shown in the screenshot at step 3 of part 1 of this guide, you specified the correct parent folder for all the plugins? I mean you have to put all the plugins with their own folders under an unique folder and specify it at this step. Have you done it in this way? How many custom plugins are you adding?
Simmaco
Hi Simmaco,
When I tried the first time, it was fine. Now could you tell me how to add another custom plugin? Since when I go to project setting>Device configuration and add local custom plugin it says Connection failure.
And when I am following the above mentioned steps again for adding custom plugin, that time when I am running the setup, it wont allow me to configure path for setting custom plugin.
Hi
How I can get device unique id from cordova
Regards
Kiran
This blog post is outdated. We have reached end-of-maintenance for HAT local add-on. You can no longer download this tool from the SAP Store. We no longer support this tool. You are strongly advised to make use of our Cloud Build Service provided through Mobile Services to build hybrid apps. More information can be found here: https://blogs.sap.com/2018/08/16/announcing-end-of-maintenance-for-hybrid-app-toolkit-local-add-on-local-builds-only
Also note that the use of custom plugins is not supported with our cloud build service.