Installing Cordova Plugins

Currently the process for installing Cordova Plugins contains a number of manual steps. Eventually we would like to improve this with tooling.

Ensure that you have the Cordova CLI installed:
- sudo npm install -g cordova
In a separate directory, create a new Cordova project:
- cordova create cordova-plugin-test
Add the platforms you need:
- cd cordova-plugin-test
- cordova platform add android
- cordova platform add ios
Find the plugin you want to install, and install it:
- cordova plugin search bar code
- cordova plugin add com.phonegap.plugins.barcodescanner
Build the Cordova app:
- cordova build android
- cordova build ios

Android

Copy the contents of cordova-plugin-test/platforms/android/res to astro/astro/src/main/res. Merge as necessary.
Copy the contents of cordova-plugin-test/platforms/android/src (except for the io directory) to astro/astro/src/main/java. Merge as necessary.
Copy the contents of cordova-plugin-test/platforms/android/libs to astro/astro/libs.
Copy cordova_plugins.js, cordova.js, and plugins from cordova-plugin-test/platforms/android/assets/www to astro/demo/src/main/assets.
Use your creativity to merge the contents of cordova-plugin-test/platforms/android/AndroidManifest.xml to astro/astro/src/main/AndroidManifest.xml paying close attention to intents and permissions. Also don't forget the activities for scanning and encoding. Trust me, you’ll know soon enough whether you did this right!
Modify AstroWorkerPlugin to load in cordova.js and cordova_plugins.js (see snippet 1).
Modify AstroWebViewPlugin to initialize the plugin (see snippet 2).
Rebuild your project, run it, inspect the web view which is running app.js, and call your Cordova plugin!
Troubleshooting pro tip: If the app is not working, ensure that “Do not keep activities” is not checked in your device’s Developer options.

Snippet 1

private static final String HTML_TEMPLATE_FORMAT_STRING = "<html><head><script src='cordova.js'></script><script src='cordova_plugins.js'></script><script src='%s'></script></head></html>";

Snippet 2

// Poor man's Cordova plugin initialization.
CordovaPlugin plugin = new BarcodeScanner();
PluginEntry entry = new PluginEntry("BarcodeScanner", plugin);
cordovaPluginEntries = new ArrayList<PluginEntry>();
cordovaPluginEntries.add(entry);

iOS

Create a group in your project and name it Cordova. We'll be putting all files related to Cordova and Cordova plugins here.
Create a folder reference in the Cordova folder and name it www
Create a group within Cordova named Plugins
Open cordova-plugin-test/platforms/ios/www in Finder
Drag cordova-plugin-test/platforms/ios/www/cordova_plugins.js into the www
- If you have existing plugins, you'll need to merge the cordova_plugins.js file.
Drag cordova-plugin-test/platforms/ios/platform_www/cordova.js into the www

Create Cordova/www/index.html and populate it with the following HTML:

<html>
  <head></head>
  <body>
    <script src="cordova.js"></script>
  </body>
</html>

Drag cordova-plugin-test/platforms/ios/HelloCordova/config.xml into the Cordova folder in your Xcode project (ensure that "Copy items if needed" is checked)
- If you have existing plugins installed, you will need to merge config.xml into the existing one. Look for references to your plugin Objective-C/Swift files in the source config.xml
Drag the folder named after your plugin (eg. com.manateeworks.barcodescanner) from cordova-plugin-test/platforms/ios/HelloCordova/Plugins/ into Cordova/Plugins/ in your Xcode project.
Review the XML found in cordova-plugin-test/plugins/{your_plugin}/plugin.xml.
- Find the node $/plugin/platform[name='ios']
- Add each framework or library referenced within this element to the "Linked Frameworks and Binaries" section of your Xcode project's target.
  - Eg. <framework src="CoreVideo.framework" weak="false" />
  - Note that some of these libraries might be packaged with the plugin in cordova-plugin-test/HelloCordova/Plugins/{your_plugin}/
Rebuild your project, run it, inspect the web view which is running cordova.js and app.js.
If you see both cordova.js and app.js loaded in the inspector, you can now modify app.js and call your Cordova plugin!

Plugin Caveats & Compatibility

Cordova plugins vary in quality and implementation. Some are more compatible with Astro than others. Any non-UI based plugin should be 100% compatible. Plugins that present a UI should work correctly if they present their own UIViewController (using viewController.presentViewController(customPluginViewController)).

Some plugins manually integrate UIViews into the view hierarchy using self.webView.superview.addSubview(). These plugins will not work because the UIWebView that hosts the Cordova javascript (as well as the Astro app.js) is never visible. These plugins would need to be changed to use presentViewController() before they work.

The behaviour you'll get if you instantiate multiple instances of the same plugin from different web views is undefined. Some plugins that present their own UI (as discussed above) may work but may supercede the other web view's plugin UI. In other cases they may conflict and cause errors. Generally we recommend only using Cordova plugins from app.js.