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
toastro/astro/src/main/res
. Merge as necessary. - Copy the contents of
cordova-plugin-test/platforms/android/src
(except for theio
directory) toastro/astro/src/main/java
. Merge as necessary. - Copy the contents of
cordova-plugin-test/platforms/android/libs
toastro/astro/libs
. - Copy
cordova_plugins.js
,cordova.js
, andplugins
fromcordova-plugin-test/platforms/android/assets/www
toastro/demo/src/main/assets
. - Use your creativity to merge the contents of
cordova-plugin-test/platforms/android/AndroidManifest.xml
toastro/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 incordova.js
andcordova_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 itwww
- Create a group within
Cordova
namedPlugins
- Open
cordova-plugin-test/platforms/ios/www
in Finder - Drag
cordova-plugin-test/platforms/ios/www/cordova_plugins.js
into thewww
- If you have existing plugins, you'll need to merge the
cordova_plugins.js
file.
- If you have existing plugins, you'll need to merge the
- Drag
cordova-plugin-test/platforms/ios/platform_www/cordova.js
into thewww
- 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 theCordova
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 sourceconfig.xml
- If you have existing plugins installed, you will need to merge
- Drag the folder named after your plugin (eg.
com.manateeworks.barcodescanner
) fromcordova-plugin-test/platforms/ios/HelloCordova/Plugins/
intoCordova/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}/
- Eg.
- 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.