Cordova is used in Oracle Mobile Application Framework (MAF) to provide access to device features. MAF 2.1.0 uses Cordova version 3.6.3 on Android and 3.7.0 on iOS, dramatically increasing the number of available plugins that developers can leverage.
MAF 2.1.0 greatly simplifies the process of adding 3rd party Cordova plugins into a MAF app by internally using the plugman command-line interface to build the plugin and incorporate all the required artifacts into your MAF app.
So how do you migrate an existing MAF app that uses a 3rd party Cordova plugin to MAF 2.1.0?
The following steps and screenshots show the process of migrating the BarcodeDemo sample app from MAF 2.0.1 to MAF 2.1.0 using JDeveloper.
Step 1 – Download JDK 8 and update MAF extension
MAF 2.1.0 requires JDK 8. Download JDK 8 before updating the MAF extension to 2.1.0 via Check for Updates in JDeveloper. Following a restart, you will be prompted to enter the JDK 8 location on your local machine and to reconfigure the Android and iOS Platform Preferences in JDeveloper. Please refer to the Installation Guide for more detailed information.
Step 2 – Automatic app migration
Open your MAF app within JDeveloper and you will be prompted to allow JDeveloper to automatically migrate your app. The Installation Guide describes this process in more detail.
Step 3 – Remove the old plugin code
In a later step, you will point JDeveloper to the location of the plugin’s source code on your local machine and JDeveloper will use plugman to build the plugin and incorporate it into your MAF app.
Before doing that, you should remove the plugin artifacts that you had manually added to your MAF app previously. This includes:
- Android native code found in Projects > ApplicationController > Application Sources > plugins.BarcodeScanner.Android
- iOS native code found in Projects > ApplicationController > ApplicationSources > plugins.BarcodeScanner.iOS
- JavaScript files found in Projects > ViewController > Web Content > plugins
Step 4 – Remove unnecessary iOS app icons and launch images
This is an optional step to reduce the size of your app. You can remove the following iOS app icons and launch images for unsupported devices and operating system versions, found in Application Resources > Resources > ios:
- Default-1135h@2x.png
- Default-Land.png
- Default-Landscape-Ipad.png
- Default-Landscape.png
- Default-Landscape@2x.png
- Default-Landscape@2x~Ipad.png
- Default-Portrait-Ipad.png
- Default-Portrait.png
- Default-Portrait @2x.png
- Default-Portrait @2x~Ipad.png
- Default.png
- Default@2x-Landscape.png
- Icon-50.png
- Icon-50@2x.png
- Icon-57.png
- Icon-57@2x.png
- Icon-72@2x.png
- Icon-80.png
- Icon-144.png
- icon-72.png
- icon.png
- icon@2x.png
Step 5 – Remove old plugin details from the Plugins UI
To complete the removal of the old plugin, you should remove the references to it from within the maf-application.xml Plugins UI, by selecting each reference and clicking the red ‘x’ icon.
Step 6 – Save all, Clean all
At this point, save all modifications and then do a ‘clean all’.
Step 7 – Download a new version of the plugin
MAF 2.1.0 requires you to have the plugin source code residing on your build machine, located on the same drive as your app source code, in a path that contains no spaces.
It is likely that there is a later version of the plugin that you have used previously which is compatible with the Cordova versions used by MAF. You may even find that more recently someone has written a plugin that provides a better match to your requirements.
Anyone can build a Cordova plugin and they can choose to keep it to themselves or to publish it for use by others. The most common way to publish a Cordova plugin is to store it in a Git repository and to register it with the Cordova plugin registry. Launch your browser and open http://plugins.cordova.io.
To find a barcode scanner plugin, type in “barcode” and search.
Click on com.phonegap.plugins.barcodescanner to view the details of this plugin.
You can see that this plugin requires Cordova version 3.0.0 or greater, works on Android and iOS, and was last updated 3 months ago to version 2.0.1. This page also provides a description and API documentation.
To access this plugin, click on the link to its Git repository.
To download this plugin, click on the link to Download Zip.
Once the plugin has been downloaded, extract the zip file contents into a location relative to your app’s source code which does not contain spaces. For example, you wish to extract the plugin into your app’s src folder as follows:
Step 8 – Add the plugin via the Plugins UI
To import the downloaded version of the plugin into your MAF app, return to the maf-application.xml Plugin UI in JDeveloper and click the green ‘+’ icon. Navigate to the location of the plugin’s top-level folder and click the Select button.
The details of the plugin, which are read from the plugin.xml file, will be displayed in the Plugins UI.
Step 9 – Update the JS that calls the plugin API
In most cases, you will need to update the JavaScript that calls the plugin API. Firstly, you no longer need to include the plugin’s JavaScript file because plugman will include this into your application at deploy-time. Secondly, the manner in which you invoke the plugin’s JS API may have changed.
For the BarcodeDemo sample app, this means editing the scanner.amx file to remove the inclusion of barcodescanner.js and to change window.plugins.barcodeScanner.scan to cordova.plugins.barcodeScanner.scan as described in the plugin’s README.md file.
Step 10 – Save all, deploy and test
All that’s left now is to save all modifications, deploy your app (most likely to a device, since many plugins won’t work on a simulator or emulator) and test it.
A tip for anyone using plugins with dependencies
If a 3rd party Cordova plugin has a dependency on another plugin, this will be defined in the plugin.xml file. At deploy-time, JDeveloper calls plugman to build and incorporate the 3rd party plugins defined in the maf-application.xml Plugins UI. If one of these plugins has a dependency, plugman will automatically attempt to download the required plugin's source code so it can be built and incorporated into your MAF app.
If your build machine is behind a firewall, this attempted download may cause the JDeveloper deployment to hang for a while before reporting error messages similar to the following:
[10:21:35 AM] Fetching plugin "https://github.com/apache/cordova-plugin-device" via git clone
[10:21:35 AM] Deployment Successful
[10:21:35 AM] Failed to install 'de.appplant.cordova.plugin.local-notification':Error: Command failed: Cloning into '/var/folders/h9/84x8qcsj391c355v3v137n580000gn/T/plugman/git/1423102819927'…
[10:21:35 AM] fatal: unable to access 'https://github.com/apache/cordova-plugin-device/': Failed to connect to github.com port 443: Operation timed out
[10:21:35 AM] at ChildProcess.exithandler (child_process.js:648:15)
[10:21:35 AM] at ChildProcess.emit (events.js:98:17)
[10:21:35 AM] at maybeClose (child_process.js:756:16)
[10:21:35 AM] at Socket.<anonymous> (child_process.js:969:11)
[10:21:35 AM] at Socket.emit (events.js:95:17)
[10:21:35 AM] at Pipe.close (net.js:465:12)
[10:21:35 AM] Command failed: Cloning into '/var/folders/h9/84x8qcsj391c355v3v137n580000gn/T/plugman/git/1423102819927'…
[10:21:35 AM] fatal: unable to access 'https://github.com/apache/cordova-plugin-device/': Failed to connect to github.com port 443: Operation timed out
The solution for this is:
- Download and extract the required plugin as per Step 7 above.
- Remove the dependent plugin from the Plugins UI.
- Add the required plugin to the Plugins UI.
- Add the dependent plugin to the Plugins UI.
This will ensure that each plugin is built and incorporated into your MAF app in the correct order.