You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by ni...@apache.org on 2016/03/08 08:07:35 UTC
docs commit: Cleaned up plugin authoring guide. This closes #542
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 <ni...@microsoft.com>
Authored: Mon Mar 7 13:50:29 2016 -0800
Committer: Nikhil Khandelwal <ni...@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