You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by ra...@apache.org on 2016/02/22 23:10:32 UTC
docs commit: CB-10333: Improving windows guide
Repository: cordova-docs
Updated Branches:
refs/heads/master ccb3cfd2e -> f5f39b3bf
CB-10333: Improving windows 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/f5f39b3b
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/f5f39b3b
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/f5f39b3b
Branch: refs/heads/master
Commit: f5f39b3bf9cbdadd67314896453f73e0f2381d77
Parents: ccb3cfd
Author: Raghav Katyal <ra...@microsoft.com>
Authored: Fri Feb 12 15:33:35 2016 -0800
Committer: Raghav Katyal <ra...@microsoft.com>
Committed: Mon Feb 22 14:10:14 2016 -0800
----------------------------------------------------------------------
www/docs/en/dev/config_ref/index.md | 6 +-
www/docs/en/dev/guide/platforms/win8/index.md | 225 ++++++++++---------
.../en/dev/guide/platforms/win8/packaging.md | 59 ++---
www/docs/en/dev/guide/platforms/win8/plugin.md | 118 ++++------
www/docs/en/dev/guide/platforms/win8/upgrade.md | 4 +-
5 files changed, 179 insertions(+), 233 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f5f39b3b/www/docs/en/dev/config_ref/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/dev/config_ref/index.md b/www/docs/en/dev/config_ref/index.md
index 1659c28..bbf712a 100644
--- a/www/docs/en/dev/config_ref/index.md
+++ b/www/docs/en/dev/config_ref/index.md
@@ -229,7 +229,7 @@ platform. See [Icons and Splash Screens](images.html) for more information.
LogLevel(string) | *Default: ERROR* <br/> Allowed values: ERROR, WARN, INFO, DEBUG, VERBOSE <br/> ==Android== <br/> Sets the minimum log level through which log messages from your application will be filtered.
MediaPlaybackAllowsAirPlay(boolean) | *Default: true* <br/> ==iOS== <br/> Set to false to prevent Air Play from being used in this view. Available in default UIWebView and WKWebView.
MediaPlaybackRequiresUserAction(boolean) | *Default: false* <br/> ==iOS== <br/> Set to true to prevent HTML5 videos or audios from playing automatically with the autoplay attribute or via JavaScript.
- Min/Max UAP(Regex) | Allowed values: **/(Microsoft.+? | Windows.+?)-(MinVersion | MaxVersionTested)/i** <br/> ==Windows== <br/> Sets the min/max UAP versions for Windows. If nothing is specified, Windows.Universal at version 10.0.10240.0 will be used.
+ Min/Max Version(Regex) | ==Windows== <br/> Allowed values: **/(Microsoft.+? | Windows.+?)-(MinVersion | MaxVersionTested)/i** <br/> Identifies the ecosystems and their min/max versions the app is compatible with. There are three parts to each value: the **SDK**, the **version restriction**, and the **version value**. These preferences are detected by beginning with `Windows` or `Microsoft` and ending in `-MinVersion` or `-MaxVersionTested`: <ul><li>The **SDK** defines what specialized platform you want to target. The default is `Windows.Universal`. Valid values for these are defined in the AppxManifest schema, in the `Package/Depednencies/TargetPlatform` elements.</li><li>The **version restriction** defines application compatibility rules. For example, if the `-MinVersion` is set to 10.1.0.0, then OS versions which don't support at least 10.1.0.0 of the corresponding SDK won't be able to load it. Similarly you can also use `-MaxVersionTested` which specifies the hig
hest-tested version of the SDK. If a new version of the corresponding SDK is released, it will run in compatibility mode for the specified version.</li><li>The **version value** is a 4-integer tuple in the form of *major.minor.build.qfe*.</li></ul> If no preferences of these types are specified in your config.xml file, then Windows.Universal version 10.0.0.0 will be chosen by default.
Orientation(string) | *Default: default* <br/> Allowed values: default, landscape, portait <br/> Allows you to lock orientation and prevent the interface from rotating in response to changes in orientation. <br/> **NOTE:** The default value means Cordova will strip the orientation preference entry from the platform's manifest/configuration file allowing the platform to fallback to its default behavior. For iOS, to specify both portrait & landscape mode you would use the platform specific value 'all'.
OverrideUserAgent(string) | ==Android== <br/> If set, the value will replace the old UserAgent of webview. It is helpful to identify the request from app/browser when requesting remote pages. Use with caution, this may causes compitiable issue with web servers. For most cases, use AppendUserAgent instead.
PageLength(float) | *Default: 0* <br/> ==iOS== <br/> The size of each page, in points, in the direction that the pages flow. When PaginationMode is right to left or left to right, this property represents the width of each page. When PaginationMode is topToBottom or bottomToTop, this property represents the height of each page. The default value is 0, which means the layout uses the size of the viewport to determine the dimensions of the page.
@@ -250,6 +250,7 @@ platform. See [Icons and Splash Screens](images.html) for more information.
target-device(string) | *Default: universal* <br/> Allowed values: handset, tablet, universal <br/> ==iOS== <br/> This property maps directly to TARGETED_DEVICE_FAMILY in the xcode project. Note that if you target universal (which is the default) you will need to supply screen shots for both iPhone and iPad or your app may be rejected.
windows-phone-target-version(string) | ==Windows== <br/> Sets the version of Windows Phone for which the package (resulting from ```cordova build```) will target. If none is specified, it will be set to the same version as ```windows-target-version``` (if found).
windows-target-version(string) | ==Windows== <br/> Sets the version of Windows for which the package (resulting from ```cordova build```) will target. If none is specified, it will be set to '8.1'.
+ WindowsDefaultUriPrefix(string) | ==Windows== <br/> Allowed values: `ms-appx://`, `ms-appx-web://` <br/> Identifies whether you want your app to target the local context or remote context as its startup URI. When building for Windows 10, the default is the remote context (`ms-appx-web://`). <br/> In order to have a local-mode application that is not impacted by Remote Mode capability restrictions, you must set this preference to `ms-appx://` and not declare any `<access>` elements with remote URIs. The local mode is the default for Windows 8.1
Examples:
@@ -299,6 +300,9 @@ platform. See [Icons and Splash Screens](images.html) for more information.
<preference name="windows-phone-target-version" value="8.1" />
<preference name="windows-target-version" value="8.1" />
<preference name="Windows.Universal" value="10.0.10240.0" />
+ <preference name="WindowsDefaultUriPrefix" value="ms-appx://"" />
+ <preference name="Windows.Mobile-MaxVersionTested" value="10.0.10031.0" />
+ <preference name="Windows.Universal-MinVersion" value="10.0.0.0" />
<!-- BlackBerry only preferences -->
<preference name="ChildBrowser" value="disable"/>
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f5f39b3b/www/docs/en/dev/guide/platforms/win8/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/dev/guide/platforms/win8/index.md b/www/docs/en/dev/guide/platforms/win8/index.md
index 911317e..71f3bee 100644
--- a/www/docs/en/dev/guide/platforms/win8/index.md
+++ b/www/docs/en/dev/guide/platforms/win8/index.md
@@ -26,19 +26,15 @@ This guide shows how to set up your SDK development environment to build
and deploy Cordova apps for Windows 8.1, Windows Phone 8.1, and
Windows 10 Universal App Platform. It shows how to use either shell tools
to generate and build apps, or the cross-platform Cordova CLI discussed in
-[The Command-Line Interface](../../cli/index.html). (See the [Overview](../../overview/index.html) for a comparison of these
+[The Command-Line Interface](../../cli/index.html). (See the [Overview](../../overview/index.html#development-paths) for a comparison of these
development options.) This section also shows how to modify Cordova apps
-within Visual Studio. Regardless of which approach you take, you need to
+within Visual Studio. Regardless of [which](../../overview/index.html#development-paths) approach you take, you need to
install the Visual Studio SDK, as described below.
-See [Upgrading Windows](upgrade.html) for information on how to upgrade existing
-Windows Cordova projects.
+Developers wishing to target Windows Phone 8 should use the wp8 platform,
+see [Windows Phone 8 Platform Guide](../wp8/index.html) for details (Warning, the wp8 platform is deprecated).
-Window Phone 8 (wp8) stays as a separate platform,
-see [Windows Phone 8 Platform Guide](../wp8/index.html) for details.
-
-Cordova WebViews running on Windows rely on Internet Explorer 11
-(Windows 8.1 and Windows Phone 8.1) as
+Cordova WebViews running on Windows rely on Internet Explorer 11 (Windows 8.1 and Windows Phone 8.1) as
their rendering engine, so as a practical matter you can use IE's
powerful debugger to test any web content that doesn't invoke Cordova
APIs. The Windows Phone Developer Blog provides
@@ -67,12 +63,7 @@ App compatibility is determined by the OS that the app targeted. Apps are forwa
but not backwardly-compatible, so an app targeting Windows 10 cannot run on 8.1, but
an app built for 8.1 can run on 10.
-Follow the instructions at
-[developer.windows.com](https://developer.windows.com/)
-to submit the app to Windows Store.
-
-To develop Cordova apps for Windows, you may use a PC running
-Windows, but you may also develop on a Mac, either by running a
+Cordova apps targeting Windows can be developed on a Mac, either by running a
virtual machine environment or by using Boot Camp to dual-boot a
Windows 8.1 partition. Consult these resources to set up the required
Windows development environment on a Mac:
@@ -82,90 +73,43 @@ Windows development environment on a Mac:
- [Parallels Desktop](http://msdn.microsoft.com/en-US/library/windows/apps/jj945424)
- [Boot Camp](http://msdn.microsoft.com/en-US/library/windows/apps/jj945423)
-
-## Using Cordova Shell Tools
-If you want to use Cordova's Windows-centered shell tools in
-conjunction with the SDK, you have two basic options:
-
-- Access them locally from project code generated by the CLI. They are
- available in the `platforms/windows/` directory after you add
- the `windows` platform as described below.
-
-- Download them from a separate distribution at
- [cordova.apache.org](https://www.apache.org/dist/cordova/platforms/).
- The Cordova distribution contains separate archives for each platform.
- Be sure to expand the appropriate archive, `cordova-windows` in
- this case, within an empty directory. The relevant batch utilities
- are available in `package/bin` directory. (Consult the
- __README__ file if necessary for more detailed directions.)
-
-These shell tools allow you to create, build, and run Windows apps.
-For information on the additional command-line interface that enables
-plugin features across all platforms, see Using Plugman to Manage
-Plugins.
-
-## Install the SDK
+## Installing the Requirements
Install any edition of
[Visual Studio](http://www.visualstudio.com/downloads) matching the version
requirements listed above.
-
+<br/><p align="center"><img src="{{ site.baseurl }}/static/img/guide/platforms/win8/win8_installSDK.png" /></p><br/>
For Windows 10, the Visual Studio installer has an option to install tools to
build Universal Windows Apps. You must ensure that this option is selected
when installing to install the required SDK.
-## Create a New Project
-
-At this point, to create a new project you can choose between the
-cross-platform CLI tool described in [The Command-Line Interface](../../cli/index.html), or
-the set of Windows-specific shell tools.
-The CLI approach below generates an app named _HelloWorld_
-within a new `hello` project directory:
-
- > cordova create hello com.example.hello HelloWorld
- > cd hello
- > cordova platform add windows
-
-Here's the corresponding lower-level shell-tool approach:
+## Project Configuration
- C:\path\to\cordova-windows\package\bin\create.bat C:\path\to\new\hello com.example.hello HelloWorld
+### Target Windows version
-This project targets Windows 8.1 as the default target OS. You can choose to target 10.0 (see "Configure target Windows version" below) for all builds, or you target specific a particular version during each build.
+After installation, you should be ready to develop apps targetting Windows platform. Refer to [The Command-Line Interface](../../cli/index.html) for details.
-## Build the Project
-
-If you are using the CLI in development, the project directory's
-top-level `www` directory contains the source files. Run either of
-these within the project directory to rebuild the app:
-
- > cordova build
- > cordova build windows # do not rebuild other platforms
- > cordova build windows --debug # generates debugging information
- > cordova build windows --release # signs the apps for release
-
-Here's the corresponding lower-level shell-tool approach:
-
- C:\path\to\project\cordova\build.bat --debug
- C:\path\to\project\cordova\build.bat --release
-
-The `clean` command helps flush out directories in preparation for the
-next `build`:
-
- C:\path\to\project\cordova\clean.bat
-
-## Configure target Windows version
-
-By default `build` command produces two packages: Windows 8.1 and Windows Phone 8.1.
+By default the `cordova build` command produces two packages: Windows 8.1 and Windows Phone 8.1.
To upgrade Windows package to version 10 the following configuration setting must be
added to configuration file (`config.xml`).
<preference name="windows-target-version" value="10.0" />
-Once you add this setting `build` command will start producing Windows 10 packages. For more information about Windows 10, look at
-the [Cordova for Windows 10](win10-support.html) documentation.
+Once you add this setting `build` command will start producing Windows 10 packages.
+
+### Considerations for target Windows version
+
+Windows 10 supports a new "Remote" mode for Cordova apps (and HTML apps in general). This mode enables
+apps to have much more freedom with respect to use of DOM manipulation and common web patterns such as the use
+of inline script, but does so by reducing the set of capabilities your app may use when
+submitted to the public Windows Store. For more information about Windows 10 and Remote Mode, look at
+the [Understanding Remote Mode vs Local Mode](#understanding-remote-mode-vs-local-mode) section.
+
+When using Remote Mode, developers are encouraged to apply a Content Security Policy (CSP) to their application
+to prevent script injection attacks.
### The --appx parameter
@@ -177,18 +121,7 @@ The build system will ignore the preference set in config.xml for the target Win
Valid values for the `--appx` flag are `8.1-win`, `8.1-phone`, and `uap` (for Windows 10 Universal Apps). These options also apply to the `cordova run` command.
-### Considerations for target Windows version
-
-Windows 10 supports a new "Remote" mode for Cordova apps (and HTML apps in general). This mode enables
-apps much more freedom with respect to use of DOM manipulation and common web patterns such as the use
-of inline script, but does so by reducing the set of capabilities your app may use when
-submitted to the public Windows Store. For more information about Windows 10 and Remote Mode, look at
-the [Cordova for Windows 10](win10-support.html) documentation.
-
-When using Remote Mode, developers are encouraged to apply a Content Security Policy (CSP) to their application
-to prevent script injection attacks.
-
-## Deploy the app
+### Deploy options
To deploy Windows package:
@@ -200,39 +133,41 @@ To deploy Windows Phone package:
> cordova run windows -- --phone # deploy app to Windows Phone 8.1 emulator
> cordova run windows --device -- --phone # deploy app to connected device
-You can use __cordova run windows --list__ to see all available targets and
-__cordova run windows --target=target_name -- --phone__ to run application on a
-specific device or emulator
-(for example, `cordova run windows --target="Emulator 8.1 720P 4.7 inch" -- --phone`).
+This command will give you the list of all available targets:
-You can also use __cordova run --help__ to see additional build and run
-options.
+ > cordova run windows --list
-## Open the Project in the SDK and Deploy the App
+This allows you to run the application on a specific device or emulator, in this case "Emulator 8.1 720p 4.7 inch"
-Once you build a Cordova app as described above, you can open it with
+ > cordova run windows --target="Emulator 8.1 720P 4.7 inch" -- --phone
+
+You can also use __cordova run --help__ to see additional build and run options.
+
+### Using Visual Studio to deploy the app
+
+Once you build a Cordova app, you can open it with
Visual Studio. The various `build` commands generate a Visual Studio
Solution (_.sln_) file. Open the file in the File Explorer to modify
the project within Visual Studio:
-
+<br/><p align="center"><img src="{{ site.baseurl }}/static/img/guide/platforms/win8/win8_sdk_openSLN.png" /></p><br/>
The `CordovaApp` component displays within the solution, and its `www`
directory contains the web-based source code, including the
`index.html` home page:
-
+<br/><p align="center"><img src="{{ site.baseurl }}/static/img/guide/platforms/win8/win8_sdk.png" /></p><br/>
-The controls below Visual Studio's main menu allow you to test or
+The projects for different Windows versions are displayed separately in the solution explorer. You can choose the deploy target version by right clicking the 'solution' (topmost entry in the solution explorer) and then going into 'Properties'. Here you can update the 'Single start up' field. The controls below Visual Studio's main menu allow you to test or
deploy the app:
-
+<br/><p align="center"><img src="{{ site.baseurl }}/static/img/guide/platforms/win8/win8_sdk_deploy.png" /></p><br/>
With __Local Machine__ selected, press the green arrow to install the
app on the same machine running Visual Studio. Once you do so, the app
appears in Windows' app listings:
-
+<br/><p align="center"><img src="{{ site.baseurl }}/static/img/guide/platforms/win8/win8_sdk_runApp.png" /></p><br/>
Each time you rebuild the app, the version available in the interface
is refreshed.
@@ -240,18 +175,18 @@ is refreshed.
Once available in the app listings, holding down the __CTRL__ key
while selecting the app allows you to pin it to the main screen:
-
+<br/><p align="center"><img src="{{ site.baseurl }}/static/img/guide/platforms/win8/win8_sdk_runHome.png" /></p><br/>
Note that if you open the app within a virtual machine environment,
you may need to click in the corners or along the sides of the windows
to switch apps or access additional functionality:
-
+<br/><p align="center"><img src="{{ site.baseurl }}/static/img/guide/platforms/win8/win8_sdk_run.png" /></p><br/>
Alternately, choose the __Simulator__ deployment option to view the
app as if it were running on a tablet device:
-
+<br/><p align="center"><img src="{{ site.baseurl }}/static/img/guide/platforms/win8/win8_sdk_sim.png" /></p><br/>
Unlike desktop deployment, this option allows you to simulate the
tablet's orientation, location, and vary its network settings.
@@ -263,16 +198,86 @@ platform-specific files used by the SDK. If you want to use the SDK to
modify the project, use the lower-level shell tools as an alternative
to the CLI.
+## Debugging
+
+Visual Studio provides powerful tools to debug your application. You can refer to [this](https://msdn.microsoft.com/en-us/library/7seh8d72.aspx) article to get started with it.
+
+## Platform Centered Workflow
+
+If you want to use Cordova's Windows-centered shell tools in conjunction with the SDK, you have two basic options:
+
+- Access them locally from project code generated by the CLI. They are
+ available in the `platforms/windows/` directory after you add
+ the `windows` platform as described below.
+
+- Download them from a separate distribution
+ [here](https://www.apache.org/dist/cordova/platforms/).
+ The Cordova distribution contains separate archives for each platform.
+ Be sure to expand the appropriate archive, `cordova-windows` in
+ this case, within an empty directory. The relevant batch utilities
+ are available in `package/bin` directory. (Consult the
+ __README__ file if necessary for more detailed directions.)
+
+These shell tools allow you to create, build, and run Windows apps. Each cordova command corresponds to one of these shell tool scripts.
+
+For example, the lower-level shell-tool approach corresponding to `cordova create HelloWorld` is:
+
+```
+C:\path\to\cordova-windows\package\bin\create.bat C:\path\to\new\hello HelloWorld
+```
+
+Similarly for `cordova build --debug`:
+
+```
+C:\path\to\project\cordova\build.bat --debug
+```
+
+## Upgrading
+
+Refer to [this](upgrade.html) article for instructions to upgrade your `cordova-windows` version.
+
## Supporting Toasts
Windows requires an app manifest capability declaration in order to support
toast notifications. When using the `cordova-plugin-local-notifications`
plugin, or any other plugin that is attempting to use toast notifications,
add the following preference to your config.xml to enable it to publish
-toast notifications:
+toast notifications, unless the plugin makes that change on it's own:
<preference name="WindowsToastCapable" value="true" />
-This preference sets the corresponding flag in your app manifest. Plugins
+This preference sets the corresponding flag in your app manifest. Plugins
should do the work necessary to configure the appearance of the
displayed notifications.
+
+## Understanding Remote Mode vs Local Mode
+Windows 10 introduces a new feature called "Remote mode" for HTML applications. Prior to it, Windows 8.1 apps
+worked on what is now termed as "Local Mode" in Windows 10, in which HTML Applications have full access to the native
+Windows API surface and capabilities. Local Mode disallows inline script in order to prevent script injection attacks,
+which could result in leaking personally-identifiable information due to malicious code. It also requires developers who
+perform DOM manipulation to do so within an explicit context
+(`MSApp.execUnsafeLocalFunction`).
+
+Remote Mode eliminates those requirements, which makes it possible to use unmodified libraries like jQuery
+or AngularJS directly in your code, without any changes. To do so, it removes your ability to declare certain
+capabilities when certifying your app in the Windows Store. The removal of these capabilities usually doesn't
+prevent accessing certain functionality, but it might require the use of a different combination of APIs or tactics.
+
+## Effect of Remote Mode on capabilities
+The following capabilities are unavailable when deploying your Remote Mode application to the Windows Store:
+
+- Enterprise Authentication (`enterpriseAuthentication`)
+- Shared User Certificates (`sharedUserCertificates`)
+- Documents Library (`documentsLibrary`)
+- Music Library (`musicLibrary`)
+- Pictures Library (`picturesLibrary`)
+- Videos Library (`videosLibrary`)
+- Removable [Storage](../../../cordova/storage/storage.html) (`removableStorage`)
+- Internet client/server (`internetClientServer`) - note that `internetClient` is still permitted
+- Private network client/server (`privateNetworkClientServer`)
+
+Each of the library restrictions may be worked around by requesting that the user interact with the file system via a [File Picker](https://msdn.microsoft.com/en-us/library/windows/apps/windows.storage.pickers.fileopenpicker.aspx). This prevents malicious injected code from arbitrarily accessing the file system.
+
+The network-related restrictions must be worked around by either using an API that doesn't use capability checks or by brokering communication via standard internet communication channels, such as `XMLHttpRequest` or Web Sockets.
+
+The Enterprise Authentication and Shared User Certificates capabilities are specifically targeted at Enterprise scenarios. These capabilities are supported for private/enterprise-enabled App Stores, so if you are building apps which are going to be deployed to an internal deployment mechanism, you can still support these. However, they are not supported for Remote Mode apps in the public Windows Store. When you build targeting Windows 10, if one of these capabilities is detected in your app manifest, a warning will be displayed.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f5f39b3b/www/docs/en/dev/guide/platforms/win8/packaging.md
----------------------------------------------------------------------
diff --git a/www/docs/en/dev/guide/platforms/win8/packaging.md b/www/docs/en/dev/guide/platforms/win8/packaging.md
index 76683c5..8c8b48c 100644
--- a/www/docs/en/dev/guide/platforms/win8/packaging.md
+++ b/www/docs/en/dev/guide/platforms/win8/packaging.md
@@ -20,7 +20,7 @@ license: >
title: Windows Packaging
---
-# Windows Packaging
+# Signing an App
You can learn more about signing and packaging of Windows Store Apps on [MSDN][1].
@@ -41,8 +41,15 @@ In Windows project, identity details are kept in a file named package.appxmanife
A signing certificate can be provided from either CLI or through build.json file. The certificate related CLI flags are:
-- `--packageCertificateKeyFile` : Once a package signing certificate is created, this parameter can be used to associate the certificate with the app. This flag takes a file path as an argument. Eg. `> cordova build -- --packageCertificateKeyFile="platforms\windows\CordovaApp_TemporaryKey.pfx"`
-- `--packageThumbprint` : Package thumbprint is used to validate the authenticity of package certificate key file. When creating a certificate key file, this value will be provided to the end user. Eg. `> cordova build -- --packageCertificateKeyFile="platforms\windows\CordovaApp_TemporaryKey.pfx" --packageThumbprint="ABCABCABCABC123123123123"`
+| Parameter | Flag | Description
+|-----------------------|-------------------|-----------------------------------
+| Certificate File | `--packageCertificateKeyFile` | Path to the package signing certificate to be associated with the app
+| Thumb Print | `--packageThumbprint` | Used to validate the authenticity of package certificate key file. When creating a certificate key file, this value will be provided to the end user
+
+Example:
+```
+cordova build -- --packageCertificateKeyFile="platforms\windows\CordovaApp_TemporaryKey.pfx" --packageThumbprint="ABCABCABCABC123123123123"`
+```
Alternatively, these values could be specified using a build configuration file (build.json) using CLI (--buildConfig). A sample build configuration file:
@@ -61,44 +68,10 @@ Alternatively, these values could be specified using a build configuration file
There is also support to mix and match command line arguments and parameters in build.json file. Values from the command line arguments will get precedence.
-# How to create a certificate key and sign Cordova windows Apps
-Signing is required for distributing and installing Windows Store apps. This process is normally handled by Visual Studio when you deploy a package for release. To do tmhis without Visual Studio we need to create our own certificates.
-
-For creating certificates we need to use [makecert.exe][2] util. This tool ships with Windows SDK and can be found under `%ProgramFiles(x86)%\Windows Kits\8.1\bin\x64` or `%ProgramFiles(x86)%\Windows Kits\8.1\bin\x86`.
-
-The first thing we need to do is to create a root key for signing our app.
-
-`makecert.exe -n "CN=FakeCorp.com" -r -eku "1.3.6.1.5.5.7.3.3,1.3.6.1.4.1.311.10.3.13" -e "01/01/2020" –h 0 -sv FakeCorp.com.pvk FakeCorp.com.cer`
-
-To understand what makecert does, here's a brief explanation of what parameters do:
-
-- -n "CN=FakeCorp.com" : This is the certificate subject [X.509](http://en.wikipedia.org/wiki/X.509) name. In this example it's **C**ommon**N**ame=FakeCorp.com.
-- -r : Creates a [self signed certificate](http://en.wikipedia.org/wiki/Self-signed_certificate).
-- -eku #EKU_VAL# : Comma separated enhanced key usage OIDs.
- - 1.3.6.1.5.5.7.3.3 indicates that the certificate is valid for code signing. Always specify this value to limit the intended use for the certificate.
- - 1.3.6.1.4.1.311.10.3.13 indicates that the certificate respects lifetime signing. Typically, if a signature is time stamped, as long as the certificate was valid at the point when it was time stamped, the signature remains valid even if the certificate expires. This EKU forces the signature to expire regardless of whether the signature is time stamped.
-- -e "01/01/2020" : Sets the expiration date of the certificate.
-- -h 0 : Sets max height of the tree below this cert to 0 to prevent the certificate from being used as a Certification Authority (CA) that can issue other certificates.
-- -sv FakeCorp.com.pvk : Output PVK file. Windows uses PVK files to store private keys for code signing.
-- FakeCorp.com.cer : Output certificate file. CER file is used to store X.509 certificate.
-
-After running makecert for the first time, enter the private password on the screen that pops up:
-
-
-
-Once pvk and cer file is created, we need to create a pfx file from these certificates. A pfx (Personal Exchange Format) file contains a variety of cryptographic information, such as certificates, root authority certificates, certificate chains and private keys. To package the certs, we will use the a tool called [pvk2pfx][3]. This tool ships with Windows SDK and can be found under `%ProgramFiles(x86)%\Windows Kits\8.1\bin\x64` or `%ProgramFiles(x86)%\Windows Kits\8.1\bin\x86`.
-
-`pvk2pfx -pvk FakeCorp.com.pvk -pi pvkPassword -spc FakeCorp.com.cer -pfx FakeCorp.com.pfx -po pfxPassword`
-
-Where:
-
-- pvk : Input pvk file name
-- pi : pvk password
-- spc : Input cert file name
-- pfx : Output pfx file name
-- po : pfx password; same as pvk password if not provided
+## Creating a certificate key
+Signing is required for distributing and installing Windows Store apps. This process is normally handled by Visual Studio when you deploy a package for release. To do this without Visual Studio we need to create our own certificates. [This](https://msdn.microsoft.com/en-us/library/windows/desktop/jj835832(v=vs.85).aspx) article has instructions on how to do that.
-If we provide this pfx file to build.json file, we will have the following error: "The key file may be password protected. To correct this, try to import the certificate manually into the current user's personal certificate store.". In order to import it we have to use [certutil][4] from an admin prompt:
+Once you have the pfx file created and provided to build.json file, you might get the following error: "The key file may be password protected. To correct this, try to import the certificate manually into the current user's personal certificate store.". In order to import it you have to use [certutil][2] from an admin prompt:
`certutil -user -p PASSWORD -importPFX FakeCorp.com.pfx`
@@ -108,13 +81,11 @@ Where:
- p : Password for pfx file
- importPfx : Name of pfx file
-Once installed, next step is to add packageThumbprint and packageCertificateKeyFile to build.json. In order to find the packageThumbprint, search for the CommonName we've associated with the certificate:
+Once installed, next step is to add packageThumbprint and packageCertificateKeyFile to build.json. In order to find the packageThumbprint, search for the CommonName you've associated with the certificate:
`powershell -Command " & {dir -path cert:\LocalMachine\My | where { $_.Subject -like \"*FakeCorp.com*\" }}"`
Once these final values are provided. Cordova should successfully package and sign the app.
[1]: https://msdn.microsoft.com/en-us/library/hh446593(v=vs.85).aspx
-[2]: https://msdn.microsoft.com/en-us/library/ff548309(v=vs.85).aspx
-[3]: https://msdn.microsoft.com/en-us/library/ff550672(v=vs.85).aspx
-[4]: https://technet.microsoft.com/en-us/library/ee624045(v=ws.10).aspx
+[2]: https://technet.microsoft.com/en-us/library/ee624045(v=ws.10).aspx
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f5f39b3b/www/docs/en/dev/guide/platforms/win8/plugin.md
----------------------------------------------------------------------
diff --git a/www/docs/en/dev/guide/platforms/win8/plugin.md b/www/docs/en/dev/guide/platforms/win8/plugin.md
index 6a49de6..300dc9a 100644
--- a/www/docs/en/dev/guide/platforms/win8/plugin.md
+++ b/www/docs/en/dev/guide/platforms/win8/plugin.md
@@ -23,19 +23,16 @@ title: Windows Plugins
# Windows Plugins
This section provides details for how to implement a plugin for use in
-a Windows Store app. Before reading this, see Application Plugins for
+a Windows Store app. Before reading this, see Create your fist plugin for
an overview of the plugin's structure and its common JavaScript interface.
This section continues to demonstrate the sample _echo_ plugin that
communicates from the Cordova webview to the native platform and back.
-It is important to note that Windows supports developing directly in Javascript, which means developing the 'native' portions in only required in special cases.
+## Creating a Windows Plugin in JavaScript
-Creating a Windows 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.
+These instructions are to create a pure JavaScript plugin.
-Windows Cordova plugins are essentially a thin wrapper around existing WinJS provided functions, but assuming you will want to define your JS common interface for multiple devices, you will typically have 1 JS file that provides the API.
+Windows Cordova plugins are essentially a thin wrapper around existing WinJS provided functions, but assuming you will want to define your JS common interface for multiple devices, you will typically have one JS file that provides the API.
// inside file echoplugin.js
var EchoPlugin = {
@@ -46,61 +43,43 @@ Windows Cordova plugins are essentially a thin wrapper around existing WinJS pro
}
}
-Inside Cordova exec on Windows
----
-
-The cordova.exec function is defined differently on every platform, this is because each platform has it's own way of communicating between the application js code, and the native wrapper code. But in the case of Windows, there is no native wrapper, so the exec call is there for consistency. 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, 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
-The Cordova exec proxy
----
+The `cordova.exec` function is defined differently on every platform, this is because each platform has it's own way of communicating between the application js code, and the native wrapper code. But in the case of Windows, there is no native wrapper, so the exec call is there for consistency. So even though you could write the Windows specific code as a part of plugin's common JS code directly, this is not recommended and plugin authors should use the same exec API for Windows as for other platforms. This way the plugin API becomes consistent and you can also take advantage of any parameter checking, or other common code provided by developers who were working on other platforms.
-On Windows, cordova provides a proxy that you can use to register an object that will handle all cordova.exec calls to an API.
+On Windows, cordova provides a proxy that you can use to register an object that will handle all cordova.exec calls to an API. So in our case, we will assume that the code in `echoplugin.js` is handling cross platform relevant JavaScript, and we can simply write a proxy for Windows.
-For example if you wanted to provide the implementation for the Accelerometer API, you would do this :
+```
+// in file echoplugin.js
+window.echo = function(str, callback) {
+ cordova.exec(callback, function(err) {
+ callback('Nothing to echo.');
+ }, "Echo", "echo", [str]);
+};
+```
-cordova.commandProxy.add("Accelerometer",{
- start:function(){
- // your code here ...
+```
+// in file echopluginProxy.js
+cordova.commandProxy.add("Echo",{
+ echo:function(successCallback,errorCallback,strInput) {
+ if(!strInput || !strInput.length) {
+ errorCallback("Error, something was wrong with the input string. =>" + strInput);
+ }
+ else {
+ successCallback(strInput + "echo");
+ }
}
- // ,
- // ... 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
-
- // 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 `echoplugin.js` file will forward the `echo` function call to this proxy through the `cordova.exec` command and execute this implementation.
-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)
+The plugin.xml file will have the settings required for our plugin. In this case, we want to add our `echoplugin.js` file in the `www` directory and the `echopluginProxy.js` file inside the `windows` source code of our application. Details of these elements can be found in the [Plugin.xml](../../plugin_ref/spec.html) reference.
<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
- id="com.risingj.echoplugin"
+ id="echoplugin"
version="0.1.0">
<js-module src="www/echoplugin.js" name="echoplugin">
@@ -120,13 +99,11 @@ If we want users of our plugin to be able to easily install our plugin, we will
This gives us a working Windows JavaScript plugin that uses a common file ( echoplugin.js ) and uses a proxy to provide the Windows only portion of implementation ( echopluginProxy.js ). So how do we add native/managed code to this? Well we are going to start the same, the only difference will be what we do inside in echopluginProxy methods.
-How WinJS accesses native/managed code
-===
-
+## How WinJS accesses native/managed code
In Windows, WinJS authored apps are able to interact with native code, this inter-op is available for Windows Runtime Components. The details are numerous, and this guide will only cover the basics. Microsoft provides much more info [here](http://msdn.microsoft.com/en-us/library/windows/apps/hh441569.aspx).
-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.
+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
@@ -156,8 +133,11 @@ When you create your Windows Runtime Component, any class that is defined as 'pu
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 :
+```
+
+Moving this to our echopluginProxy.js file, we get:
// in file echopluginProxy.js
cordova.commandProxy.add("EchoPlugin",{
@@ -174,22 +154,18 @@ Moving this to our echopluginProxy.js file, we get this :
And that's it, we have an end to end C++ backed js callable plugin for use in Apache Cordova Windows!
-Some technical notes:
-===
+## Considerations
-- the callback is typically async, so calling the callback right away is probably not expected by the caller. In practice, if the call is not async, you should at least use a javascript timeout to force the callback to be called 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.0 and Windows SDK API calls, you will be able to use the same runtime component ( native or managed bits ) in a Windows Phone 8.0 Apache Cordova plugin. ~stay tuned for that post.
+- The callback is typically async, so calling the callback right away is probably not expected by the caller. In practice, if the call is not async, you should at least use a javascript timeout to force the callback to be called asynchronously.
+- Activatable classes can be used to do event dispatching, async callbacks, passing your own object types, arrays, collections, overloaded methods and much more. Refer [here](http://msdn.microsoft.com/en-us/library/windows/apps/hh441569.aspx) for details.
-Defining your plugin
-===
+## 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
+Now that we have a working plugin, we need to revisit the plugin definition from earlier so we can publish it. We can now add the runtime component as a framework, through the `<framework>` tag inside our platfrom settings. Note that the output type of a WindowsRuntimeComponent can be either .winmd or .dll
<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
- id="com.risingj.echoplugin"
+ id="echoplugin"
version="0.2.0">
<js-module src="www/echoplugin.js" name="echoplugin">
@@ -208,14 +184,4 @@ Note that the output type of a WindowsRuntimeComponent can be either .winmd or .
</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 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 windows --plugin com.risingj.echoplugin --project .
-
-https://github.com/purplecabbage/cordova-runtimecomp-echoplug
-
+That's it, you now have a distributable plugin that you can share with the world!
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f5f39b3b/www/docs/en/dev/guide/platforms/win8/upgrade.md
----------------------------------------------------------------------
diff --git a/www/docs/en/dev/guide/platforms/win8/upgrade.md b/www/docs/en/dev/guide/platforms/win8/upgrade.md
index a189c04..cc39ee3 100644
--- a/www/docs/en/dev/guide/platforms/win8/upgrade.md
+++ b/www/docs/en/dev/guide/platforms/win8/upgrade.md
@@ -22,7 +22,7 @@ title: Upgrading Windows
# Upgrading Windows
-Run `cordova platform update windows`.
+For upgrading from `windows` version 4.0.0 or higher, run `cordova platform update windows`.
For projects not created with the cordova CLI, run:
@@ -31,7 +31,7 @@ For projects not created with the cordova CLI, run:
# Upgrading Windows 8
-This guide shows how to modify Windows 8 projects to upgrade from older versions of Cordova.
+This is for people still using `windows8` platform 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 Command-Line Interface](../../cli/index.html) for information how to update the
version of the CLI.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org