incubator-callback-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From agri...@apache.org
Subject [2/2] docs commit: Update iOS plugin guide for changes in 2.2.0.
Date Sun, 21 Oct 2012 02:52:48 GMT
Update iOS plugin guide for changes in 2.2.0.

- [commandDelegate sendPluginResult] instead of [webView writeJavaScript]
- Add a section on threading.
- Remove mention of alert() causing dead-lock (we now think that's fixed)
Also, remove @try for exceptions. No core plugins have that, so it's
shouldn't be in the docs.

Bug: https://issues.apache.org/jira/browse/CB-1608


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/26bdfa75
Tree: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/tree/26bdfa75
Diff: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/diff/26bdfa75

Branch: refs/heads/master
Commit: 26bdfa75c0e429df107f8f543ecdebe45e1566c2
Parents: 5f6768f
Author: Andrew Grieve <agrieve@chromium.org>
Authored: Sat Oct 20 22:43:52 2012 -0400
Committer: Andrew Grieve <agrieve@chromium.org>
Committed: Sat Oct 20 22:43:52 2012 -0400

----------------------------------------------------------------------
 docs/en/edge/guide/plugin-development/ios/index.md |   82 +++++++--------
 1 files changed, 39 insertions(+), 43 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/26bdfa75/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 5d1b447..ab30d3a 100644
--- a/docs/en/edge/guide/plugin-development/ios/index.md
+++ b/docs/en/edge/guide/plugin-development/ios/index.md
@@ -46,39 +46,33 @@ We have JavaScript fire off a plugin request to the native side. We have
the iOS
 
 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:(CDVInvokedUrlCommand*)command
+    - (void)myMethod:(CDVInvokedUrlCommand*)command
     {
         CDVPluginResult* pluginResult = nil;
-        NSString* javaScript = nil;
-
-        @try {
-            NSString* myarg = [command.arguments objectAtIndex:0];
-
-            if (myarg != nil) {
-                pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK];
-                javaScript = [pluginResult toSuccessCallbackString:command.callbackId];
-            } 
-        } @catch (id exception) {
-            pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_JSON_EXCEPTION
messageAsString:[exception reason]];
-            javaScript = [pluginResult toErrorCallbackString:command.callbackId];
-        }
+        NSString* myarg = [command.arguments objectAtIndex:0];
 
-        [self writeJavascript:javaScript];
+        if (myarg != nil) {
+            pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK];
+        } else { 
+            pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Arg
was null"];
+        }
+        [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
     }
     
 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)
+3. [CDVCommandDelegate.h](https://github.com/apache/incubator-cordova-ios/blob/master/CordovaLib/Classes/CDVCommandDelegate.h)
 
   
 ## Plugin Signatures
 
 The **new signature** supported beginning in **Cordova 2.1.0** is:
 
-        - (void) myMethod:(CDVInvokedUrlCommand*)command;
+        - (void)myMethod:(CDVInvokedUrlCommand*)command;
 
 The **old (deprecated)** signature is:
 
-        - (void) myMethod:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options;
+        - (void)myMethod:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options;
 
 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. 
 
@@ -98,7 +92,7 @@ application folder:
 
     @interface Echo : CDVPlugin
 
-    - (void) echo:(CDVInvokedUrlCommand*)command;
+    - (void)echo:(CDVInvokedUrlCommand*)command;
 
     @end
     
@@ -109,27 +103,18 @@ application folder:
 
     @implementation Echo
 
-    - (void) echo:(CDVInvokedUrlCommand*)command
+    - (void)echo:(CDVInvokedUrlCommand*)command
     {
         CDVPluginResult* pluginResult = nil;
-        NSString* javaScript = nil;
-
-        @try {
-            NSString* echo = [command.arguments objectAtIndex:0];
-
-            if (echo != nil && [echo length] > 0) {
-                pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:echo];
-                javaScript = [pluginResult toSuccessCallbackString:command.callbackId];
-            } else {
-                pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR];
-                javaScript = [pluginResult toErrorCallbackString:command.callbackId];
-            }
-        } @catch (NSException* exception) {
-            pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_JSON_EXCEPTION
messageAsString:[exception reason]];
-            javaScript = [pluginResult toErrorCallbackString:command.callbackId];
+        NSString* echo = [command.arguments objectAtIndex:0];
+
+        if (echo != nil && [echo length] > 0) {
+            pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:echo];
+        } else {
+            pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR];
         }
 
-        [self writeJavascript:javaScript];
+        [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
     }
 
     @end
@@ -139,9 +124,25 @@ Let's take a look at the code. At the top we have all of the necessary
Cordova i
 
 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.
+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.
+
+Finally, we send the result to `self.commandDelegate`, which will execute the JavaScript
that will callback to success or failure callbacks of the exec method on the JavaScript side.
If the success callback was called, it will pass the `echo` parameter as a parameter.
+
+## Threading
+
+Although UIWebViews run on a dedicated thread, plugin methods are executed on the UI thread.
If your plugin requires a non-trivial amount of processing or requires a blocking call, you
should make use of a background thread. An example:
+
+    - (void)myPluginMethod:(CDVInvokedUrlCommand*)command
+    {
+        [self.commandDelegate runInBackground:^{
+            NSString* payload = nil;
+            // Some blocking logic...
+            CDVPluginResult* pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK
messageAsString:payload];
+            // sendPluginResult is thread-safe.
+            [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
+        }];
+    }
 
-Finally we write the JavaScript back to the UIWebView, which will execute the JavaScript
that will callback to success or failure callbacks of the exec method on the JavaScript side.
If the success callback was called, it will pass the `echo` parameter as a parameter.
 
 ## Advanced Plugin Functionality
 
@@ -154,7 +155,7 @@ For example, you can hook into the pause, resume, app terminate and handleOpenUR
 
 ## Debugging Plugins
 
-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/)
+To debug the Objective-C side, you would use Xcode's built in debugger. For JavaScript, on
iOS 5.0 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.
 
@@ -162,11 +163,6 @@ For iOS 6, you would use Safari 6.0 to simply attach to your app running
in the
 
 * 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
 * Don't forget to add any hosts you connect to in the [whitelist](guide_whitelist_index.md.html#Domain%20Whitelist%20Guide)
- if you forgot, an error will be printed to the Xcode console log
-* If you handle the resume event, and the app resumes, you can hang the app if you send out
a JavaScript call that executes a native function, like alerts. To be safe, wrap your JavaScript
call in a setTimeout call, with a timeout value of zero:
-
-        setTimeout(function() {
-            // do your thing here!
-        }, 0);
 
 ## Deprecated Plugin Signature Note
 


Mime
View raw message