You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by pu...@apache.org on 2014/06/11 22:50:11 UTC
[1/4] docs commit: updated wp8 plugin authoring to not use wp7 terms
or classpath
Repository: cordova-docs
Updated Branches:
refs/heads/master 1c287eb46 -> 1d5a84c0c
updated wp8 plugin authoring to not use wp7 terms or classpath
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/3755c19a
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/3755c19a
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/3755c19a
Branch: refs/heads/master
Commit: 3755c19aa5ff0dd45b95a908025d652376564d4b
Parents: 4995c6b
Author: Jesse MacFadyen <pu...@gmail.com>
Authored: Wed Jun 11 13:47:49 2014 -0700
Committer: Jesse MacFadyen <pu...@gmail.com>
Committed: Wed Jun 11 13:47:49 2014 -0700
----------------------------------------------------------------------
docs/en/edge/guide/platforms/wp8/plugin.md | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/3755c19a/docs/en/edge/guide/platforms/wp8/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/wp8/plugin.md b/docs/en/edge/guide/platforms/wp8/plugin.md
index acf69a4..77bda25 100644
--- a/docs/en/edge/guide/platforms/wp8/plugin.md
+++ b/docs/en/edge/guide/platforms/wp8/plugin.md
@@ -27,10 +27,10 @@ _echo_ plugin that communicates from the Cordova webview to the native
platform and back.
Writing a plugin for Cordova on Windows Phone requires a basic
-understanding of Cordova's architecture. Cordova-WP7 consists of a
+understanding of Cordova's architecture. Cordova-WP8 consists of a
`WebBrowser` that hosts the application's JavaScript code and manages
native API calls. You can extend a C# `BaseCommand` class
-(`WP7CordovaClassLib.Cordova.Commands.BaseCommand`), which comes with
+(`WPCordovaClassLib.Cordova.Commands.BaseCommand`), which comes with
most of the functionality you need:
1. Select your project, and right-click to choose __Add → New
@@ -65,7 +65,7 @@ most of the functionality you need:
}
See the
-[BaseCommand.cs](https://github.com/apache/cordova-wp7/blob/master/templates/standalone/cordovalib/Commands/BaseCommand.cs)
+[BaseCommand.cs](https://github.com/apache/cordova-wp8/blob/master/wp8/template/cordovalib/Commands/BaseCommand.cs)
class for methods available for the plugin to override. For example,
the plugin can capture 'pause' and 'resume' events.
[2/4] docs commit: link to new windows 8 plugin auth guide
Posted by pu...@apache.org.
link to new windows 8 plugin auth guide
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/3f709d33
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/3f709d33
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/3f709d33
Branch: refs/heads/master
Commit: 3f709d330ec6f664146b4e22c4fd03eba3a0e4cc
Parents: 3755c19
Author: Jesse MacFadyen <pu...@gmail.com>
Authored: Wed Jun 11 13:48:57 2014 -0700
Committer: Jesse MacFadyen <pu...@gmail.com>
Committed: Wed Jun 11 13:48:57 2014 -0700
----------------------------------------------------------------------
docs/en/edge/guide/hybrid/plugins/index.md | 1 +
1 file changed, 1 insertion(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/3f709d33/docs/en/edge/guide/hybrid/plugins/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/hybrid/plugins/index.md b/docs/en/edge/guide/hybrid/plugins/index.md
index c140b37..6ab6b02 100644
--- a/docs/en/edge/guide/hybrid/plugins/index.md
+++ b/docs/en/edge/guide/hybrid/plugins/index.md
@@ -187,6 +187,7 @@ listed below, and each builds on the simple Echo Plugin example above:
- iOS Plugins
- BlackBerry 10 Plugins
- Windows Phone Plugins
+- Windows 8 Plugins
The Tizen platform does not support plugins.
[3/4] docs commit: Created Windows 8 plugin auth guide.
Posted by pu...@apache.org.
Created Windows 8 plugin auth guide.
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/0f4aee0a
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/0f4aee0a
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/0f4aee0a
Branch: refs/heads/master
Commit: 0f4aee0ad2c8d88cf0325234435628399a89acde
Parents: 3f709d3
Author: Jesse MacFadyen <pu...@gmail.com>
Authored: Wed Jun 11 13:49:43 2014 -0700
Committer: Jesse MacFadyen <pu...@gmail.com>
Committed: Wed Jun 11 13:49:43 2014 -0700
----------------------------------------------------------------------
docs/en/edge/guide/platforms/win8/plugin.md | 216 +++++++++++++++++++++++
1 file changed, 216 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0f4aee0a/docs/en/edge/guide/platforms/win8/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/win8/plugin.md b/docs/en/edge/guide/platforms/win8/plugin.md
new file mode 100644
index 0000000..996462a
--- /dev/null
+++ b/docs/en/edge/guide/platforms/win8/plugin.md
@@ -0,0 +1,216 @@
+--
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Windows 8 Plugins
+
+This section provides details for how to implement a plugin for use in
+a Windows Store app. Before reading this, see Application Plugins 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.
+
+It is important to note that Windows 8 supports developing directly in Javascript, which means developing the 'native' portions in only required in special cases.
+
+Creating a Windows 8 Plugin in JavaScript
+---
+
+These instructions are to create a pure JavaScript plugin. Understanding this is crucial to understanding how to add the native/managed bits.
+
+Windows 8 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 1 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]);
+ }
+ }
+
+Inside Cordova exec on Windows 8
+---
+
+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 8, there is no native wrapper, so the exec call is there for consistency. You could do your js only plugin work directly in EchoPlugin.echo, something like :
+
+ // inside file echoplugin.js ( this is what NOT to do if you want to reuse the JS API cross platform )
+ var EchoPlugin = {
+ echo:function(successCallback,errorCallback,strInput) {
+ if(!strInput || !strInput.length) {
+ errorCallback("Error, something was wrong with the input string. =>" + strInput);
+ }
+ else {
+ successCallback(strInput + "echo");
+ }
+ }
+ }
+
+This would/could work fine, however it means that you will need different versions of echoPlugin.js for different platforms, and possibly you could have issues with inconsistencies in your implementations. As a best practice, we decided to mimic a native API inside cordova.exec on Windows 8, so we could run the same JS code, and not have to rewrite it for the platform, and also take advantage of any parameter checking, or other common code provided by developers who were working on other platforms.
+
+The Cordova exec proxy
+---
+
+On Windows 8, cordova provides a proxy that you can use to register an object that will handle all cordova.exec calls to an API.
+
+For example if you wanted to provide the implementation for the Accelerometer API, you would do this :
+
+cordova.commandProxy.add("Accelerometer",{
+ start:function(){
+ // your code here ...
+ }
+ // ,
+ // ... and the rest of the API here
+});
+
+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 8
+
+ // in file echopluginProxy.js
+ cordova.commandProxy.add("EchoPlugin",{
+ echo:function(successCallback,errorCallback,strInput) {
+ if(!strInput || !strInput.length) {
+ errorCallback("Error, something was wrong with the input string. =>" + strInput);
+ }
+ else {
+ successCallback(strInput + "echo");
+ }
+ }
+ });
+
+The plugin definition
+
+If we want users of our plugin to be able to easily install our plugin, we will need to define it according to how PlugMan defines plugins. More on this in the [Plugin Spec](plugin_ref_spec.md.html#Plugin%20Specification)
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
+ id="com.risingj.echoplugin"
+ version="0.1.0">
+
+ <js-module src="www/echoplugin.js" name="echoplugin">
+ <clobbers target="window.echoplugin" />
+ </js-module>
+
+ <!-- windows8 -->
+ <platform name="windows8">
+ <js-module src="src/windows8/echopluginProxy.js" name="EchoProxy">
+ <merges target="" />
+ </js-module>
+ </platform>
+
+ <!-- other platforms -->
+
+ </plugin>
+
+This gives us a working Windows 8 JavaScript plugin that uses a common file ( echoplugin.js ) and uses a proxy to provide the Windows 8 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
+===
+
+
+In Windows 8, 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).
+
+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
+ {
+ public ref class EchoPluginRT sealed
+ {
+ public:
+ static Platform::String^ Echo(Platform::String^ input);
+ }
+ }
+
+ // in the implementation file .cpp
+ using namespace EchoRuntimeComponent;
+ using namespace Platform;
+
+ Platform::String^ EchoPluginRT::Echo(Platform::String^ input)
+ {
+ if(input->IsEmpty())
+ {
+ 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.
+
+var res = EchoRuntimeComponent.EchoPluginRT.echo("boom");
+Moving this to our echopluginProxy.js file, we get this :
+
+ // 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 8!
+
+Some technical notes:
+===
+
+- 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 async.
+- Activatable classes can do all kinds of awesome, like event dispatching, async callbacks, passing your own object types, arrays, collections, overloaded methods and much more. I recommend you do your homework.
+- If you stick to common Windows Phone 8 and Windows 8 SDK API calls, you will be able to use the same runtime component ( native or managed bits ) in a Windows Phone 8 Apache Cordova plugin. ~stay tuned for that post.
+
+Defining your plugin
+===
+
+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.
+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="com.risingj.echoplugin"
+ version="0.2.0">
+
+ <js-module src="www/echoplugin.js" name="echoplugin">
+ <clobbers target="window.echoplugin" />
+ </js-module>
+
+ <!-- windows8 -->
+ <platform name="windows8">
+ <js-module src="src/windows8/echopluginProxy.js" name="EchoProxy">
+ <merges target="" />
+ </js-module>
+ <framework src="src/windows8/EchoRuntimeComponent.winmd" custom="true"/>
+ </platform>
+
+ <!-- other platforms -->
+
+ </plugin>
+
+That's it, you now have a distributable plugin that you can share with the world!
+One thing to note, support for adding frameworks to Windows 8 Cordova project was only recently added so you will need to make sure your cordova tooling current. The cordova-cli and cordova-plugman both support adding removing native backed plugins.
+
+\> cordova plugin add com.risingj.echoplugin
+or
+\> plugman install --platform windows8 --plugin com.risingj.echoplugin --project .
+
+https://github.com/purplecabbage/cordova-runtimecomp-echoplug
+
[4/4] docs commit: Merge branch 'master' of
https://git-wip-us.apache.org/repos/asf/cordova-docs
Posted by pu...@apache.org.
Merge branch 'master' of https://git-wip-us.apache.org/repos/asf/cordova-docs
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/1d5a84c0
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/1d5a84c0
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/1d5a84c0
Branch: refs/heads/master
Commit: 1d5a84c0cdd0d74e0793bc4c0e001785077b73f8
Parents: 0f4aee0 1c287eb
Author: Jesse MacFadyen <pu...@gmail.com>
Authored: Wed Jun 11 13:50:15 2014 -0700
Committer: Jesse MacFadyen <pu...@gmail.com>
Committed: Wed Jun 11 13:50:15 2014 -0700
----------------------------------------------------------------------
.gitignore | 1 +
CONTRIBUTING.md | 21 ++++
README.md | 50 +++++++++-
Vagrantfile | 125 ++++++++++++++++++++++++
docs/en/edge/cordova/plugins/pluginapis.md | 3 +
docs/pl/edge/config.json | 18 ++++
lib/cordova/version_menu.rb | 43 ++++----
vagrant/cordova-docs.sh | 30 ++++++
8 files changed, 270 insertions(+), 21 deletions(-)
----------------------------------------------------------------------