In our previous blogpost we showed how our Android plugin was packaged as a PhoneGap plugin. In this blogpost we will show how we have packaged our iOS plugin for PhoneGap and how you can use this plugin in your own PhoneGap project.
Don’t want to think about this? Get started with geofencing without a hassle! |
|
Our Cordova/PhoneGap plugin is written for version 3.0.0 and is available under an open source license on GitHub.
Update January 8th 2014: We have updated this post after the release of version 1.5.0 of our iOS plugin.
About Cordova/PhoneGap
Apache Cordova and Adobe PhoneGap provide a way for developers to develop apps for all major platforms in HTML, CSS and JavaScript. Developers only have to maintain a single codebase for all platforms. The project started out as PhoneGap and when it was acquired by Adobe the code was released as Apache Cordova. Currently the only difference between Apache Cordova and Adobe PhoneGap is the name. Native libraries (such as our Plot library) can be used by writing a plugin which makes it available to JavaScript.
Creating the Plugin
To ensure you only need to install one plugin for both Android and iOS, the plugin makes use of the same js-module.
The native part, written in Objective C, is specific for iOS. To start you create a class that extends from CDVPlugin.
The plugin mechanism doesn’t provide an easy mechanism to capture the launchOptions which are passed to the AppDelegate’s didFinishLaunching: method. Therefore we added an observer for the UIApplicationDidFinishLaunchingNotification notification when the class is loaded.
+(void)load {
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(didFinishLaunching:)
name:UIApplicationDidFinishLaunchingNotification
object:nil];
}
+(void)didFinishLaunching:(NSNotification*)notification {
launchOptions = notification.userInfo;
if (launchOptions == nil) {
//launchOptions is nil when not start because of notification or url open
launchOptions = [NSDictionary dictionary];
}
}
In Android it is necessary to specify an execute method, but in iOS this isn’t required. You can just add methods to the class in the form “-(void)methodName:(CDVInvokedUrlCommand*)command” and then you can access them from the JavaScript code. The command parameter provides access to the arguments passed and gives access to the callbackId needed to return the result of the command.
CDVPluginResult* pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK];
[self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
When the native code was written, we extended our plugin.xml to allow automatic installation of our plugin. We added directives to plugin.xml to copy the source, header and library files. We didn’t add the directives to copy the updated configuration, since there is a bug (https://issues.apache.org/jira/browse/CB-4731) in Cordova preventing this from working correctly. This means you have to do it manually later.
<config-file target="config.xml" parent="/*">
<feature name="PlotCordovaPlugin">
<param name="ios-package" value="PlotCordovaPlugin" />
</feature>
</config-file>
<!--Copy the native files:-->
<header-file src="src/ios/PlotCordovaPlugin.h" />
<source-file src="src/ios/PlotCordovaPlugin.m" />
<header-file src="src/ios/Plot.h" />
<source-file src="src/ios/libPlot-1_4_1.a" framework="true" />
<!--Link with SQLite Framework-->
<framework src="libsqlite3.dylib" />
Using the Plugin
Starting from version 3.0.0 of Phonegap, it is made much easier to install plugins. When you already have installed this plugin for usage with Android, you don’t have to install this plugin again. It works for both platforms at the same time. You only have to link to where the plugin can be downloaded and Phonegap will install the plugin for you.
You can add Plot to your existing project by running:
phonegap local plugin add https://github.com/Plotprojects/plot-phonegap-plugin
and adding the following code to the html page that gets loaded first (often index.html):
<script type="text/javascript">
document.addEventListener("deviceready", deviceReady, true);
function deviceReady() {
var plot = cordova.require("cordova/plugin/plot");
var config = plot.exampleConfiguration;
config.publicKey = "REPLACE_ME"; //put your public key here
plot.init(config);
}
</script>
Conclusion
It’s actually quite easy to make a library available to Cordova/PhoneGap users. Just as it was for Android, exposing your iOS code only requires a small amount of code to create the plugin. For the end user that will be using the plugin it is very easy with the latest PhoneGap version. Just run one command and you’re done.
Resources
PhoneGap Plugin Github Project
PhoneGap Plugin Development Guide
PhoneGap Plugin (XML) Specification
PhoneGap iOS Plugins
Plot Library documentation
Don’t want to think about this? Get started with geofencing without a hassle! |
|