Plugins for PhoneGap + Windows Phone Mango

Plugins for PhoneGap + Windows Phone Mango

We recently added plugin support to WP7 PhoneGap apps. I will outline here what you need to do to start extending the functionality for WP7 PhoneGap projects.

All WP7 PhoneGap plugins must derive from the PhoneGap base command. More specifically, the WP7GapClassLib.PhoneGap.Commands.BaseCommand class.
Plugin commands are dealt with generically throughout the framework, and base command provides the base interface for you to pass data back to JavaScript. This approach also prevents JavaScript code from calling arbitrary native code.

I recently posted a plugin titled PGSimpleShare to my GitHub repo. You can clone/fork it here : https://github.com/purplecabbage/phonegap-plugins/tree/master/WindowsPhone/PGSocialShare

The PGSimpleShare allows for simple updates to share links and status updates on social networks. Windows Phone Mango includes accounts for popular social networks, and the updated SDK provides a simple way to post data to them. The PGSimpleShare plugin exposes this same functionality to JavaScript running in a PhoneGap application. When you call this plugin to share a statusUpdate, the user will be presented with a native dialog previewing the update and allowing them to choose which networks they want to post it to. On my phone I see Facebook, Twitter, LinkedIn, and Window’s Live, all updated simultaneously ( as far as my code is concerned )

Plugins provide their interface to the application via some JavaScript code, this is done as expected inside a js file. Here is some JS for a simple plugin, taken from the recent PGSocialShare plugin I posted on GitHub:
To call your native side implementation, simply call PhoneGap.exec(winCallbackFunction, failCallbackFunction, pluginName, methodName, argsObj); The WP7 version of PhoneGap.exec will do the work of managing your callbacks if supplied, as well as turning the argsObj into a JSON object that can be passed to your native code. In the case of the shareStatus function defined above, the framework, on the native side will look for a class named PGSocialShare. ( fully qualified: WP7GapClassLib.PhoneGap.Commands.PGSocialShare ) When it finds this class it will instantiate it if it hasn’t already, then it will attempt to call the ‘share’ method on it. Here is a portion of the native implementation of the ‘share’ function :

Note the implementation of the share function is public, returns void, and expects 1 string argument, this is currently the signature for ALL plugin methods that are callable via the framework.

The above code then continues on to deserialize the JSON representation of the arguments it is expecting via a data-contract. See the full source code for details on this.
Based on the shareType passed in, we will call another method in our class; namely ‘shareStatus’.
This method then proceeds to pass the status message on to the SDK ShareStatusTask. There is no return value from the native SDK’s ShareStatusTask, so we have no way of knowing if the user cancelled it, or which networks they chose to post the status to. PGSocialShare::shareStatus then calls DispatchCommandResult which is defined by WP7GapClassLib.PhoneGap.Commands.BaseCommand, and will signal to JavaScript that the call has succeeded. In cases where we need to pass back some data, or signal an error condition vs a success, we can use the PluginResult`s enum of statuses ( statii ? )
We can also signal that we want JavaScript to keep our callback, for cases where we are monitoring sensor data, like the Accelerometer command.

Hopefully this is enough for everyone to get started developing plugins for Windows Phone! Also, I have attempted to keep PGSocialShare device-agnostic in the definition of the methods, so hopefully we will see the same plugin implemented on other devices as well. I look forward to your comments, questions, and critriques!

Cheers,
Jesse

    No Twitter Messages