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 2013/07/18 21:28:26 UTC
[02/12] Version 3.0.0rc1
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/platforms/win8/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/platforms/win8/index.md b/docs/en/3.0.0rc1/guide/platforms/win8/index.md
new file mode 100644
index 0000000..471793a
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/platforms/win8/index.md
@@ -0,0 +1,111 @@
+---
+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 Platform Guide
+
+This guide shows how to set up your SDK development environment to
+deploy Cordova apps for Windows 8. See the following for more
+detailed platform-specific information:
+
+* Upgrading Windows 8
+* Windows 8 Command-line Tools
+
+The command-line tools above refer to versions prior to Cordova 3.0.
+See The Cordova Command-line Interface for information about the
+current interface.
+
+Microsoft deprecated the name _Metro-style apps_ in Windows 8 and
+Windows RT. MSDN now refers to this type of app as a _Windows Store_
+app, and this guide follows that convention. Also, in this guide
+_Windows 8_ signifies both Windows 8 and Windows RT.
+
+## 1. Requirements
+
+- Windows 8
+
+- Visual Studio 2012 Professional or better, or Visual Studio 2012 Express for Windows 8
+
+Follow the instructions [here](http://www.windowsstore.com/) to submit your apps Windows Store.
+
+## 2. Install SDK + Cordova
+
+- Set up your preferred variant of Visual Studio 2012. All of the product's paid versions (Professional, etc.) let you build Windows Store apps. You need **Express for Windows 8** to build Windows Store apps using the [Express editions](http://www.microsoft.com/visualstudio/eng/products/visual-studio-express-products).
+- Download and extract the latest copy of [Cordova](http://phonegap.com/download). You will be working in the `lib\windows-8` subfolder.
+
+## 3. Set up New Project
+
+You can already build Windows 8 apps using the _HTML/JavaScript track_
+available in Windows Store apps. Use Cordova in Windows Store apps to
+expose the same APIs as on other Cordova-supported platforms.
+
+- Open Visual Studio 2012 and choose **New Project**.
+- Select **Installed → Template → Other Languages → JavaScript → Windows Store** from the tree, and then **Blank App** from the projects list. Enter whatever project name you like, such as **CordovaWin8Foo** as in this example.
+
+ 
+
+- Microsoft continues to use `default.html` as the default home page, but most web developers use `index.html`. (Plus it's likely that in the other platform variants of your project you are using `index.html` as the name of your default page.) To fix this, in Solution Explorer rename the `default.html` file to `index.html`. Then double-click the `package.appxmanifest` file and change the **Start page** value to `index.html`.
+
+ 
+
+- To include `cordova.js` in your project, right-click on the **js** folder in Solution Explorer and select **Add → New Item**. Locate the `cordova.js` file in the **lib\windows-8** folder noted above.
+
+- Edit the code for `index.html`. Add a reference to `cordova.js`. You can do this manually, or by dragging the file from Solution Explorer.
+
+### Adding the reference...
+ <!-- WinJS references -->
+ <link href="//Microsoft.WinJS.1.0/css/ui-dark.css" rel="stylesheet" />
+ <script src="//Microsoft.WinJS.1.0/js/base.js"></script>
+ <script src="//Microsoft.WinJS.1.0/js/ui.js"></script>
+
+ <!-- Cordova -->
+ <script src="/js/cordova.js"></script>
+
+ <!-- CordovaWin8Foo references -->
+ <link href="/css/default.css" rel="stylesheet" />
+ <script src="/js/default.js"></script>
+
+- Next, add some code that demonstrates Cordova is working.
+
+### Adding a 'deviceready' handler...
+ <body>
+ <p>Content goes here</p>
+
+ <script type="text/javascript">
+
+ console.log("Subscribing...");
+ document.addEventListener("deviceready", function () {
+
+ navigator.notification.alert("The device is ready!");
+
+ });
+
+ </script>
+
+ </body>
+
+## 5. Test the Project
+
+- Run the project from Visual Studio. You'll see the message box appear:
+
+ 
+
+## Done!
+
+That's it! You're now ready to build Windows Store apps with Cordova.
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/platforms/win8/tools.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/platforms/win8/tools.md b/docs/en/3.0.0rc1/guide/platforms/win8/tools.md
new file mode 100644
index 0000000..9fbb26d
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/platforms/win8/tools.md
@@ -0,0 +1,44 @@
+---
+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 Command-line Tools
+
+The `cordova` command-line utility is a high-level tool that allows
+you to build applications across several platforms at once. An older
+version of the Cordova framework provides sets of command-line tools
+specific to each platform. To use them as an alternative to the CLI,
+you need to download this version of Cordova from
+[cordova.apache.org](http://cordova.apache.org). The download contains
+separate archives for each platform. Expand the platform you wish to
+target. The tools described here are typically available in the
+top-level `bin` directory, otherwise consult the __README__ file for
+more detailed directions.
+
+## Windows 8
+
+The Windows 8 command-line tools only support creating new projects.
+Commands must be run from a cmd or powershell prompt.
+
+## Create a project
+
+Run the `create` command with the following parameters:
+
+* Path to your new Cordova Windows 8 project
+* Package Name, following reverse-domain style convention ( this becomes the default Namespace )
+* Project name
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/platforms/win8/upgrading.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/platforms/win8/upgrading.md b/docs/en/3.0.0rc1/guide/platforms/win8/upgrading.md
new file mode 100644
index 0000000..102ad4a
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/platforms/win8/upgrading.md
@@ -0,0 +1,42 @@
+---
+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.
+---
+
+# Upgrading Windows 8
+
+This guide shows how to modify Windows 8 projects to upgrade from older versions of Cordova.
+Most of these instructions apply to projects created with an older set
+of command-line tools that precede the `cordova` CLI utility. See The
+Cordova Command-line Interface for information how to update the
+version of the CLI.
+
+## Upgrade to 2.9.0 from 2.8.0 ##
+
+The following commands should be done from within Visual Studio to be sure that the any project references are updated/deleted.
+
+1. Remove `cordova-2.8.0.js` from the project's `www` directory.
+2. Add cordova.js file from the source to the project's `www` directory. (Note that the file no longer contains a version number in the filename.)
+3. Build and test!
+
+## Upgrade to 2.8.0 from 2.7.0 ##
+
+The following commands should be done from within Visual Studio to be sure that the any project references are updated/deleted.
+
+1. Remove `cordova-2.7.0.js` from the project's `www` directory.
+2. Add cordova.js file from the source to the project's `www` directory. (Note that the file no longer contains a version number in the filename.)
+3. Build and test!
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/platforms/wp7/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/platforms/wp7/index.md b/docs/en/3.0.0rc1/guide/platforms/wp7/index.md
new file mode 100644
index 0000000..6edb1b6
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/platforms/wp7/index.md
@@ -0,0 +1,99 @@
+---
+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 Phone 7 Platform Guide
+
+This guide shows how to set up your SDK development environment to
+deploy Cordova apps for Windows Phone 7 devices. Apps also run on
+Windows Phone 8 devices using the same APIs, but version 7 lacks some
+of IE10's advanced features available on Windows Phone 8. Windows
+Phone 8 apps do _not_ run on Windows Phone 7 devices.
+
+See the following for more detailed platform-specific information that
+applies to both versions:
+
+* Upgrading Windows Phone
+* Windows Phone Plugins
+* Windows Phone Command-line Tools
+
+The command-line tools above refer to versions prior to Cordova 3.0.
+See The Cordova Command-line Interface for information about the
+current interface.
+
+## 1. System Requirements
+
+- Operating System:
+ - Windows 7 or Windows 8 (Pro) or Windows Vista with SP2
+ - The 64-bit version (x64) of Windows is required for the SDK.
+ - The Pro version is recommended for running a device emulator.
+
+- Register and pay for a [Windows Phone Dev Center](http://dev.windowsphone.com/en-us/publish) account if you want to install your app on a real device or submit it to Market Place.
+
+__NOTE:__ Running the SDK in Virtual Machine might present some challenges. You can read this blog post that gives insight on the solutions to develop for [Windows Phone on a Mac](http://aka.ms/BuildaWP8apponaMac).
+
+## 2. Install SDK + Cordova
+
+- Download and install the [Windows Phone SDK](http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=27570/)
+- Download and extract the latest copy of [Cordova](http://phonegap.com/download). You will be working in the `lib\windows-phone-8\wp7` subfolder, `lib\windows-phone-8\wp8` contains the Windwos Phone 8 version of Cordova.
+- Copy the file CordovaWP7_x_x_x.zip to the folder : \My Documents\Visual Studio 2012\Templates\ProjectTemplates\
+
+## 2.1. Building the template
+
+__NOTE:__ this step may not be required. If the lib\windows-phone directory already contains a file CordovaWP7_x_x_x.zip then you may skip this step.
+
+In order to simplify the development process, Cordova comes with a script to build Visual Studio templates. This allows for rapid creation of Cordova applications inside Visual Studio. This template can be modified if needed and the below steps indicate how to proceed if you want to generate the template.
+
+### Run the batch file to create and install the templates.
+
+- The root of the repo contains a file createTemplates.bat. Double clicking this file will generate 2 .zip files. (CordovaWP7_x_x_x.zip + CordovaWP8_x_x_x.zip where 3.0.0 is the current version number) To easily use these files in Visual Studio, copy them to
+"My Documents\Visual Studio 2012\Templates\ProjectTemplates\" You will then be able to create new Apache Cordova Windows Phone apps from the Visual Studio File->New Project menu.
+- If you run the batch file from the command line, you can also call with a parameter to install automatically
+
+Run the script :
+
+ >createTemplates.bat -install
+
+## 3. Set up New Project
+
+- Open Visual Studio Express for Windows Phone and choose **New Project**.
+- Select **CordovaWP7**. (The version number is displayed in the template description.)
+- Give the project a name, and select __OK__.
+
+## 4. Review the project structure
+
+- The `www` folder contains your Cordova `html/js/css` and any other resources included in your app.
+- Any content that you add here needs to be a part of the Visual Studio project, and it must be set as content.
+- Note: This screen capture was from the wp8 cordova-2.3.0 download, your listing will vary based on the actual version installed.
+
+
+
+## 6. Build your project for the device
+
+In order to test your application on a device, the device must be registered. Click [here][register-url] to read documentation on deploying and testing on your Windows Phone 7.
+
+- Make sure your phone is connected, and the screen is unlocked.
+- In Visual Studio, select 'Device' from the top drop-down menu.
+- Press the green **play** button next to the main drop-down menu to start debugging, or type __F5__.
+
+
+
+## Done!
+
+[register-url]: http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff402565(v=vs.105).aspx
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/platforms/wp8/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/platforms/wp8/index.md b/docs/en/3.0.0rc1/guide/platforms/wp8/index.md
new file mode 100644
index 0000000..2bad662
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/platforms/wp8/index.md
@@ -0,0 +1,128 @@
+---
+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 Phone 8 Platform Guide
+
+This guide shows how to set up your SDK development environment to
+deploy Cordova apps for Windows Phone 8 devices. If you want to target
+both 7.5 and 8 devices, develope for Windows Phone 7 instead as
+detailed in the Windows Phone 7 Platform Guide. Version 7 does not
+have all the advanced features included in IE10, but implements the
+same set of APIs. Windows Phone 8 apps do _not_ run on Windows Phone 7
+devices.
+
+See the following for more detailed platform-specific information that
+applies to both versions:
+
+* Upgrading Windows Phone
+* Windows Phone Plugins
+* Windows Phone Command-line Tools
+
+The command-line tools above refer to versions prior to Cordova 3.0.
+See The Cordova Command-line Interface for information about the
+current interface.
+
+## 1. System Requirements
+
+- Operating System:
+ - Windows 8 or Windows 8 Pro
+ - The 64-bit version (x64) of Windows is required for the SDK.
+ - The Pro version is recommended so you can run a device emulator.
+
+- Hardware:
+ - 6.5 GB of free hard disk space
+ - 4 GB RAM
+ - 64-bit (x64) CPU
+
+- Windows Phone 8 Emulator
+ - The phone emulator uses Hyper-V, so this list includes those pre-requisites.
+ - Windows 8 Pro 64-bit edition or greater
+ - Requires a processor that supports virtualization and [Second Level Address Translation (SLAT)](http://en.wikipedia.org/wiki/Second_Level_Address_Translation)
+ - See the [list of Intel processors that support VT-x (virtualization) and EPT (SLAT)](http://ark.intel.com/Products/VirtualizationTechnology)
+ - Enable the virtualization capability (i.e., VT-x on Intel) in your BIOS settings, as usually this is disabled by default.
+
+- SDK + IDE ( Visual Studio )
+ - Visual Studio 2012 Professional, Premium, or Ultimate. Note that Visual Studio Express for Windows Phone (included in the SDK) is not recommended because you can not build the template (see below) with VS Express, as it does not have the __Export Template__ functionality, which is only in VS Pro or higher.
+
+- Register and pay for a [Windows Phone Dev Center](http://dev.windowsphone.com/en-us/publish) account if you want to install your app on a real device or submit it to Market Place.
+
+__NOTE:__ Running the SDK in Virtual Machine might present some challenges. You can read this blog post that gives insight on the solutions to develop for [Windows Phone on a Mac](http://aka.ms/BuildaWP8apponaMac).
+
+## 2. Install SDK + Cordova
+
+- Download and install [Windows Phone SDK](http://www.microsoft.com/en-us/download/details.aspx?id=35471)
+- Download and extract the latest copy of [Cordova](http://phonegap.com/download). You will be working in the `lib\windows-phone-8\wp8` subfolder, `lib\windows-phone-8\wp7` contains the Windwos Phone 7 version of Cordova.
+- Copy the file CordovaWP8_x_x_x.zip to the folder : \My Documents\Visual Studio 2012\Templates\ProjectTemplates\
+
+## 2.1. Building the template
+
+__NOTE:__ this step may not be required. If the lib\windows-phone directory already contains a file CordovaWP8_x_x_x.zip then you may skip this step.
+
+In order to simplify the development process, Cordova comes with a script to build Visual Studio templates. This allows for rapid creation of Cordova applications inside Visual Studio. This template can be modified if needed and the below steps indicate how to proceed if you want to generate the template.
+
+### Run the batch file to create and install the templates.
+
+- The root of the repo contains a file createTemplates.bat. Double clicking this file will generate 2 .zip files. (CordovaWP7_x_x_x.zip + CordovaWP8_x_x_x.zip where 3.0.0 is the current version number) To easily use these files in Visual Studio, copy them to
+"My Documents\Visual Studio 2012\Templates\ProjectTemplates\" You will then be able to create new Apache Cordova Windows Phone apps from the Visual Studio File->New Project menu.
+- If you run the batch file from the command line, you can also call with a parameter to install automatically
+
+Run the script :
+
+ >createTemplates.bat -install
+
+## 3. Set up New Project
+
+- Open Visual Studio Express for Windows Phone and choose **New Project**.
+- Select **CordovaWP8**. (The version number is displayed in the template description.)
+- Give the project a name, and select __OK__.
+
+
+
+## 4. Review the project structure
+
+- The `www` folder contains your Cordova `html/js/css` and any other resources included in your app.
+- Any content that you add here needs to be a part of the Visual Studio project, and it must be set as content.
+- Note: This screen capture was from the cordova-2.3.0 download, your listing will vary based on the actual version installed.
+
+
+
+## 5. Build and Deploy to Emulator
+
+- Make sure **Windows Phone Emulator** is selected in the main drop-down menu.
+- Press the green **play** button next to the drop-down menu to start debugging, or type __F5__.
+
+
+
+## 6. Build your project for the device
+
+In order to test your application on a device, the device must be registered. Click [here][register-url] to read documentation on deploying and testing on your Windows Phone 8.
+
+- Make sure your phone is connected, and the screen is unlocked.
+- In Visual Studio, select 'Device' from the top drop-down menu.
+- Press the green **play** button next to the main drop-down menu to start debugging, or type __F5__.
+
+
+
+## Done!
+
+## Further Reading
+
+For more details on the specific differences between IE10 and WebKit browsers, and how to support both MS has a helpful [guide here](http://blogs.windows.com/windows_phone/b/wpdev/archive/2012/11/15/adapting-your-webkit-optimized-site-for-internet-explorer-10.aspx)
+
+[register-url]: http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff402565(v=vs.105).aspx
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/platforms/wp8/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/platforms/wp8/plugin.md b/docs/en/3.0.0rc1/guide/platforms/wp8/plugin.md
new file mode 100644
index 0000000..3bf34b4
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/platforms/wp8/plugin.md
@@ -0,0 +1,187 @@
+---
+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 Phone Plugins
+
+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 to 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 WPCordovaClassLib.Cordova;
+ using WPCordovaClassLib.Cordova.Commands;
+ using WPCordovaClassLib.Cordova.JSON;
+
+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
+ }
+ }
+
+## Namespaces
+
+The default namespace for unqualified commands is:
+
+ namespace Cordova.Extension.Commands
+ {
+ // ...
+ }
+
+If you want to use your own namespace, you need to make a fully
+qualified call to `cordova.exec`. For example, if you want to define
+your C# class like this:
+
+ namespace com.mydomain.cordovaExtensions
+ {
+ public class Echo : BaseCommand
+ {
+ // ...
+ }
+ }
+
+Then, in JS you need to call `exec` like this:
+
+ cordova.exec(win, fail, "com.mydomain.cordovaExtensions.Echo", ...);
+
+## Interpreting your arguments in C#
+
+The data received by your plugin method is a string value, but in actuality
+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 see that the value is actually:
+
+ "[\"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"
+
+## 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 simply call:
+
+ DispatchCommandResult(); // calls back with an empty plugin result, considered a success callback
+
+To pass data back, you 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 occurred, you can call `DispatchCommandResult` with a `PluginResult` object:
+
+ DispatchCommandResult(new PluginResult(PluginResult.Status.ERROR, "Echo signaled an error"));
+
+## Handling serialization errors in your plugin's C# method
+
+When interpreting 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 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:
+
+1. [BaseCommand.cs](https://github.com/apache/cordova-wp7/blob/master/templates/standalone/cordovalib/Commands/BaseCommand.cs)
+
+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.
+
+JavaScript is a little more difficult to debug on Windows Phone. You
+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 means that your C# code receives 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 allows you to re-use
+ more JavaScript code among your plug-in's various native
+ implementations.
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/platforms/wp8/tools.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/platforms/wp8/tools.md b/docs/en/3.0.0rc1/guide/platforms/wp8/tools.md
new file mode 100644
index 0000000..f11ab67
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/platforms/wp8/tools.md
@@ -0,0 +1,101 @@
+---
+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 Phone Command-line Tools
+
+The `cordova` command-line utility is a high-level tool that allows
+you to build applications across several platforms at once. An older
+version of the Cordova framework provides sets of command-line tools
+specific to each platform. To use them as an alternative to the CLI,
+you need to download this version of Cordova from
+[cordova.apache.org](http://cordova.apache.org). The download contains
+separate archives for each platform. Expand the platform you wish to
+target. The tools described here are typically available in the
+top-level `bin` directory, otherwise consult the __README__ file for
+more detailed directions.
+
+## Windows Phone
+
+The Windows Phone command-line tools support creating, building, and
+running new projects. Commands must be run from a cmd or powershell
+prompt.
+
+The WP8 repo now includes code for building both WP7 + WP8 apps. The
+repo has subfolders for each: wp7/ and wp8/
+
+## Create a project
+
+There are 2 ways to go about creating a new Apache Cordova WP7 or WP8 application.
+
+### Run the batch file to create and install the templates.
+
+- The root of the repo contains a file createTemplates.bat. Double clicking this file will generate 2 .zip files. (CordovaWP7_x_x_x.zip + CordovaWP8_x_x_x.zip where 3.0.0 is the current version number) To easily use these files in Visual Studio, copy them to
+"My Documents\Visual Studio 2012\Templates\ProjectTemplates\" You will then be able to create new Apache Cordova Windows Phone apps from the Visual Studio File->New Project menu.
+- If you run the batch file from the command line, you can also call with a parameter to install automatically
+
+Run the script :
+
+ >createTemplates.bat -install
+
+### Use the create scripts on the command line
+
+Run the `create` command, specifying the existing path to the project,
+the reverse-domain-style package identifier, and the app's display
+name. Here is the syntax for both Windows Phone 7 and 8:
+
+ >.\wp7\bin\create PathToNewProject [ PackageName ] [ AppName ]
+ >.\wp8\bin\create PathToNewProject [ PackageName ] [ AppName ]
+
+ >PathToNewProject : The path to where you wish to create the project
+ >PackageName : The namespace for the project (default is Cordova.Example)
+ >AppName : The name of the application (default is CordovaWP8AppProj or CordovaWP7AppProj)
+
+ >examples:
+ >.\wp7\bin\create C:\path\to\my_new_project
+ >.\wp8\bin\create C:\path\to\my_new_project io.cordova.example CordovaWP8App
+
+ Launch Visual Studio and open Solution file (.sln) in (C:\path\to\my_new_project)
+
+ Built and Run it
+
+## Building your project (cleans then builds)
+
+* Debug
+
+ $ C:\path\to\my_new_project\cordova\build --debug
+
+* Release
+
+ $ C:\path\to\my_new_project\cordova\build --release
+
+## Running your application
+
+Run the 'run' command with the following *optional* parameters
+
+* Target specification. This includes `--emulator`, `--device`, or `--target=<targetID>`.
+* Build specification. This includes `--debug`, `--release`, or `--nobuild`.
+
+ $ C:\path\to\my_new_project\cordova\run [Target] [Build]
+
+By default the `run` command will be called with `--emulator --debug` if flags are not provided.
+
+## Cleaning
+
+ $ C:\path\to\my_new_project\cordova\clean
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/platforms/wp8/upgrading.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/platforms/wp8/upgrading.md b/docs/en/3.0.0rc1/guide/platforms/wp8/upgrading.md
new file mode 100644
index 0000000..bc58ba6
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/platforms/wp8/upgrading.md
@@ -0,0 +1,274 @@
+---
+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.
+---
+
+# Upgrading Windows Phone
+
+This guide shows how to modify Windows Phone projects, both versions 7
+and 8, to upgrade from older versions of Cordova.
+Most of these instructions apply to projects created with an older set
+of command-line tools that precede the `cordova` CLI utility. See The
+Cordova Command-line Interface for information how to update the
+version of the CLI.
+The following section shows how to upgrade from non-CLI projects.
+
+## Upgrade to the CLI (3.0.0) from 2.9.0 ##
+
+1. Create a new Apache Cordova 3.0.0 project using the cordova CLI, as
+ described in The Cordova Command-line Interface.
+2. Add your platforms the the cordova project, for example: `cordova
+ platform add wp7 wp8`.
+3. Copy the contents of the project's `www` folder to the `www` folder
+ at the root of the cordova project you just created.
+4. Copy or overwrite any native assets from your original project
+ (`SplashScreen`, `ApplicationIcon`, etc.), making sure to add any
+ new files to the `.csproj` file. The windows phone project builds
+ inside the `platforms\wp7` or `platforms\wp8` directory.
+5. Use the cordova CLI tool to install any plugins you need. Note that
+ the CLI handles all core APIs as plugins, so they may need to be
+ added. Only 3.0.0 plugins are compatible with the CLI.
+6. Build and test.
+
+## Upgrade to 3.0.0 (non-CLI) from 2.9.0 ##
+
+In Visual Studio's Solution Explorer window:
+
+1. Create a new Apache Cordova WP7 or WP8 3.0.0 Project
+2. Copy the contents of your `www` folder to the new project, and be sure these items are added to the VS project.
+3. Copy and overwrite any splash screen, or icon images.
+4. Copy over any plugins from the `plugins` folder to the new project and ensure that they are also added to the VS project.
+5. Build and test.
+
+__NOTE:__ all core APIs are removed from Cordova version 3.0, and must
+be installed separately as plugins. For more information on how to
+re-enable these features in a non-CLI workflow, see Using Plugman to
+Manage Plugins.
+
+## Upgrade to 2.9.0 from 2.8.0 ##
+
+In Visual Studio's Solution Explorer window:
+
+1. Create a new Apache Cordova WP7 or WP8 2.9.0 Project
+2. Copy the contents of your `www` folder to the new project, and be sure these items are added to the VS project.
+3. Update the name of cordova.js in the HTML tag if it's still using cordova-VERSION.js (should be just cordova.js).
+4. Copy and overwrite any splash screen, or icon images.
+5. Copy over any plugins from the `plugins` folder to the new project and ensure that they are also added to the .csproj file.
+6. Build and test.
+
+## Upgrade to 2.8.0 from 2.7.0 ##
+
+In Visual Studio's Solution Explorer window:
+
+1. Create a new Apache Cordova WP7 or WP8 2.8.0 Project
+2. Copy the contents of your `www` folder to the new project, and be sure these items are added to the VS project.
+3. Update your HTML to use the new cordova.js file. ( note that there is no longer a version number in the name )
+4. Copy and overwrite any splash screen, or icon images.
+5. Copy over any plugins from the `plugins` folder to the new project and ensure that they are also added to the VS project.
+6. Build and test.
+
+## Upgrade to 2.7.0 from 2.6.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Create a new Apache Cordova WP7 or WP8 2.7.0 Project
+2. Copy the contents of your `www` folder to the new project, and be sure these items are added to the VS project.
+3. Update your HTML to use the new `cordova-2.7.0.js` file.
+4. Copy and overwrite any splash screen, or icon images.
+5. Copy over any plugins from the `plugins` folder to the new project and ensure that they are also added to the VS project.
+6. Build and test.
+
+## Upgrade to 2.6.0 from 2.5.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Create a new Apache Cordova WP7 or WP8 2.6.0 Project
+2. Copy the contents of your `www` folder to the new project, and be sure these items are added to the VS project.
+3. Update your HTML to use the new `cordova-2.6.0.js` file.
+4. Copy and overwrite any splash screen, or icon images.
+5. Copy over any plugins from the `plugins` folder to the new project and ensure that they are also added to the VS project.
+6. Build and test.
+
+## Upgrade to 2.5.0 from 2.4.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Create a new Apache Cordova WP7 or WP8 2.5.0 Project
+2. Copy the contents of your `www` folder to the new project, and be sure these items are added to the VS project.
+3. Update your HTML to use the new `cordova-2.5.0.js` file.
+4. Copy and overwrite any splash screen, or icon images.
+5. Copy over any plugins from the `plugins` folder to the new project and ensure that they are also added to the VS project.
+6. Build and test.
+
+## Upgrade to 2.4.0 from 2.3.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Create a new Apache Cordova WP7 or WP8 2.4.0 Project
+2. Copy the contents of your `www` folder to the new project, and be sure these items are added to the VS project.
+3. Update your HTML to use the new `cordova-2.4.0.js` file.
+4. Copy and overwrite any splash screen, or icon images.
+5. Copy over any plugins from the `plugins` folder to the new project and ensure that they are also added to the VS project.
+6. Build and test.
+
+## Upgrade to 2.3.0 from 2.2.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Create a new Apache Cordova WP7 2.3.0 Project
+2. Copy the contents of your `www` folder to the new project, and be sure these items are added to the VS project.
+3. Update your HTML to use the new `cordova-2.3.0.js` file.
+4. Copy and overwrite any splash screen, or icon images.
+5. Copy over any plugins from the `plugins` folder to the new project and ensure that they are also added to the VS project.
+6. Build and test.
+
+## Upgrade to 2.2.0 from 2.1.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Create a new Apache Cordova WP7 2.2.0 Project
+2. Copy the contents of your `www` folder to the new project, and be sure these items are added to the VS project.
+3. Update your HTML to use the new `cordova-2.2.0.js` file.
+4. Copy and overwrite any splash screen, or icon images.
+5. Copy over any plugins from the `plugins` folder to the new project and ensure that they are also added to the VS project.
+6. Build and test.
+
+## Upgrade to 2.1.0 from 2.0.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Create a new Apache Cordova WP7 2.1.0 Project
+2. Copy the contents of your `www` folder to the new project, and be sure these items are added to the VS project.
+3. Update your HTML to use the new `cordova-2.1.0.js` file.
+4. Copy and overwrite any splash screen, or icon images.
+5. Copy over any plugins from the `plugins` folder to the new project and ensure that they are also added to the VS project.
+6. Build and test.
+
+## Upgrade to 2.0.0 from 1.9.0 ##
+
+There have been considerable changes to the WP7 project structure in Apache Cordova 2.0.0 which make this upgrade a little more involved that the others. Essentially this is not an upgrade but creation of a new project and copy over of existing source files.
+
+In Visual Studio's Solution Explorer window:
+1. Create a new Apache Cordova WP7 2.0 Project
+2. Copy the contents of your `www` folder to the new project, and be sure these items are added to the VS project.
+3. Update your HTML to use the new `cordova-2.0.0.js` file.
+4. Copy and overwrite any splash screen, or icon images.
+5. Copy over any plugins from the `plugins` folder to the new project and ensure that they are also added to the VS project.
+6. Build and test.
+
+## Upgrade to 1.9.0 from 1.8.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Delete `GapLib/WP7CordovaClassLib.dll` from your project.
+2. Remove the reference to `WP7CordovaClassLib` in the __References__ folder.
+3. Right-click on __References__ and select __Add Reference__
+4. Navigate to the new distribution and add the file 'WP7CordovaClassLib.dll'
+ - __NOTE:__ You can view the version of the DLL by right-clicking on the reference, and selecting __Properties__.
+5. Copy the new `cordova-1.9.0.js` into your project. (Be sure it is marked as Content.)
+6. Update your HTML to use the new `cordova-1.9.0.js` file.
+
+## Upgrade to 1.8.0 from 1.7.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Delete `GapLib/WP7CordovaClassLib.dll` from your project.
+2. Remove the reference to `WP7CordovaClassLib` in the __References__ folder.
+3. Right-click on __References__ and select __Add Reference__
+4. Navigate to the new distribution and add the file 'WP7CordovaClassLib.dll'
+ - __NOTE:__ You can view the version of the DLL by right-clicking on the reference, and selecting __Properties__.
+5. Copy the new `cordova-1.8.0.js` into your project. (Be sure it is marked as Content.)
+6. Update your HTML to use the new `cordova-1.8.0.js` file.
+
+## Upgrade to 1.7.0 from 1.6.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Delete `GapLib/WP7CordovaClassLib.dll` from your project.
+2. Remove the reference to `WP7CordovaClassLib` in the __References__ folder.
+3. Right-click on __References__ and select __Add Reference__
+4. Navigate to the new distribution and add the file 'WP7CordovaClassLib.dll'
+ - __NOTE:__ You can view the version of the DLL by right-clicking on the reference, and selecting __Properties__.
+5. Copy the new `cordova-1.7.0.js` into your project. (Be sure it is marked as Content.)
+6. Update your HTML to use the new `cordova-1.7.0.js` file.
+
+## Upgrade to 1.6.1 from 1.6.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Delete `GapLib/WP7CordovaClassLib.dll` from your project.
+2. Remove the reference to `WP7CordovaClassLib` in the __References__ folder.
+3. Right-click on __References__ and select __Add Reference__
+4. Navigate to the new distribution and add the file 'WP7CordovaClassLib.dll'
+ - __NOTE:__ You can view the version of the DLL by right-clicking on the reference, and selecting __Properties__.
+5. Copy the new `cordova-1.6.1.js` into your project. (Be sure it is marked as Content.)
+6. Update your HTML to use the new `cordova-1.6.1.js` file.
+
+## Upgrade to 1.6.0 from 1.5.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Delete `GapLib/WP7CordovaClassLib.dll` from your project.
+2. Remove the reference to `WP7CordovaClassLib` in the __References__ folder.
+3. Right-click on __References__ and select __Add Reference__
+4. Navigate to the new distribution and add the file 'WP7CordovaClassLib.dll'
+ - __NOTE:__ You can view the version of the DLL by right-clicking on the reference, and selecting __Properties__.
+5. Copy the new `cordova-1.6.0.js` into your project. (Be sure it is marked as Content.)
+6. Update your HTML to use the new `cordova-1.6.0.js` file.
+
+## Upgrade to 1.5.0 from 1.4.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Delete `GapLib/WP7CordovaClassLib.dll` from your project.
+2. Remove the reference to `WP7CordovaClassLib` in the __References__ folder.
+3. Right-click on __References__ and select __Add Reference__
+4. Navigate to the new distribution and add the file 'WP7CordovaClassLib.dll'
+ - __NOTE:__ You can view the version of the DLL by right-clicking on the reference, and selecting __Properties__.
+5. Copy the new `cordova-1.5.0.js` into your project. (Be sure it is marked as Content.)
+6. Update your HTML to use the new `cordova-1.5.0.js` file.
+
+## Upgrade to 1.4.0 from 1.3.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Delete `GapLib/WP7CordovaClassLib.dll` from your project.
+2. Remove the reference to `WP7CordovaClassLib` in the __References__ folder.
+3. Right-click on __References__ and select __Add Reference__
+4. Navigate to the new distribution and add the file 'WP7CordovaClassLib.dll'
+ - __NOTE:__ You can view the version of the DLL by right-clicking on the reference, and selecting __Properties__.
+5. Copy the new `cordova-1.4.0.js` into your project. (Be sure it is marked as Content.)
+6. Update your HTML to use the new `cordova-1.4.0.js` file.
+
+## Upgrade to 1.3.0 from 1.2.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Delete `GapLib/WP7CordovaClassLib.dll` from your project.
+2. Remove the reference to `WP7CordovaClassLib` in the __References__ folder.
+3. Right-click on __References__ and select __Add Reference__
+4. Navigate to the new distribution and add the file 'WP7CordovaClassLib.dll'
+ - __NOTE:__ You can view the version of the DLL by right-clicking on the reference, and selecting __Properties__.
+5. Copy the new `cordova-1.3.0.js` into your project. (Be sure it is marked as Content.)
+6. Update your HTML to use the new `cordova-1.3.0.js` file.
+
+## Upgrade to 1.2.0 from 1.1.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Delete `GapLib/WP7CordovaClassLib.dll` from your project.
+2. Remove the reference to `WP7CordovaClassLib` in the __References__ folder.
+3. Right-click on __References__ and select __Add Reference__
+4. Navigate to the new distribution and add the file 'WP7CordovaClassLib.dll'
+ - __NOTE:__ You can view the version of the DLL by right-clicking on the reference, and selecting __Properties__.
+5. Copy the new `cordova-1.2.0.js` into your project. (Be sure it is marked as Content.)
+6. Update your HTML to use the new `cordova-1.2.0.js` file.
+
+## Upgrade to 1.1.0 from 1.0.0 ##
+
+In Visual Studio's Solution Explorer window:
+1. Delete `GapLib/WP7CordovaClassLib.dll` from your project.
+2. Remove the reference to `WP7CordovaClassLib` in the __References__ folder.
+3. Right-click on __References__ and select __Add Reference__
+4. Navigate to the new distribution and add the file 'WP7CordovaClassLib.dll'
+ - __NOTE:__ you can view the version of the DLL by right-clicking on the reference, and selecting __Properties__.
+5. Copy the new `cordova-1.1.0.js` into your project. (Be sure it is marked as Content.)
+6. Update your HTML to use the new `cordova-1.1.0.js` file.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/plugins/corePluginInstall.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/plugins/corePluginInstall.md b/docs/en/3.0.0rc1/guide/plugins/corePluginInstall.md
new file mode 100644
index 0000000..7b8f01e
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/plugins/corePluginInstall.md
@@ -0,0 +1,110 @@
+---
+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.
+---
+
+# Using Plugman to Manage Plugins
+
+From version 3.0 onward, Cordova implements all device APIs as
+plugins, and leaves them disabled by default. It also supports two
+different ways to add and remove plugins. The first is by using the
+`cordova` CLI described in The Command-line Interface. The second is
+by using a lower-level
+[plugman](https://github.com/apache/cordova-plugman/)
+command-line interface. This guide concentrates on the second
+approach, which may be useful for developers who want to upgrade their
+version of Cordova, but who haven't yet adopted the Cordova CLI in
+their workflow.
+
+For more information on plugman, see
+[the README file in its repository](https://github.com/apache/cordova-plugman/blob/master/README.md).
+
+## Basic Commands
+
+To install plugman, you must have [node](http://nodejs.org/) installed
+on your machine:
+
+ npm install -g plugman
+
+Here is the syntax to add a plugin for each platform:
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]
+
+To uninstall a plugin:
+
+ plugman --uninstall --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]
+
+## Installing Core Plugins
+
+The examples below show how to add plugins as needed so that any
+Cordova APIs you use in your project still work after you upgrade to
+version 3.0. For each command, you need to select the target
+platform, and reference the platform's project directory.
+
+* cordova-plugin-battery-status
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status.git
+
+* cordova-plugin-camera
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git
+
+* cordova-plugin-console
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-console.git
+
+* cordova-plugin-contacts
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-contacts.git
+
+* cordova-plugin-device
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git
+
+* cordova-plugin-device-motion (accelerometer)
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-device-motion.git
+
+* cordova-plugin-device-orientation (compass)
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-device-orientation.git
+
+* cordova-plugin-dialogs
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-dialogs.git
+
+* cordova-plugin-file
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-file.git
+
+* cordova-plugin-file-transfer
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer.git
+
+* cordova-plugin-geolocation
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-geolocation.git
+
+* cordova-plugin-globalization
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-globalization.git
+
+* cordova-plugin-inappbrowser
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-inappbrowser.git
+
+* cordova-plugin-media
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-media.git
+
+* cordova-plugin-media-capture
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-media-capture.git
+
+* cordova-plugin-network-information
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information.git
+
+* cordova-plugin-splashscreen
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-splashscreen.git
+
+* cordova-plugin-vibration
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration.git
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/plugins/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/plugins/index.md b/docs/en/3.0.0rc1/guide/plugins/index.md
new file mode 100644
index 0000000..64896fd
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/plugins/index.md
@@ -0,0 +1,120 @@
+---
+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.
+---
+
+# Plugin Development Guide
+
+A Cordova plugin bridges a bit of functionality between the WebView
+powering a Cordova application and the native platform the Cordova
+application is running on. Plugins are composed of a single JavaScript
+interface used across all platforms, and native implementations
+following platform-specific Plugin interfaces that the JavaScript
+calls into. All of the core Cordova APIs are implemented using this
+architecture.
+
+This guide steps the process of writing a simple Echo Plugin that
+passes a string from JavaScript and sends it into the native
+environment for the supported platforms. The native code then returns
+the same string back to the callbacks inside the plugin's JavaScript.
+
+This guide provides enough overview on which you can build to write
+more complex plugins.
+
+## JavaScript
+
+The entry point for any plugin is JavaScript. The reason developers use
+Cordova is so they can use and write JavaScript, not Objective-C,
+not Java, not C#. The JavaScript interface for your plugin is the
+front-facing and arguably most important part of your Cordova plugin.
+
+You can structure your plugin's JavaScript however you like. The one
+thing you _must_ use to communicate between the Cordova JavaScript
+ and native environments is the `cordova.exec` function. Here is an example:
+
+ cordova.exec(function(winParam) {}, function(error) {}, "service",
+ "action", ["firstArgument", "secondArgument", 42,
+ false]);
+
+The parameters are detailed below:
+
+1. `function(winParam) {}` - Success function callback. Assuming your
+ `exec` call completes successfully, this function is invoked
+ (optionally with any parameters you pass back to it).
+2. `function(error) {}` - Error function callback. If the operation does
+ not complete successfully, this function is invoked (optionally
+ with an error parameter).
+3. `"service"` - The service name to call into on the native side. This
+ is mapped to a native class, about which more information is
+ available in the native guides listed below.
+4. `"action"` - The action name to call into. This is picked up by the
+ native class receiving the `exec` call, and, depending on the
+ platform, essentially maps to a class's method.
+ The native guides listed below provide details.
+5. `[/* arguments */]` - Arguments to pass into the native environment.
+
+### Echo Plugin JavaScript Example
+
+ window.echo = function(str, callback) {
+ cordova.exec(callback, function(err) {
+ callback('Nothing to echo.');
+ }, "Echo", "echo", [str]);
+ };
+
+Let's dive into this. The plugin attaches itself to `window`,
+specifically to the `echo` function. Plugin users would then use it as
+follows:
+
+ window.echo("echome", function(echoValue) {
+ alert(echoValue == "echome"); // should alert true.
+ });
+
+First, let's take a look at the last three arguments to the `exec`
+function. We will be calling the `Echo` "service", requesting the `echo`
+"action", and passing an array of arguments containing the echo string,
+which is the first parameter into the `window.echo` function.
+
+The success callback passed into `exec` is simply a reference to the
+callback function that `window.echo` takes. We do a bit more for the
+error callback: if the native side fires off the error callback, we
+simply invoke the success callback and pass into it a "default"
+string.
+
+## Plugin Specification
+
+Cordova has a plugin specification available to enable automated
+installation of the plugin for Android, iOS, BlackBerry 10 and Windows
+Phone platforms. By structuring your plugin in a particular way and
+adding a `plugin.xml` manifest file, you can enable users to install
+your plugin via the command line tooling.
+
+- Plugin Specification
+
+## Native
+
+Once you define JavaScript for your plugin, you need to complement it
+with at least one native implementation. Details to do so for each
+platform are listed below. These guides continue to build on the
+simple Echo Plugin example discussed above.
+
+- Android Plugins
+- BlackBerry Plugins
+- BlackBerry 10 Plugins
+- iOS Plugins
+- Windows Phone Plugins
+
+The Tizen platform currently does not support plugins.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/plugins/plugin_spec.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/plugins/plugin_spec.md b/docs/en/3.0.0rc1/guide/plugins/plugin_spec.md
new file mode 100644
index 0000000..63b9b0c
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/plugins/plugin_spec.md
@@ -0,0 +1,502 @@
+---
+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.
+---
+
+# Plugin Specification
+
+The `plugin.xml` file is an XML document in the `plugins` namespace:
+`http://apache.org/cordova/ns/plugins/1.0`. It contains a top-level
+`plugin` element that defines the plugin, and children that define the
+structure of the plugin.
+
+A sample plugin element:
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
+ xmlns:android="http://schemas.android.com/apk/res/android"
+ id="com.alunny.foo"
+ version="1.0.2">
+
+## <plugin> element
+
+The `plugin` element is the plugin manifest's top-level element. It
+features the following attributes:
+
+* `xmlns` (required):
+ The plugin namespace, `http://apache.org/cordova/ns/plugins/1.0`. If
+ the document contains XML from other namespaces, such as tags to be
+ added to the `AndroidManifest.xml` file, those namespaces should
+ also be included in the top-level element.
+
+* `id` (required):
+ A reverse-domain style identifier for the plugin, such as
+ `com.alunny.foo`
+
+* `version` (required):
+ A version number for the plugin, that matches the following
+ major-minor-patch style regular expression:
+
+ ^\d+[.]\d+[.]\d+$
+
+## <engines> and <engine> elements
+
+The child elements of the `<engines>` element specify versions of
+Apache Cordova-based frameworks that this plugin supports. An example:
+
+ <engines>
+ <engine name="cordova" version="1.7.0" />
+ <engine name="cordova" version="1.8.1" />
+ <engine name="worklight" version="1.0.0" />
+ </engines>
+
+Similar to the `<plugin>` element's `version` attribute, the specified
+version string should match a major-minor-patch string conforming to
+the regular expression:
+
+ ^\d+[.]\d+[.]\d+$
+
+Engine elements may also specify fuzzy matches to avoid repetition,
+and to reduce maintenance when the underlying platform is updated.
+Tools should support a minimum of `>`, `>=`, `<` and `<=`, for
+example:
+
+ <engines>
+ <engine name="cordova" version=">=1.7.0" />
+ <engine name="cordova" version="<1.8.1" />
+ </engines>
+
+plugman aborts with a non-zero code for any plugin whose target
+project does not meet the engine's constraints.
+
+If no `<engine>` tags are specified, plugman attempts to install into
+the specified cordova project directory blindly.
+
+## <name> element
+
+A human-readable name for the plugin, whose text content contains the
+name of the plugin. For example:
+
+ <name>Foo</name>
+
+This element does not (yet) handle localization.
+
+## <asset> element
+
+One or more elements listing the files or directories to be copied
+into a Cordova app's `www` directory. Examples:
+
+ <!-- a single file, to be copied in the root directory -->
+ <asset src="www/foo.js" target="foo.js" />
+ <!-- a directory, also to be copied in the root directory -->
+ <asset src="www/foo" target="foo" />
+
+All `<asset>` tags require both `src` and `target` attributes.
+Web-only plugins contains mostly `<asset>` elements. Any `<asset>`
+elements that are nested within `<platform>` elements specify
+platform-specific web assets, as described below. Attributes include:
+
+* `src` (required):
+ Where the file or directory is located in the plugin package,
+ relative to the `plugin.xml` document. If a file does not exist at
+ the specified `src` location, plugman stops and reverses the
+ installation process, issues a notification about the conflict, and
+ exits with a non-zero code.
+
+* `target` (required):
+
+ Where the file or directory should be located in the Cordova app,
+ relative to the `www` directory.
+ Assets can be targeted to subdirectories, for example:
+
+ <asset src="www/new-foo.js" target="js/experimental/foo.js" />
+
+ creates the `js/experimental` directory within the `www` directory,
+ unless already present, then copies the `new-foo.js` file and
+ renames it `foo.js`. If a file already exists at the target
+ location, plugman stops and reverses the installation process,
+ issues a notification about the conflict, and exits with a non-zero
+ code.
+
+## <js-module> element
+
+Most plugins include one or more JavaScript files. Each `<js-module>`
+tag corresponds to a JavaScript file, and prevents the plugin's users
+from having to add a `<script>` tag for each file. While `<asset>`
+tags simply copy a file from the plugin subdirectory into `www`,
+`<js-module>` tags are much more sophisticated. They look like this:
+
+ <js-module src="socket.js" name="Socket">
+ <clobbers target="chrome.socket" />
+ </js-module>
+
+When installing a plugin with the example above, `socket.js` is copied
+to `www/plugins/my.plugin.id/socket.js`, and added as an entry to
+`www/cordova_plugins.js`. At load time, code in `cordova.js` uses XHR
+to read each file and inject a `<script>` tag into HTML. It adds a
+mapping to clobber or merge as appropriate, as described below.
+
+_Do not_ wrap the file with `cordova.define`, as it is added
+automatically. The module is wrapped in a closure, with `module`,
+`exports`, and `require` in scope, as is normal for AMD modules.
+
+Details for the `<js-module>` tag:
+
+* The `src` references a file in the plugin directory relative to the
+ `plugin.xml` file.
+
+* The `name` provides the last part of the module name. It can
+ generally be whatever you like, and it only matters if you want to
+ use `cordova.require` to import other parts of your plugins in your
+ JavaScript code. The module name for a `<js-module>` is your
+ plugin's `id` followed by the value of `name`. For the example
+ above, with an `id` of `chrome.socket`, the module name is
+ `chrome.socket.Socket`.
+
+* Three tags are allowed within `<js-module>`:
+
+ * `<clobbers target="some.value" />` indicates that the
+ `module.exports` is inserted into the `window` object as
+ `window.some.value`. You can have as many `<clobbers>` as you
+ like. Any object not available on `window` is created.
+
+ * `<merges target="some.value" />` indicates that the module
+ should be merged with any existing value at `window.some.value`.
+ If any key already exists, the module's version overrides the
+ original. You can have as many `<merges>` as you like. Any
+ object not available on `window` is created.
+
+ * `<runs />` means that your code should be specified with
+ `cordova.require`, but not installed on the `window`
+ object. This is useful when initializing the module, attaching
+ event handlers or otherwise. You can only have up to one
+ `<runs/>` tag. Note that including a `<runs/>` with
+ `<clobbers/>` or `<merges/>` is redundant, since they also
+ `cordova.require` your module.
+
+ * An empty `<js-module>` still loads and can be acccessed in other
+ modules via `cordova.require`.
+
+If `src` does not resolve to an existing file, plugman stops and
+reverses the installation, issues a notification of the problem, and
+exits with a non-zero code.
+
+Nesting `<js-module>` elements within `<platform>` declares
+platform-specific JavaScript module bindings.
+
+## <dependency>
+
+The `<dependency>` tag allows you specify other plugins on which the
+current plugin depends. While future versions will access them from
+plugin repositories, in the short term plugins are directly referenced
+as URLs by `<dependency>` tags. They are formatted as follows:
+
+ <dependency id="com.plugin.id" url="https://github.com/myuser/someplugin" commit="428931ada3891801" subdir="some/path/here" />
+
+* `id`: provides the ID of the plugin. It should be globally unique,
+ and expressed in reverse-domain style. While neither of these
+ restrictions is currently enforced, they may be in the future.
+
+* `url`: A URL for the plugin. This should reference a git repository,
+ which plugman attempts to clone.
+
+* `commit`: This is any git reference understood by `git checkout`: a
+ branch or tag name (e.g., `master`, `0.3.1`), or a commit hash (e.g.,
+ `975ddb228af811dd8bb37ed1dfd092a3d05295f9`).
+
+* `subdir`: Specifies that the targeted plugin dependency exists as a
+ subdirectory of the git repository. This is helpful because it
+ allows the repository to contain several related plugins, each
+ specified individually.
+
+In the future, version constraints will be introduced, and a plugin
+repository will exist to support fetching by name instead of explicit
+URLs.
+
+### Relative Dependency Paths
+
+If you set the `url` of a `<dependency>` tag to `"."` and provide a
+`subdir`, the dependent plugin is installed from the same local or
+remote git repository as the parent plugin that specifies the
+`<dependency>` tag.
+
+Note that the `subdir` always specifies a path relative to the _root_
+of the git repository, not the parent plugin. This is true even if you
+installed the plugin with a local path directly to it. Plugman finds
+the root of the git repository and then finds the other plugin from
+there.
+
+## <platform>
+
+The `<platform>` tag identifies platforms that have associated native
+code or require modifications to their configuration files. Tools
+using this specification can identify supported platforms and install
+the code into Cordova projects.
+
+Plugins without `<platform>` tags are assumed to be JavaScript-only,
+and therefore installable on any and all platforms.
+
+A sample platform tag:
+
+ <platform name="android">
+ <!-- android-specific elements -->
+ </platform>
+ <platform name="ios">
+ <!-- ios-specific elements -->
+ </platform>
+
+The required `name` attribute identifies a platform as supported,
+associating the element's children with that platform.
+
+Platform names should be lowercase. Platform names, as arbitrarily
+chosen, are listed:
+
+* android
+* bb10
+* ios
+* wp7
+* wp8
+
+## <source-file>
+
+The `<source-file>` element identifies executable source code that
+should be installed into a project. Examples:
+
+ <!-- android -->
+ <source-file src="src/android/Foo.java"
+ target-dir="src/com/alunny/foo" />
+ <!-- ios -->
+ <source-file src="src/ios/CDVFoo.m" />
+ <source-file src="src/ios/someLib.a" framework="true" />
+ <source-file src="src/ios/someLib.a" compiler-flags="-fno-objc-arc" />
+
+It supports the following attributes:
+
+* `src` (required):
+ Location of the file relative to `plugin.xml`. If the `src` file
+ cannot be found, plugman stops and reverses the installation, issues
+ a notification about the problem, and exits with a non-zero code.
+
+* `target-dir`:
+ A directory into which the files should be copied, relative to the
+ root of the Cordova project. In practice, this is most important
+ for Java-based platforms, where a file in the `com.alunny.foo`
+ package must be located within the `com/alunny/foo` directory. For
+ platforms where the source directory is not important, this
+ attribute should be omitted.
+
+ As with assets, if the `target` of a `source-file` would overwrite
+ an existing file, plugman stops and reverses the installation,
+ issues a notification about the problem, and exits with a non-zero
+ code.
+
+* `framework` (iOS only):
+ If set to `true`, also adds the specified file as a framework to the
+ project.
+
+* `compiler-flags` (iOS only):
+ If set, assigns the specified compiler flags for the particular
+ source file.
+
+## <config-file>
+
+Identifies an XML-based configuration file to be modified, where in
+that document the modification should take place, and what should be
+modified.
+
+Two file types that have been tested for modification with this
+element are `xml` and `plist` files.
+
+The `config-file` element only allows you to append new children to an
+XML document tree. The children are XML literals to be inserted in the
+target document.
+
+Example for XML:
+
+ <config-file target="AndroidManifest.xml" parent="/manifest/application">
+ <activity android:name="com.foo.Foo" android:label="@string/app_name">
+ <intent-filter>
+ </intent-filter>
+ </activity>
+ </config-file>
+
+Example for `plist`:
+
+ <config-file target="*-Info.plist" parent="CFBundleURLTypes">
+ <array>
+ <dict>
+ <key>PackageName</key>
+ <string>$PACKAGE_NAME</string>
+ </dict>
+ </array>
+ </config-file>
+
+It supports the following attributes:
+
+* `target`:
+
+ The file to be modified, and the path relative to the root of the
+ Cordova project.
+
+ The target can include wildcard (`*`) elements. In this case,
+ plugman recursively searches through the project directory structure
+ and uses the first match.
+
+ On iOS, the location of configuration files relative to the project
+ directory root is not known, so specifying a target of `config.xml`
+ resolves to `cordova-ios-project/MyAppName/config.xml`.
+
+ If the specified file does not exist, the tool ignores the
+ configuration change and continues installation.
+
+* `parent`: An XPath selector referencing the parent of the elements
+ to be added to the config file. If you use absolute selectors, you
+ can use a wildcard (`*`) to specify the root element,
+ e.g., `/*/plugins`.
+
+ For `plist` files, the `parent` determines under what parent key the
+ specified XML should be inserted.
+
+ If the selector does not resolve to a child of the specified
+ document, the tool stops and reverses the installation process,
+ issues a warning, and exits with a non-zero code.
+
+## <plugins-plist>
+
+This is _outdated_ as it only applies to cordova-ios 2.2.0 and
+below. Use the `<config-file>` tag for newer versions of Cordova.
+
+Example:
+
+ <config-file target="config.xml" parent="/widget/plugins">
+ <plugin name="ChildBrowser" value="ChildBrowserCommand"/>
+ </config-file>
+
+Specifies a key and value to append to the correct `AppInfo.plist`
+file in an iOS Cordova project. For example:
+
+ <plugins-plist key="Foo" string="CDVFoo" />
+
+## <resource-file> and <header-file>
+
+Like source files, but specifically for platforms such as iOS that
+distinguish between source files, headers, and resources. Examples:
+
+ <resource-file src="CDVFoo.bundle" />
+ <resource-file src="CDVFooViewController.xib" />
+ <header-file src="CDVFoo.h" />
+
+## <lib-file>
+
+Like source, resource, and header files, but specifically for
+platforms such as BlackBerry 10 that use user-generated libraries.
+Examples:
+
+ <lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" />
+ <lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" />
+
+Supported attributes:
+
+* `src` (required):
+ The location of the file relative to `plugin.xml`.
+ If `src` cannot be found, plugman stops and reverses the
+ installation, issues a warning about the problem, and exits with a
+ non-zero code.
+
+* `arch`: The architecture for which the `.so` file has been built,
+ either `device` or `simulator`.
+
+## <framework>
+
+Identifies a framework (usually part of the OS/platform) on which the plugin depends.
+
+Examples:
+
+ <framework src="libsqlite3.dylib" />
+ <framework src="social.framework" weak="true" />
+
+
+
+
+The `src` attribute identifies the framework, which plugman attempts
+to add to the Cordova project, in the correct fashion for a given
+platform.
+
+The optional `weak` attribute is a boolean indicating whether the
+framework should be weakly linked. The default is `false`.
+
+## <info>
+
+Additional information provided to users. This is useful when you
+require extra steps that can't be easily automated or are beyond
+plugman's scope. Examples:
+
+ <info>
+ You need to install **Google Play Services** from the `Android Extras` section using the Android SDK manager (run `android`).
+
+ You need to add the following line to your `local.properties`
+
+ android.library.reference.1=PATH_TO_ANDROID_SDK/sdk/extras/google/google_play_services/libproject/google-play-services_lib
+ </info>
+
+# Variables
+
+In certain cases, a plugin may need to make configuration changes
+dependent on the target application. For example, to register for C2DM
+on Android, an app whose package id is `com.alunny.message` would
+require a permission such as:
+
+ <uses-permission
+ android:name="com.alunny.message.permission.C2D_MESSAGE"/>
+
+In such cases where the content inserted from the `plugin.xml` file is
+not known ahead of time, variables can be indicated by a dollar-sign
+followed by a series of capital letters, digits, or underscores. For
+the above example, the `plugin.xml` file would include this tag:
+
+ <uses-permission
+ android:name="$PACKAGE_NAME.permission.C2D_MESSAGE"/>
+
+plugman replaces variable references with the specified value, or the
+empty string if not found. The value of the variable reference may be
+detected (in this case, from the `AndroidManifest.xml` file) or
+specified by the user of the tool; the exact process is dependent on
+the particular tool.
+
+plugman can request users to specify a plugin's required
+variables. For example, API keys for C2M and Google Maps can be
+specified as a command-line argument:
+
+ plugman --platform android --project /path/to/project --plugin name|git-url|path --variable API_KEY=!@CFATGWE%^WGSFDGSDFW$%^#$%YTHGsdfhsfhyer56734
+
+To make the variable mandatory, the `<platform>` tag needs to contain
+a `<preference>` tag. For example:
+
+ <preference name="API_KEY" />
+
+plugman checks that these required preferences are passed in. If not,
+it should warn the user how to pass the variable in and exit with a
+non-zero code.
+
+Certain variable names should be reserved, as listed below.
+
+## $PACKAGE_NAME
+
+The reverse-domain style unique identifier for the package,
+corresponding to the `CFBundleIdentifier` on iOS or the `package`
+attribute of the top-level `manifest` element in an
+`AndroidManifest.xml` file.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/privacy/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/privacy/index.md b/docs/en/3.0.0rc1/guide/privacy/index.md
new file mode 100644
index 0000000..7603e08
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/privacy/index.md
@@ -0,0 +1,110 @@
+---
+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.
+---
+
+# Privacy Guide
+
+Mobile privacy is a critical issue that every app developer must address. Your users expect that their private information will be collected and treated appropriately by your app. Also, there are an increasing number of jurisdictions that now have legal requirements regarding mobile privacy practices.
+
+This guide on mobile app privacy should be considered a "primer" addressing some the most significant issues. It outlines some broadly accepted best practices and provides references to other more detailed guides and references.
+
+* **Privacy Policy**: You app should include a privacy policy that
+ addresses topics such as what kind of information your app collects
+ from or about your users, how that information is used, with whom it
+ is shared, and how users can make privacy-related choices within the
+ app. To aid understanding, you should use plain language and avoid
+ technical jargon. You should make your privacy policy available for
+ users to review prior to download, such as in the app description in
+ the app marketplace. In addition, you should make your privacy
+ policy available within the app itself. The limited size of mobile
+ device displays creates challenges for displaying privacy policies
+ to users. Consider developing a "short form" of the policy that
+ includes the most important information, and then provide a link to
+ the "long form" policy for those interested in more details. Several
+ groups are attempting to develop icon-based standards for
+ communicating privacy practices, which you may want to consider once
+ these standards mature.
+
+* **Collection of sensitive information**: An app's collection of
+ sensitive personal information raises important privacy concerns.
+ Examples of sensitive personal information include financial
+ information, health information, and information from or about
+ children. It also includes information gathered from certain sensors
+ and databases typically found on mobile devices and tablets, such as
+ geolocation information, contacts/phonebook, microphone/camera, and
+ stored pictures/videos. See the following documentation pages for
+ more information: [camera](cordova_camera_camera.md.html),
+ [capture](cordova_media_capture_capture.md.html),
+ [contacts](cordova_contacts_contacts.md.html), and
+ [geolocation](cordova_geolocation_geolocation.md.html). Generally,
+ you should obtain a user's express permission before collecting
+ sensitive information and, if possible, provide a control mechanism
+ that allows a user to easily change permissions. App operating
+ systems can help in some instances by presenting just-in-time dialog
+ boxes that ask for the user's permission before collection. In these
+ cases, be sure to take advantage of any opportunity to customize the
+ dialog box text to clarify how the app uses and, if applicable,
+ shares such information.
+
+* **Avoiding user surprise**: If your app collects or uses information
+ in a way that may be surprising to users in light of the primary
+ purpose of your app (for example, a music player that accesses
+ stored pictures), you should take similar steps as with the
+ collection of sensitive personal information. That is, you should
+ strongly consider the use of just-in-time dialog boxes to inform the
+ user about the collection or use of that information and, if
+ appropriate, provide a corresponding privacy control.
+
+* **Third party data collection or sharing**: If you app collects
+ information that is provided to another company--such as a social
+ networking platform or an ad network (for example, if your app
+ displays advertising)--you should inform your users of that
+ collection and sharing. At a minimum, your privacy policy should
+ describe the information collection and sharing and, if appropriate,
+ offer your users the ability to control or opt-out of such
+ collection or sharing.
+
+* **Collection limitation and security**: Your users entrust your app
+ with their information and they expect that you will take
+ appropriate security precautions to protect it. One of the best ways
+ to avoid security compromises of personal information is not to
+ collect the information in the first place unless your app has a
+ specific and legitimate business reason for the collection. For
+ information that does need to be collected, ensure that you provide
+ appropriate security controls to protect that information, whether
+ it is stored on the device or on your backend servers. You should
+ also develop an appropriate data retention policy that is
+ implemented within the app and on your backend servers.
+
+Following are some additional helpful mobile privacy guides for developers:
+
+* California Attorney General, [Privacy on the Go: Recommendations for the Mobile Ecosystem][1]
+
+* Center for Democracy & Technology, Future of Privacy Forum, [Best Practices for Mobile App Developers][2]
+
+* CTIA-The Wireless Association, [Best Practices and Guidelines for Location Based Services][3]
+
+* Federal Trade Commission, [Mobile Privacy Disclosures: Building Trust Through Transparency][4]
+
+* Future of Privacy Forum, [Application Privacy][5] Website
+
+[1]: http://oag.ca.gov/sites/all/files/pdfs/privacy/privacy_on_the_go.pdf
+[2]: http://www.futureofprivacy.org/wp-content/uploads/Best-Practices-for-Mobile-App-Developers_Final.pdf
+[3]: http://www.ctia.org/business_resources/wic/index.cfm/AID/11300
+[4]: http://www.ftc.gov/os/2013/02/130201mobileprivacyreport.pdf
+[5]: http://www.applicationprivacy.org