Introduction

This is a Step by Step Tutorial for iOS PhoneGap Plugin. If you are new to PhoneGap please refer to this documentation. In case you are new to the concept of PhoneGap plugins, please refer to this documentation.

Creating PhoneGap Plugin Project (using PhoneGap 1.5.0)

This simple project demonstrates how to implement and use Phonegap plugins on iOS.

Here we have a method called "print" which will evaluate the user sent data to "HelloWorld" If the User sent HelloWorld string

It will output it to the SuccessFunction If not it will output it to the FailureFunction.

You can also refer to the example of Barcode scanner (https://github.com/purplecabbage/phonegap-plugins/tree/master/iPhone)

So lets get started..

Implement Plugin Class

We will define a Class in Objective C called "MyClass".

Steps

            1. Implement a Class which extends CDVPlugin

//
//  MyClass.h
//
//  Created by Nimish Nayak on 08/08/2011. 
//  Copyright 2011 Nimish Nayak. All rights reserved.
#import <Foundation/Foundation.h>
#import <Cordova/CDVPlugin.h>
  

@interface MyClass : CDVPlugin {
    
     NSString* callbackID;  

 }

@property (nonatomic, copy) NSString* callbackID;

// Instance Method  

- (void) print:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options;
 

@end
 
 

//
//  MyClass.m
//  

     // Created by Nimish Nayak on 08/08/2011. 
     // Copyright 2011 Nimish Nayak. All rights reserved.
      
     #import "MyClass.h" 
          
     @implementation MyClass 

     @synthesize callbackID;

     -(void)print:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options  
     {
               // The first argument in the arguments parameter is the callbackID.
               // We use this to send data back to the successCallback or failureCallback
               // through PluginResult.   
               self.callbackID = [arguments pop];

               // Get the string that javascript sent us 
               NSString *stringObtainedFromJavascript = [arguments objectAtIndex:0];                 

               // Create the Message that we wish to send to the Javascript

               NSMutableString *stringToReturn = [NSMutableString stringWithString: @"StringReceived:"];
 

               // Append the received string to the string we plan to send out        

               [stringToReturn appendString: stringObtainedFromJavascript];
 

               // Create Plugin Result 

               CDVPluginResult* pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK
                      messageAsString: [stringToReturn stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding]];
 

               // Checking if the string received is HelloWorld or not

               if ([stringObtainedFromJavascript isEqualToString:@"HelloWorld"]==YES)

               {

                      // Call  the Success Javascript function

                      [self writeJavascript: [pluginResult toSuccessCallbackString:self.callbackID]];

               } else

               {    

                      // Call  the Failure Javascript function

                      [self writeJavascript: [pluginResult toErrorCallbackString:self.callbackID]];

                }

      }

      @end

Implement Plugin JavaScript

Steps

1. Create a class (Here: MyPlugin)
2. Add a function in it using prototype (Here: nativeFunction) 
3. In this function call PhoneGap.exec(<<successCallback>>, <<failureCallback>>, <<Plugin Name>>, <<Action Name>>, <<Arguments Array>>);
4. Finally, we have to initiate PhoneGap framework and include MyPlugin instance as a plugin.

The resulting code looks like this: 

/**
 * MyPlugin.js
 *  
 * Phonegap MyPlugin Instance plugin
 * Copyright (c) Nimish Nayak 2011
 *
 */
var MyPlugin = {
     nativeFunction: function(types, success, fail) {
          return PhoneGap.exec(success, fail, "MyPlugin", "print", types);
     }
};
  

Edit Cordova.plist

     You may be wondering what "MyPlugin" in the code snippet above means.

     Edit Cordova.plist and create a new entry in the "Plugins" section as follows:

          Key:     MyPlugin       This is the name of the plugin you can use from Javascript. 

          Type:   String             This is quite Obvious

          Value:  MyClass         The name of your Objective-C Class

Using the plugin

     Testing the plugin is very simple, use this example code:

   MyPlugin.nativeFunction(
      ["HelloWorld"],
      function(result) {
           alert("Success : \r\n"+result);      
      },
      function(error) {
           alert("Error : \r\n"+error);      
      }
  );  
 

Packaging the plugin

Zip up the .m, .h and .js files. That's about it.