You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by mw...@apache.org on 2012/07/30 23:58:53 UTC
docs commit: Fix Markdown formatting of Windows Phone Plugin Guide.
Updated Branches:
refs/heads/master d52d5424f -> 722ff972d
Fix Markdown formatting of Windows Phone 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/722ff972
Tree: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/tree/722ff972
Diff: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/diff/722ff972
Branch: refs/heads/master
Commit: 722ff972d5bb91dcd89d8c6428c79f47ddaf3b7c
Parents: d52d542
Author: Michael Brooks <mi...@michaelbrooks.ca>
Authored: Mon Jul 30 14:57:46 2012 -0700
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Jul 30 14:57:46 2012 -0700
----------------------------------------------------------------------
.../plugin-development/windows-phone/index.md | 193 ++++++++-------
1 files changed, 98 insertions(+), 95 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/722ff972/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 022a894..c33a54f 100644
--- a/docs/en/edge/guide/plugin-development/windows-phone/index.md
+++ b/docs/en/edge/guide/plugin-development/windows-phone/index.md
@@ -20,134 +20,133 @@ 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 _(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.
-
+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
+(`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",...)
+ - 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
+ using WP7CordovaClassLib.Cordova;
+ using WP7CordovaClassLib.Cordova.Commands;
+ using WP7CordovaClassLib.Cordova.JSON;
- public class Echo : BaseCommand
- {
+4. Extend your class from BaseCommand
-
- }
+ public class Echo : BaseCommand
+ {
+ // ...
+ }
5. Add a method that is callable from JS
- 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
- }
- }
-
+ 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
+ }
+ }
Namespaces
----------
-The default namespace for unqualified commands is :
-
- namespace Cordova.Extension.Commands
- {
+The default namespace for unqualified commands is:
- }
+ 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
-For example, if you wanted to define your C# class like this :
+If you would like to use your own namespace, you will need to make a fully qualified
+call to `cordova.exec`. For example, if you wanted to define your C# class like this:
- namespace com.mydomain.cordovaExtensions
- {
- public class Echo : BaseCommand
- {
+ namespace com.mydomain.cordovaExtensions
+ {
+ public class Echo : BaseCommand
+ {
+ // ...
+ }
+ }
- }
- }
-
-Then, in JS you would need to call exec like this :
-
- codova.exec(win,fail,"com.mydomain.cordovaExtensions.Echo",...);
+Then, in JS you would need to call exec like this:
+ 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 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]
+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"]);
+ 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:
+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"
-Passing results from C# to JS
+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 :
+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
+ 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 :
+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."));
+ 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 :
+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!\"}"));
+ 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"));
+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
- }
-
-
-
+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
-----------------------------
@@ -160,29 +159,33 @@ For example, you can hook into the 'pause' and 'resume' application events.
### 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.
+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.
+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
---------------
-- 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 :
+- 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'}"]) ;
-
- string[] optValues = JsonHelper.Deserialize<string[]>(options);
+ cordova.exec(win, fail, "ServiceName", "MethodName", ["this is a string", 54, {literal:'trouble'}]);
-- 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.
+ - This will mean that your C# code will receive a difficult to decode string value, such as:
+ "[\"this is a string\", 54, { literal:'trouble' }]"
+ - 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);
+- 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.