[4/5] docs commit: updated WP7 plugin guide

[pu...@apache.org]

updated WP7 plugin guide


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

Branch: refs/heads/master
Commit: 621b6818e5b823d0e9463e98e43dba3f8e52ba46
Parents: 5ff2411
Author: Jesse MacFadyen <pu...@gmail.com>
Authored: Wed Jul 25 15:57:15 2012 -0700
Committer: Jesse MacFadyen <pu...@gmail.com>
Committed: Wed Jul 25 15:57:15 2012 -0700

----------------------------------------------------------------------
 .../plugin-development/windows-phone/index.md      |  167 +++++++++++----
 1 files changed, 123 insertions(+), 44 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/621b6818/docs/en/edge/guide/plugin-development/windows-phone/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/plugin-development/windows-phone/index.md b/docs/en/edge/guide/plugin-development/windows-phone/index.md
index d8c5d40..5c8c119 100644
--- a/docs/en/edge/guide/plugin-development/windows-phone/index.md
+++ b/docs/en/edge/guide/plugin-development/windows-phone/index.md
@@ -20,87 +20,166 @@ license: Licensed to the Apache Software Foundation (ASF) under one
 Developing a Plugin on Windows Phone
 ====================================
 
-Writing a plugin for Cordova on Windows Phone requires a basic understanding of the architecture of Cordova. Cordova-WP7 consists of a WebBrowser which hosts the application javascript code and manages native API calls. There is a BaseCommand class in C# which you can extend, and it comes with the majority of the 'plumbing' built for you already.
+Writing a plugin for Cordova on Windows Phone requires a basic understanding of the architecture of Cordova. Cordova-WP7 consists of a WebBrowser which hosts the application javascript code and manages native API calls. There is a BaseCommand _(fully qualified: WP7CordovaClassLib.Cordova.Commands.BaseCommand)_ class in C# which you can extend, and it comes with the majority of the 'plumbing' built for you already.
 
 
+1. Select your project, and right click choose 'Add -> New Item ...'
+   - Preferably add it to the 'Plugins' folder, but it is up to you
+2. Select 'Class' and name it Echo.cs
+   - The name of this class must EXACTLY match what you call into cordova.exec(win,fail,"Echo",...)
+3. Include the base classes implementation
 
+   using WP7CordovaClassLib.Cordova;
+   using WP7CordovaClassLib.Cordova.Commands;
+   using WP7CordovaClassLib.Cordova.JSON;
 
+4. Extend your class from BaseCommand 
+
+   public class Echo : BaseCommand 
+   {
 
-Select your project, and right click choose 'Add -> New Item ...'
-- Preferably add it to the 'Plugins' folder, but it is up to you
-Select 'Class' and name it Echo.cs
-The name of this class must EXACTLY match what you call into cordova.exec(win,fail,"Echo",...)
 
+   }
 
+5. Add a method that is callable from JS
 
-Include the base classes implementation :
-using WP7CordovaClassLib.Cordova;
-using WP7CordovaClassLib.Cordova.Commands;
-using WP7CordovaClassLib.Cordova.JSON;
+	public class Echo : BaseCommand
+	{
+		public void echo(string options)
+		{
+			// all JS callable plugin methods MUST have this signature!
+			// public, returning void, 1 argument that is a string
+		}
+	}
+	
 
-Extend your class from BaseCommand 
+Namespaces
+===
 
 The default namespace for unqualified commands is :
-namespace Cordova.Extension.Commands
+
+	namespace Cordova.Extension.Commands 
+	{
+
+	}
 
 If you would like to use your own namespace, you will need to make a fully qualified call to cordova.exec
-C#
-namespace com.mydomain.cordovaExtensions {...}
-JS
-codova.exec(win,fail,"com.mydomain.cordovaExtensions.Echo",...);
+For example, if you wanted to define your C# class like this :
 
-Passing results from C# to JS 
-===
+	namespace com.mydomain.cordovaExtensions 
+	{ 
+		public class Echo : BaseCommand 
+		{ 
 
-DispatchCommandResult(); // calls back with an empty plugin result, considered a success callback
+		} 
+	}
 
-If you need to signal that an error has occured, you can call DispatchCommandResult with a PluginResult object.
-DispatchCommandResult(new PluginResult(PluginResult.Status.ERROR, "Echo signalled an error"));
+Then, in JS you would need to call exec like this :
 
-Interpretting your arguments
+	codova.exec(win,fail,"com.mydomain.cordovaExtensions.Echo",...);
+
+
+Interpretting your arguments in C#
 ===
 
-The data received by your plugin method is a string value, but in actuallality we our intention was to pass an array of strings.  Looking back at our JS call to cordova.exec, we see we passed [str]
-cordova.exec( win, fail, "Echo", "echo", ["input string"]); 
+The data received by your plugin method is a string value, but in actuallality looking at our JavaScript code, we see our intention was to pass an array of strings.  Looking back at our JS call to cordova.exec, we see we passed [str]
+
+	cordova.exec( win, fail, "Echo", "echo", ["input string"]); 
 
 If we inspect the options string passed in to our Echo.echo method, we will see that the value is actually:
-"[\"input string\"]"
+
+	"[\"input string\"]"
 
 All javascript exec arguments are JSON encoded before being passed into C#.
 
 If we want to treat this as the string we were expecting, we need to decode it.
 We can use simple JSON deserialization.
 
-string optVal = JsonHelper.Deserialize<string[]>(options)[0];
-// optVal now has the value of "input string"
+	string optVal = JsonHelper.Deserialize<string[]>(options)[0];
+	// optVal now has the value of "input string"
+
 
-Handling serialization errors
+Passing results from C# to JS 
+===
+
+The base class BaseCommand provides methods for passing data to your JS callback handlers.
+To simply signal that the command has succeeded, when no additional result info is needed, you can can simply call :
+
+	DispatchCommandResult(); // calls back with an empty plugin result, considered a success callback
+
+To pass data back, you will need to call a different version of DispatchCommandResult :
+
+	DispatchCommandResult(new PluginResult(PluginResult.Status.OK, "Everything went as planned, this is a result that is passed to the success handler."));
+
+To pass structured object data back to JS, it should be encoded as a JSON string :
+
+	DispatchCommandResult(new PluginResult(PluginResult.Status.OK, "{result:\"super awesome!\"}"));
+
+If you need to signal that an error has occured, you can call DispatchCommandResult with a PluginResult object.
+
+	DispatchCommandResult(new PluginResult(PluginResult.Status.ERROR, "Echo signalled an error"));
+
+
+Handling serialization errors in your plugin's C# method
 ===
 
 When interpretting your arguments, it is a good idea to use a try/catch block in case we have bad input.
 This is a pattern used throughout the Cordova C# code :
+	
+	string optVal = null;
+	
+	try 
+	{
+		optVal = JsonHelper.Deserialize<string[]>(options)[0];
+	}
+	catch(Exception)
+	{
+		// simply catch the exception, we will handle null values and exceptions together
+	}
+	
+	if(optVal == null)
+	{
+		DispatchCommandResult(new PluginResult(PluginResult.Status.JSON_EXCEPTION));
+	}
+	else
+	{
+		// ... continue on to do our work
+	}
+
+
+
+
+Advanced Plugin Functionality
+===
 
+See other methods that you can override in:
 
-   string optVal = null;
+1. [BaseCommand.cs](https://github.com/apache/incubator-cordova-wp7/blob/master/templates/standalone/cordovalib/Commands/BaseCommand.cs)
 
-   try 
-   {
-      optVal = JsonHelper.Deserialize<string[]>(options)[0];
-   }
-   catch(Exception)
-   {
-      // simply catch the exception, we will handle null values and exceptions together
-   }
+For example, you can hook into the 'pause' and 'resume' application events.
 
-   if(optVal == null)
-   {
-      DispatchCommandResult(new PluginResult(PluginResult.Status.JSON_EXCEPTION));
-   }
-   else
-   {
-      // ... continue on to do our work
-   }
+## Debugging Plugins
+
+To debug the C# side, you can use Visual Studio's debugger, just set a break point at any of the methods exposed by your class.
+
+Javascript is a little more difficult to debug on Windows Phone, you will need to use console.log to output the state of your plugin, or inform yourself of errors.
+
+Common Pitfalls
+===
+
+1. Be careful when deciding on the arguments you pass to native in your JavaScript implementation.  Most device platforms expect the args passed to cordova.exec to be an array, but if you have different types of objects in this array, it becomes difficult or impossible to deserialize.
+
+	cordova.exec(win,fail,"ServiceName","MethodName",["this is a string", 54, {literal:'trouble'}]);
+
+This will mean that your C# code will receive a string value of "[\"this is a string\",54,{literal:'trouble'}]" which is difficult to decode.
+
+Consider converting ALL parameters to strings before calling exec :
+
+	cordova.exec(win,fail,"ServiceName","MethodName",["this is a string", "54", "{literal:'trouble'}"])	;
+	
+	string[] optValues = JsonHelper.Deserialize<string[]>(options);
 
+2. It is usually a good idea to do parameter checking in your JavaScript code, before you call exec.  This will let you re-use more JS code between different native implementations of your plugin.