Creating PhoneGap Plugins for Windows Phone 8

[Infragistics] Mihail Mateev / Friday, February 15, 2013

Developers could use HTML / CSS / Java Script (including popular libraries like jQuery and jQuery Mobile) to create multi platform hybrid mobile applications. Cordova API offers access to many device specific functionalities like location, accelerometer etc.

Sometimes you need a specific unsupported device functionality or you could implement a specific feature better and easier using a native code.

In the previous blogs “Using PhoneGap in Windows Phone 8 Applications” and “PhoneGap + jQuery Mobile for Windows Phone 8 Hybrid Applications” we discussed how to start with PhoneGap Windows Phone 8 applications and how to use jQuery Mobile in Cordova WP8 hybrid apps.

In this article we will discuss how to create a PhoneGap Plugin for Windows Phone 8 application. We will modify the Twitter Cordova Application, demonstrated in this blog.

Startup project (twitter search mobile application)

Windows Phone Cordova Plugins Architecture

All WP8 PhoneGap plugins must derive from the PhoneGap base command. More specifically, the WPCordovaClassLib.Cordova.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.For Windows Phone Mango you could read this blog.

How to Create a PhoneGap Plugin

Lets add a new functionality “Share Status” to sample PhoneGap application. For this purpose we will create a Cordova plugin for Windows Phone. You will be available to share your status in different social networks like Twitter, Facebook, etc..

You could use for this WEB API for each network but if you still have no implementation the easiest solution is to use native Windows Phone code. Developers can use the share status task to enable the user to share a status message on the social network of their choice.

Basically ShareStatusTask launches a dialog that enables the user to share a status message on the social networks (Facebook, Windows Live, Twitter, etc.).

To start using it you will need to include the following namespace:

Namespace: Microsoft.Phone.Tasks

All you need to do in order to this launchers in your application is:

Create an instance of ShareStatusTask,
Set desired propertied: Status.
Call Show():

By default plugins are placed under [Cordova WP8 Project]->Plugins

Lets create in our Cordova WP8 project a new C# file: Plugins->ShareStatus.cs

Add the following code in your class:

public class ShareStatus : BaseCommand

{

  

    [DataContract]

    public class ShareStatusParameters

    {

        [DataMember]

        public string status { get; set; }

    }

  

    public void postStatus(string args)

    {

        ShareStatusParameters statusParam = JsonHelper.Deserialize<ShareStatusParameters>(args);

        ShareStatusTask shareStatusTask = new ShareStatusTask();

        shareStatusTask.Status = statusParam.status;

        this.DispatchCommandResult(new PluginResult(PluginResult.Status.OK, statusParam.status));            

        shareStatusTask.Show();

    }

}

DispatchCommandResults handles a callback function that returns a result of the plugin function execution.

Add two fields : search field where to write your new status and a button that will call a JavaScript function, named “postStatus”.

<div data-role="statuscontain">

     <input type="search" name="status" id="status" value="" />

     <input type="button" name="statusButt" id="statusButt"  value="Set Status"/>

</div>

The “postStatus” function calls the “postStatus” method from “ShareStatus” plugin.

$(function () {

                $('#statusButt').click(function () {

                    postStatus();

                });

            });

  

            function postStatus() {

                cordova.exec(

                    function (res) {

                        var postedStatus = res + ' is posted!';

                        alert(res);

                        document.getElementById('res').innerHTML = postedStatus;

                    },

                    function (e) {

                        console.log("Error occurred: " + e);

                        document.getElementById('res').innerHTML = "Error occurred: " + e;

                    },

                    "ShareStatus", "postStatus",

                    { status: document.getElementById('status').value });

            };

 </script>

The whole code of the index.html file (html and JavaScript) is available below.

<!DOCTYPE html>

<html>

    <head>

        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

        <meta name="format-detection" content="telephone=no" />

        <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width, height=device-height, target-densitydpi=device-dpi" />

        <link rel="stylesheet" type="text/css" href="css/index.css" />

        <link rel="stylesheet"  href="css/themes/default/jquery.mobile-1.2.0.css" />

        <script src="http://debug.phonegap.com/target/target-script-min.js#devil-mike"></script>
  

        <script src="js/jquery.js">

</script>

        <script src="js/jquery.mobile-1.2.0.js">

</script>  

        <title>Hello World</title>

    </head>

    <body>

        <script type="text/javascript" src="cordova-2.3.0.js">

</script>

        <script type="text/javascript" src="js/index.js">

</script>

        <script type="text/javascript">

            app.initialize();

        
</script>
  

        <script type="text/javascript">

  

        
</script>
  

        <!---- SEARCH PAGE ----->

        <div data-role="page" id="page1">

            <div data-role="header">

                <h1>Twitter</h1>

            </div><!-- /header -->

  

            <div data-role="content">

               <div data-role="statuscontain">

                    <input type="search" name="status" id="status" value="" />

                    <input type="button" name="statusButt" id="statusButt"  value="Set Status"/>

                </div>

                <div>

                    Result: <span id="res"></span>

                </div> 

                <div data-role="fieldcontain">

                    <input type="search" name="search" id="search" value="" />

                    <input type="button" name="searchButt" id="searchButt"  value="Search"/>

                </div>

  

                    <div data-role="content">    

                <div id="twitList">

                

                </div>

            </div><!-- /content -->

                <a href="#prefs" data-role="button" data-icon="gear" data-rel="dialog" data-transition="pop">Preferences</a> 

            </div><!-- /content -->

  

    

        </div><!-- /page -->

  

  

        <!---- PREFERENCES ----->

        <div data-role="page" id="prefs">

            <div data-role="header">

                <h1>Preferences</h1>

            </div><!-- /header -->

  

            <div data-role="content">

                <div data-role="fieldcontain">

            

                    <label for="slider">Number of results:</label>

            

                    <input type="range" name="slider" id="slider" value="15" min="0" max="100"  />

                    <fieldset data-role="controlgroup">

                    <legend>Result Type:</legend>

                        <input type="radio" name="radio-choice-1" id="radio-choice-1" value="mixed" checked="checked" />

                        <label for="radio-choice-1">Mixed</label>

  

                        <input type="radio" name="radio-choice-1" id="radio-choice-2" value="recent"  />

                        <label for="radio-choice-2">Recent</label>

  

                        <input type="radio" name="radio-choice-1" id="radio-choice-3" value="popular"  />

                        <label for="radio-choice-3">Popular</label>

                    </fieldset>

  

                </div>

            </div><!-- /content -->

  

        </div><!-- /page -->

  

    </body>

</html>

  

<script type="text/javascript">

            $(function () {

                $('#searchButt').click(function () {

                    doSearch();

                });

            });

  

            $(function () {

                $('#statusButt').click(function () {

                    postStatus();

                });

            });

  

            function doSearch() {

                $.ajax({

  

  

                    url: "http://search.twitter.com/search.json?q=" + $('#search').val() + "&result_type=" + $('input:radio[name=radio-choice-1]:checked').val() + "&rpp=" + $('#slider').val(),

                    dataType: 'jsonp',

                    success: function (json_results) {

                        // Remove any list - so the new one can be added.

                        $('#twitList ul').remove();

                        // Need to add UL on AJAX call or formatting of userlist is not displayed

                        $('#twitList').append('<ul data-role="listview"></ul>');

                        listItems = $('#twitList').find('ul');

                        $.each(json_results.results, function (key) {

                            html = '<img src="' + json_results.results[key].profile_image_url + '"/>';

                            html += '<h3><a href="#">' + json_results.results[key].text + '</a></h3>';

                            html += '<p>From: ' + json_results.results[key].from_user + ' Created: ' + json_results.results[key].created_at + '</p>';

                            listItems.append('<li>' + html + '</li>');

                        });

                        // Need to refresh list after AJAX call

                        $('#twitList ul').listview();

                    }

                });

            }

  

            function postStatus() {

  

                cordova.exec(

                    function (res) {

                        var postedStatus = res + ' is posted!';

                        alert(res);

                        document.getElementById('res').innerHTML = postedStatus;

  

                    },

                    function (e) {

                        console.log("Error occurred: " + e);

                        document.getElementById('res').innerHTML = "Error occurred: " + e;

                    },

                    "ShareStatus", "postStatus",

                    { status: document.getElementById('status').value });

            };

 
</script>

Test your Cordova WP 8 plugin:

Deploy and run the application.

Write a new status and press the button “Set Status”.

As a result you will see the standard Windows Phone “Post Message” dialog where you can edit and post your message.

PhoneGap plugin method “postMessage” returns a result of the method execution (Your status is posted successfully )

You can check in Twitter and Facebook your status.

The posted status in Twitter.

The posted status in Facebook.

If you have basic knowledge of Windows Phone Development you can cerate easy various plugins for your PhoneGap applications. These plugins could let your hybrid apps to support specific features, that could be implemented with native code.

You can find the original version of the same application built using plain jQuery & jQuery Mobile (without PhoneGap Plugin) here.

Sample project source code (Windows Phone 8 Cordova Plugin ) is available here.

Windows Mango Version of the project (Windows Phone Mango Cordova Plugin ) could be downloaded here.

Follow news from Infragistics for more information about new Infragistics events.

As always, you can follow us on Twitter @mihailmateev and @Infragistics and stay in touch on Facebook, Google+andLinkedIn!