cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nikhi...@apache.org
Subject docs commit: Cleaned up plugin authoring guide. This closes #542
Date Tue, 08 Mar 2016 07:07:35 GMT
Repository: cordova-docs
Updated Branches:
  refs/heads/master c2b8c3471 -> 9b3848504


Cleaned up plugin authoring guide. This closes #542


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/9b384850
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/9b384850
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/9b384850

Branch: refs/heads/master
Commit: 9b3848504b2d84d0ccc0d4aab2963bed97f26615
Parents: c2b8c34
Author: Nikhil Khandelwal <nikhilkh@microsoft.com>
Authored: Mon Mar 7 13:50:29 2016 -0800
Committer: Nikhil Khandelwal <nikhilkh@microsoft.com>
Committed: Mon Mar 7 23:06:40 2016 -0800

----------------------------------------------------------------------
 www/docs/en/dev/guide/platforms/win8/plugin.md | 177 ++++++++++----------
 1 file changed, 90 insertions(+), 87 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/9b384850/www/docs/en/dev/guide/platforms/win8/plugin.md
----------------------------------------------------------------------
diff --git a/www/docs/en/dev/guide/platforms/win8/plugin.md b/www/docs/en/dev/guide/platforms/win8/plugin.md
index 300dc9a..2f6c681 100644
--- a/www/docs/en/dev/guide/platforms/win8/plugin.md
+++ b/www/docs/en/dev/guide/platforms/win8/plugin.md
@@ -23,34 +23,28 @@ title: Windows Plugins
 # Windows Plugins
 
 This section provides details for how to implement a plugin for use in 
-a Windows Store app. Before reading this, see Create your fist plugin for 
-an overview of the plugin's structure and its common JavaScript interface. 
-This section continues to demonstrate the sample _echo_ plugin that 
-communicates from the Cordova webview to the native platform and back.
+a Windows Store app for Windows 8.1 phone and desktop, and Universal Windows Platform (Windows
10+). Before reading this, see [Create your fist plugin](../../hybrid/plugins/index.html)
for an overview of the plugin's structure and its common JavaScript interface. This section
continues to demonstrate the sample _echo_ plugin that communicates from the Cordova webview
to the native platform and back.
 
 ## Creating a Windows Plugin in JavaScript
 
-These instructions are to create a pure JavaScript plugin.
+Windows Cordova plugins are essentially a thin wrapper around existing WinJS provided functions,
but assuming you will want to define your JS common interface for multiple devices, you will
typically have one JS file that provides the API:
 
-Windows Cordova plugins are essentially a thin wrapper around existing WinJS provided functions,
but assuming you will want to define your JS common interface for multiple devices, you will
typically have one JS file that provides the API.
-
-    // inside file echoplugin.js
-    var EchoPlugin = {
-        // the echo function calls successCallback with the provided text in strInput
-        // if strInput is empty, it will call the errorCallback
-        echo:function(successCallback, errorCallback, strInput) {
-            cordova.exec(successCallback,errorCallback,"EchoPlugin","echo",[strInput]);
-        }
+```js
+// inside file echoplugin.js
+var EchoPlugin = {
+    // the echo function calls successCallback with the provided text in strInput
+    // if strInput is empty, it will call the errorCallback
+    echo:function(successCallback, errorCallback, strInput) {
+        cordova.exec(successCallback,errorCallback,"EchoPlugin","echo",[strInput]);
     }
-
-
-## The Cordova exec proxy
+}
+```
 
 The `cordova.exec` function is defined differently on every platform, this is because each
platform has it's own way of communicating between the application js code, and the native
wrapper code. But in the case of Windows, there is no native wrapper, so the exec call is
there for consistency. So even though you could write the Windows specific code as a part
of plugin's common JS code directly, this is not recommended and plugin authors should use
the same exec API for Windows as for other platforms. This way the plugin API becomes consistent
and you can also take advantage of any parameter checking, or other common code provided by
developers who were working on other platforms.
 
 On Windows, cordova provides a proxy that you can use to register an object that will handle
all cordova.exec calls to an API. So in our case, we will assume that the code in `echoplugin.js`
is handling cross platform relevant JavaScript, and we can simply write a proxy for Windows.
 
-```
+```js
 // in file echoplugin.js
 window.echo = function(str, callback) {
     cordova.exec(callback, function(err) {
@@ -59,7 +53,7 @@ window.echo = function(str, callback) {
 };
 ```
 
-```
+```js
 // in file echopluginProxy.js
 cordova.commandProxy.add("Echo",{
     echo:function(successCallback,errorCallback,strInput) {
@@ -77,59 +71,65 @@ The `echoplugin.js` file will forward the `echo` function call to this
proxy thr
 
 The plugin.xml file will have the settings required for our plugin. In this case, we want
to add our `echoplugin.js` file in the `www` directory and the `echopluginProxy.js` file inside
the `windows` source code of our application. Details of these elements can be found in the
[Plugin.xml](../../plugin_ref/spec.html) reference.
 
-    <?xml version="1.0" encoding="UTF-8"?>
-    <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
-        id="echoplugin"
-        version="0.1.0">
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
+    id="echoplugin"
+    version="0.1.0">
 
-        <js-module src="www/echoplugin.js" name="echoplugin">
-            <clobbers target="window.echoplugin" />
-        </js-module>
+    <js-module src="www/echoplugin.js" name="echoplugin">
+        <clobbers target="window.echoplugin" />
+    </js-module>
 
-        <!-- windows -->
-        <platform name="windows">
-            <js-module src="src/windows/echopluginProxy.js" name="EchoProxy">
-                <merges target="" />
-            </js-module>
-        </platform>
+    <!-- windows -->
+    <platform name="windows">
+        <js-module src="src/windows/echopluginProxy.js" name="EchoProxy">
+            <merges target="" />
+        </js-module>
+    </platform>
 
-        <!-- other platforms -->
+    <!-- other platforms -->
 
-    </plugin>
+</plugin>
+```
 
 This gives us a working Windows JavaScript plugin that uses a common file ( echoplugin.js
) and uses a proxy to provide the Windows only portion of implementation ( echopluginProxy.js
). So how do we add native/managed code to this? Well we are going to start the same, the
only difference will be what we do inside in echopluginProxy methods.
 
-## How WinJS accesses native/managed code
+## Creating a Windows Plugin in C++ or managed code.
 
-In Windows, WinJS authored apps are able to interact with native code, this inter-op is available
for Windows Runtime Components. The details are numerous, and this guide will only cover the
basics. Microsoft provides much more info [here](http://msdn.microsoft.com/en-us/library/windows/apps/hh441569.aspx).
+In Windows, Javascript authored apps are able to interop with native (C++) and managed code
(C#, VB) by creating a Windows runtime component. You can learn the basics here and checkout
more details in guides on MSDN:
+- [Creating Windows Runtime Components in C# and Visual Basic](https://msdn.microsoft.com/en-us/library/windows/apps/br230301.aspx)
+- [Creating Windows Runtime Components in C++](http://msdn.microsoft.com/en-us/library/windows/apps/hh441569.aspx)
 
 When you create your Windows Runtime Component, any class that is defined as `public ref
class sealed` is considered an 'activatable class' and will be callable from JavaScript.
 
-    // in your header file .h
-    namespace EchoRuntimeComponent
+```cpp
+// in your header file .h
+namespace EchoRuntimeComponent
+{
+    public ref class EchoPluginRT sealed
     {
-        public ref class EchoPluginRT sealed 
-        {
-            public:
-            static Platform::String^ Echo(Platform::String^ input);
-        }
+        public:
+        static Platform::String^ Echo(Platform::String^ input);
     }
+}
 
-    // in the implementation file .cpp
-    using namespace EchoRuntimeComponent;
-    using namespace Platform;
+// in the implementation file .cpp
+using namespace EchoRuntimeComponent;
+using namespace Platform;
 
-    Platform::String^ EchoPluginRT::Echo(Platform::String^ input)
+Platform::String^ EchoPluginRT::Echo(Platform::String^ input)
+{
+    if(input->IsEmpty())
     {
-        if(input->IsEmpty()) 
-        {
-            return "Error: input string is empty.";
-        }
-        else
-        {
-            return input->ToString() + "echo";
-        }
+        return "Error: input string is empty.";
     }
+    else
+    {
+        return input->ToString() + "echo";
+    }
+}
+```
 
 Now in order for us to call the native code, we use the namespace, classname, and lowerCamelCase
the method we are calling.
 
@@ -139,49 +139,52 @@ var res = EchoRuntimeComponent.EchoPluginRT.echo("boom");
 
 Moving this to our echopluginProxy.js file, we get:
 
-    // in file echopluginProxy.js
-    cordova.commandProxy.add("EchoPlugin",{
-        echo:function(successCallback,errorCallback,strInput) {
-            var res = EchoRuntimeComponent.EchoPluginRT.echo(strInput);
-            if(res.indexOf("Error") == 0) {
-                errorCallback(res);
-            }
-            else {
-                successCallback(res);
-            }
+```js
+// in file echopluginProxy.js
+cordova.commandProxy.add("EchoPlugin",{
+    echo:function(successCallback, errorCallback, strInput) {
+        var res = EchoRuntimeComponent.EchoPluginRT.echo(strInput);
+        if(res.indexOf("Error") == 0) {
+            errorCallback(res);
         }
-    });
+        else {
+            successCallback(res);
+        }
+    }
+});
+```
 
 And that's it, we have an end to end C++ backed js callable plugin for use in Apache Cordova
Windows!
 
-## Considerations
+### Considerations
 
 - The callback is typically async, so calling the callback right away is probably not expected
by the caller. In practice, if the call is not async, you should at least use a javascript
timeout to force the callback to be called asynchronously.
-- Activatable classes can be used to do event dispatching, async callbacks, passing your
own object types, arrays, collections, overloaded methods and much more. Refer [here](http://msdn.microsoft.com/en-us/library/windows/apps/hh441569.aspx)
for details.
+- Activatable classes can be used to do event dispatching, async callbacks, passing your
own object types, arrays, collections, overloaded methods and much more. Refer to [Creating
Windows Runtime Components in C++](http://msdn.microsoft.com/en-us/library/windows/apps/hh441569.aspx)
for details.
 
-## Defining your plugin
+### Defining your plugin in plugin.xml
 
 Now that we have a working plugin, we need to revisit the plugin definition from earlier
so we can publish it. We can now add the runtime component as a framework, through the `<framework>`
tag inside our platfrom settings. Note that the output type of a WindowsRuntimeComponent can
be either .winmd or .dll
 
-    <?xml version="1.0" encoding="UTF-8"?>
-    <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
-        id="echoplugin"
-        version="0.2.0">
-
-        <js-module src="www/echoplugin.js" name="echoplugin">
-            <clobbers target="window.echoplugin" />
-        </js-module>
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
+    id="echoplugin"
+    version="0.2.0">
 
-        <!-- windows -->
-        <platform name="windows">
-            <js-module src="src/windows/echopluginProxy.js" name="EchoProxy">
-                <merges target="" />
-            </js-module>
-            <framework src="src/windows/EchoRuntimeComponent.winmd" custom="true"/>
-        </platform>
+    <js-module src="www/echoplugin.js" name="echoplugin">
+        <clobbers target="window.echoplugin" />
+    </js-module>
 
-        <!-- other platforms -->
+    <!-- windows -->
+    <platform name="windows">
+        <js-module src="src/windows/echopluginProxy.js" name="EchoProxy">
+            <merges target="" />
+        </js-module>
+        <framework src="src/windows/EchoRuntimeComponent.winmd" custom="true"/>
+    </platform>
 
-    </plugin>
+    <!-- other platforms -->
+</plugin>
+```
 
-That's it, you now have a distributable plugin that you can share with the world!
\ No newline at end of file
+That's it, you now have a distributable plugin that you can share with the world!


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org


Mime
View raw message