Return-Path: X-Original-To: apmail-incubator-callback-commits-archive@minotaur.apache.org Delivered-To: apmail-incubator-callback-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id A1AACD4EF for ; Sat, 25 Aug 2012 00:00:51 +0000 (UTC) Received: (qmail 66462 invoked by uid 500); 25 Aug 2012 00:00:49 -0000 Delivered-To: apmail-incubator-callback-commits-archive@incubator.apache.org Received: (qmail 66342 invoked by uid 500); 25 Aug 2012 00:00:49 -0000 Mailing-List: contact callback-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: callback-dev@incubator.apache.org Delivered-To: mailing list callback-commits@incubator.apache.org Received: (qmail 65301 invoked by uid 99); 25 Aug 2012 00:00:47 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 25 Aug 2012 00:00:47 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id 63BF81FEF8; Sat, 25 Aug 2012 00:00:47 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: anis@apache.org To: callback-commits@incubator.apache.org X-Mailer: ASF-Git Admin Mailer Subject: [40/50] [abbrv] docs commit: [CB-1165] (actual) Update Plugin Dev Guide for new iOS plugin signature (old one still supported, but deprecated) Message-Id: <20120825000047.63BF81FEF8@tyr.zones.apache.org> Date: Sat, 25 Aug 2012 00:00:47 +0000 (UTC) [CB-1165] (actual) Update Plugin Dev Guide for new iOS plugin signature (old one still supported, but deprecated) Project: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/commit/e6aa4746 Tree: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/tree/e6aa4746 Diff: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/diff/e6aa4746 Branch: refs/heads/master Commit: e6aa4746d53a349d742e682851130ee49fc070bf Parents: 2bd8758 Author: Shazron Abdullah Authored: Thu Aug 2 19:35:47 2012 -0700 Committer: Anis Kadri Committed: Fri Aug 24 16:59:38 2012 -0700 ---------------------------------------------------------------------- docs/en/edge/guide/plugin-development/ios/index.md | 62 +++++++++----- 1 files changed, 40 insertions(+), 22 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/e6aa4746/docs/en/edge/guide/plugin-development/ios/index.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/guide/plugin-development/ios/index.md b/docs/en/edge/guide/plugin-development/ios/index.md index a39d4f8..4d1891d 100644 --- a/docs/en/edge/guide/plugin-development/ios/index.md +++ b/docs/en/edge/guide/plugin-development/ios/index.md @@ -31,8 +31,6 @@ The JavaScript portion of a plugin always uses the `cordova.exec` method as foll This will marshall a request from the UIWebView to the iOS native side, more or less boiling down to calling the `action` method on the `service` class, with the arguments passed in the `args` Array. -The `options` parameter for the Objective-C plugin method is being deprecated, and it should not be used. For legacy reasons - the last JavaScript object passed in the `args` Array will be passed in as the `options` dictionary of the method in Objective-C. You must make sure that any JavaScript object that is passed in as an element in the `args` array occurs as the last item in the Array, if not it will throw off the array index of all subsequent parameters of the Array in Objective-C. Only one JavaScript object is supported for the options dictionary, and only the last one encountered will be passed to the native method. It is because of these error-prone reasons that they are being deprecated. - The plugin must be added to `Plugins` key (a Dictionary) of the `Cordova.plist` file in your Cordova-iOS application's project folder. service_name @@ -44,32 +42,45 @@ The key `service_name` should match what you use in the JavaScript `exec` call, We have JavaScript fire off a plugin request to the native side. We have the iOS Objective-C plugin mapped properly via the `Cordova.plist` file. So what does the final iOS Objective-C Plugin class look like? -What gets dispatched to the plugin via JavaScript's `exec` function gets passed into the corresponding Plugin class's `action` method. Most method implementations look like this: +What gets dispatched to the plugin via JavaScript's `exec` function gets passed into the corresponding Plugin class's `action` method. A plugin method has this signature: - - (void) myMethod:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options + - (void) myMethod:(CDVInvokedUrlCommand*)command { - NSString* callbackId = [arguments objectAtIndex:0]; - CDVPluginResult* pluginResult = nil; NSString* javaScript = nil; @try { - NSString* myarg = [arguments objectAtIndex:1]; + NSString* myarg = [command.arguments objectAtIndex:0]; if (myarg != nil) { pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK]; - javaScript = [pluginResult toSuccessCallbackString:callbackId]; + javaScript = [pluginResult toSuccessCallbackString:command.callbackId]; } } @catch (id exception) { pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_JSON_EXCEPTION messageAsString:[exception reason]]; - javaScript = [pluginResult toErrorCallbackString:callbackId]; + javaScript = [pluginResult toErrorCallbackString:command.callbackId]; } [self writeJavascript:javaScript]; } +1. [CDVInvokedUrlCommand.h](https://github.com/apache/incubator-cordova-ios/blob/master/CordovaLib/Classes/CDVInvokedUrlCommand.h) +2. [CDVPluginResult.h](https://github.com/apache/incubator-cordova-ios/blob/master/CordovaLib/Classes/CDVPluginResult.h) + + +## Plugin Signatures + +The **new signature** supported beginning in **Cordova 2.1.0** is: + + - (void) myMethod:(CDVInvokedUrlCommand*)command; + +The **old (deprecated)** signature is: + + - (void) myMethod:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options; -### Echo Plugin iOS Plugin +Basically, the options dictionary has been removed for the new signature, and the callbackId is not the 0th index item for the arguments array, but it is now in a separate property. + +## Echo Plugin iOS Plugin We would add the following to the `Plugins` key (a Dictionary) of the project's `Cordova.plist` file: @@ -81,41 +92,39 @@ application folder: /********* Echo.h Cordova Plugin Header *******/ - #import + #import @interface Echo : CDVPlugin - - (void) echo:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options; + - (void) echo:(CDVInvokedUrlCommand*)command; @end /********* Echo.m Cordova Plugin Implementation *******/ #import "Echo.h" - #import + #import @implementation Echo - - (void) echo:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options + - (void) echo:(CDVInvokedUrlCommand*)command { - NSString* callbackId = [arguments objectAtIndex:0]; - CDVPluginResult* pluginResult = nil; NSString* javaScript = nil; @try { - NSString* echo = [arguments objectAtIndex:1]; + NSString* echo = [command.arguments objectAtIndex:0]; if (echo != nil && [echo length] > 0) { pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:echo]; - javaScript = [pluginResult toSuccessCallbackString:callbackId]; + javaScript = [pluginResult toSuccessCallbackString:command.callbackId]; } else { pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR]; - javaScript = [pluginResult toErrorCallbackString:callbackId]; + javaScript = [pluginResult toErrorCallbackString:command.callbackId]; } } @catch (NSException* exception) { pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_JSON_EXCEPTION messageAsString:[exception reason]]; - javaScript = [pluginResult toErrorCallbackString:callbackId]; + javaScript = [pluginResult toErrorCallbackString:command.callbackId]; } [self writeJavascript:javaScript]; @@ -126,7 +135,7 @@ application folder: Let's take a look at the code. At the top we have all of the necessary Cordova imports. Our class extends from `CDVPlugin` - very important. -This plugin only supports one action, the `echo` action. First, we grab the `callbackId` parameter, which is always the 0th item in the arguments array. Next, we grab the echo string using the `objectAtIndex` method on our `args`, telling it we want to get the 1st parameter in the arguments array. We do a bit of parameter checking: make sure it is not `nil`, and make sure it is not a zero-length string. +This plugin only supports one action, the `echo` action. First, we grab the echo string using the `objectAtIndex` method on our `args`, telling it we want to get the 0th parameter in the arguments array. We do a bit of parameter checking: make sure it is not `nil`, and make sure it is not a zero-length string. If it is, we return a `PluginResult` with an `ERROR` status. If all of those checks pass, then we return a `PluginResult` with an `OK` status, and pass in the `echo` string we received in the first place as a parameter. Then, we convert the `PluginResult` to JavaScript by calling either the `toSuccessCallbackString` (if it was OK) or `toErrorCallbackString` (if it was an error) methods. @@ -145,6 +154,8 @@ For example, you can hook into the pause, resume, app terminate and handleOpenUR To debug the Objective-C side, you would use Xcode's built in debugger. For JavaScript, you can use [Weinre, an Apache Cordova Project](https://github.com/apache/incubator-cordova-weinre) or [iWebInspector, a third-party utility](http://www.iwebinspector.com/) +For iOS 6, you would use Safari 6.0 to simply attach to your app running in the iOS 6 Simulator. + ## Common Pitfalls * Don't forget to add your plugin's mapping to Cordova.plist - if you forgot, an error will be printed to the Xcode console log @@ -154,4 +165,11 @@ To debug the Objective-C side, you would use Xcode's built in debugger. For Java setTimeout(function() { // do your thing here! }, 0); - \ No newline at end of file + +## Deprecated Plugin Signature Note + +The **old (deprecated)** signature is: + + - (void) myMethod:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options; + +The options parameter for the Objective-C plugin method is being deprecated, and it should not be used. For legacy reasons - the last JavaScript object passed in the args Array will be passed in as the options dictionary of the method in Objective-C. You must make sure that any JavaScript object that is passed in as an element in the args array occurs as the last item in the Array, if not it will throw off the array index of all subsequent parameters of the Array in Objective-C. Only one JavaScript object is supported for the options dictionary, and only the last one encountered will be passed to the native method. It is because of these error-prone reasons that they are being deprecated. \ No newline at end of file