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/05/16 21:53:16 UTC
[1/3] docs commit: Snapshotting dev to 6.x
Repository: cordova-docs
Updated Branches:
refs/heads/master 1a1cbcc10 -> 1360af4b5
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-file/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-file/index.md b/www/docs/en/6.x/reference/cordova-plugin-file/index.md
index c705a32..dc21546 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-file/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-file/index.md
@@ -37,7 +37,7 @@ This plugin is based on several specs, including :
The HTML5 File API
[http://www.w3.org/TR/FileAPI/](http://www.w3.org/TR/FileAPI/)
-The (now-defunct) Directories and System extensions
+The Directories and System extensions
Latest:
[http://www.w3.org/TR/2012/WD-file-system-api-20120417/](http://www.w3.org/TR/2012/WD-file-system-api-20120417/)
Although most of the plugin code was written when an earlier spec was current:
@@ -46,10 +46,12 @@ Although most of the plugin code was written when an earlier spec was current:
It also implements the FileWriter spec :
[http://dev.w3.org/2009/dap/file-system/file-writer.html](http://dev.w3.org/2009/dap/file-system/file-writer.html)
-For usage, please refer to HTML5 Rocks' excellent [FileSystem article.](http://www.html5rocks.com/en/tutorials/file/filesystem/)
+>*Note* While the W3C FileSystem spec is deprecated for web browsers, the FileSystem APIs are supported in Cordova applications with this plugin for the platforms listed in the _Supported Platforms_ list, with the exception of the Browser platform.
+
+To get a few ideas how to use the plugin, check out the [sample](#sample) at the bottom of this page. For additional examples (browser focused), see the HTML5 Rocks' [FileSystem article.](http://www.html5rocks.com/en/tutorials/file/filesystem/)
For an overview of other storage options, refer to Cordova's
-[storage guide](http://cordova.apache.org/docs/en/edge/cordova_storage_storage.md.html).
+[storage guide](http://cordova.apache.org/docs/en/latest/cordova/storage/storage.html).
This plugin defines global `cordova.file` object.
@@ -283,6 +285,14 @@ Listing asset directories is really slow on Android. You can speed it up though,
adding `src/android/build-extras.gradle` to the root of your android project (also
requires cordova-android@4.0.0 or greater).
+### Permisson to write to external storage when it's not mounted on Marshmallow
+
+Marshmallow requires the apps to ask for permissions when reading/writing to external locations. By
+[default](http://developer.android.com/guide/topics/data/data-storage.html#filesExternal), your app has permission to write to
+`cordova.file.applicationStorageDirectory` and `cordova.file.externalApplicationStorageDirectory`, and the plugin doesn't request permission
+for these two directories unless external storage is not mounted. However due to a limitation, when external storage is not mounted, it would ask for
+permission to write to `cordova.file.externalApplicationStorageDirectory`.
+
## iOS Quirks
- `cordova.file.applicationStorageDirectory` is read-only; attempting to store
@@ -548,3 +558,314 @@ Android also supports a special filesystem named "documents", which represents a
* `root`: The entire device filesystem
By default, the library and documents directories can be synced to iCloud. You can also request two additional filesystems, `library-nosync` and `documents-nosync`, which represent a special non-synced directory within the `/Library` or `/Documents` filesystem.
+
+## Sample: Create Files and Directories, Write, Read, and Append files <a name="sample"></a>
+
+The File plugin allows you to do things like store files in a temporary or persistent storage location for your app (sandboxed storage) and to store files in other platform-dependent locations. The code snippets in this section demonstrate different tasks including:
+* [Accessing the file system](#persistent)
+* Using cross-platform Cordova file URLs to [store your files](#appendFile) (see _Where to Store Files_ for more info)
+* Creating [files](#persistent) and [directories](#createDir)
+* [Writing to files](#writeFile)
+* [Reading files](#readFile)
+* [Appending files](#appendFile)
+* [Display an image file](#displayImage)
+
+## Create a persistent file <a name="persistent"></a>
+
+Before you use the File plugin APIs, you can get access to the file system using `requestFileSystem`. When you do this, you can request either persistent or temporary storage. Persistent storage will not be removed unless permission is granted by the user.
+
+When you get file system access using `requestFileSystem`, access is granted for the sandboxed file system only (the sandbox limits access to the app itself), not for general access to any file system location on the device. (To access file system locations outside the sandboxed storage, use other methods such as window.requestLocalFileSystemURL, which support platform-specific locations. For one example of this, see _Append a File_.)
+
+Here is a request for persistent storage.
+
+>*Note* When targeting WebView clients (instead of a browser) or native apps (Windows), you dont need to use `requestQuota` before using persistent storage.
+
+```js
+window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) {
+
+ console.log('file system open: ' + fs.name);
+ fs.root.getFile("newPersistentFile.txt", { create: true, exclusive: false }, function (fileEntry) {
+
+ console.log("fileEntry is file?" + fileEntry.isFile.toString());
+ // fileEntry.name == 'someFile.txt'
+ // fileEntry.fullPath == '/someFile.txt'
+ writeFile(fileEntry, null);
+
+ }, onErrorCreateFile);
+
+}, onErrorLoadFs);
+```
+
+The success callback receives FileSystem object (fs). Use `fs.root` to return a DirectoryEntry object, which you can use to create or get a file (by calling `getFile`). In this example, `fs.root` is a DirectoryEntry object that represents the persistent storage in the sandboxed file system.
+
+The success callback for `getFile` receives a FileEntry object. You can use this to perform file write and file read operations.
+
+## Create a temporary file
+
+Here is an example of a request for temporary storage. Temporary storage may be deleted by the operating system if the device runs low on memory.
+
+```js
+window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+ console.log('file system open: ' + fs.name);
+ createFile(fs.root, "newTempFile.txt", false);
+
+}, onErrorLoadFs);
+```
+When you are using temporary storage, you can create or get the file by calling `getFile`. As in the persistent storage example, this will give you a FileEntry object that you can use for read or write operations.
+
+```js
+function createFile(dirEntry, fileName, isAppend) {
+ // Creates a new file or returns the file if it already exists.
+ dirEntry.getFile(fileName, {create: true, exclusive: false}, function(fileEntry) {
+
+ writeFile(fileEntry, null, isAppend);
+
+ }, onErrorCreateFile);
+
+}
+```
+
+## Write to a file <a name="writeFile"></a>
+
+Once you have a FileEntry object, you can write to the file by calling `createWriter`, which returns a FileWriter object in the success callback. Call the `write` method of FileWriter to write to the file.
+
+```js
+function writeFile(fileEntry, dataObj) {
+ // Create a FileWriter object for our FileEntry (log.txt).
+ fileEntry.createWriter(function (fileWriter) {
+
+ fileWriter.onwriteend = function() {
+ console.log("Successful file read...");
+ readFile(fileEntry);
+ };
+
+ fileWriter.onerror = function (e) {
+ console.log("Failed file read: " + e.toString());
+ };
+
+ // If data object is not passed in,
+ // create a new Blob instead.
+ if (!dataObj) {
+ dataObj = new Blob(['some file data'], { type: 'text/plain' });
+ }
+
+ fileWriter.write(dataObj);
+ });
+}
+```
+
+## Read a file <a name="readFile"></a>
+
+You also need a FileEntry object to read an existing file. Use the file property of FileEntry to get the file reference, and then create a new FileReader object. You can use methods like `readAsText` to start the read operation. When the read operation is complete, `this.result` stores the result of the read operation.
+
+```js
+function readFile(fileEntry) {
+
+ fileEntry.file(function (file) {
+ var reader = new FileReader();
+
+ reader.onloadend = function() {
+ console.log("Successful file read: " + this.result);
+ displayFileData(fileEntry.fullPath + ": " + this.result);
+ };
+
+ reader.readAsText(file);
+
+ }, onErrorReadFile);
+}
+```
+
+## Append a file using alternative methods <a name="appendFile"></a>
+
+Of course, you will often want to append existing files instead of creating new ones. Here is an example of that. This example shows another way that you can access the file system using window.resolveLocalFileSystemURL. In this example, pass the cross-platform Cordova file URL, cordova.file.dataDirectory, to the function. The success callback receives a DirectoryEntry object, which you can use to do things like create a file.
+
+```js
+window.resolveLocalFileSystemURL(cordova.file.dataDirectory, function (dirEntry) {
+ console.log('file system open: ' + dirEntry.name);
+ var isAppend = true;
+ createFile(dirEntry, "fileToAppend.txt", isAppend);
+}, onErrorLoadFs);
+```
+
+In addition to this usage, you can use `resolveLocalFileSystemURL` to get access to some file system locations that are not part of the sandboxed storage system. See _Where to store Files_ for more information; many of these storage locations are platform-specific. You can also pass cross-platform file system locations to `resolveLocalFileSystemURL` using the _cdvfile protocol_.
+
+For the append operation, there is nothing new in the `createFile` function that is called in the preceding code (see the preceding examples for the actual code). `createFile` calls `writeFile`. In `writeFile`, you check whether an append operation is requested.
+
+Once you have a FileWriter object, call the `seek` method, and pass in the index value for the position where you want to write. In this example, you also test whether the file exists. After calling seek, then call the write method of FileWriter.
+
+```js
+function writeFile(fileEntry, dataObj, isAppend) {
+ // Create a FileWriter object for our FileEntry (log.txt).
+ fileEntry.createWriter(function (fileWriter) {
+
+ fileWriter.onwriteend = function() {
+ console.log("Successful file read...");
+ readFile(fileEntry);
+ };
+
+ fileWriter.onerror = function (e) {
+ console.log("Failed file read: " + e.toString());
+ };
+
+ // If we are appending data to file, go to the end of the file.
+ if (isAppend) {
+ try {
+ fileWriter.seek(fileWriter.length);
+ }
+ catch (e) {
+ console.log("file doesn't exist!");
+ }
+ }
+ fileWriter.write(dataObj);
+ });
+}
+```
+
+## Store an existing binary file <a name="binaryFile"></a>
+
+We already showed how to write to a file that you just created in the sandboxed file system. What if you need to get access to an existing file and convert that to something you can store on your device? In this example, you obtain a file using an xhr request, and then save it to the cache in the sandboxed file system.
+
+Before you get the file, get a FileSystem reference using `requestFileSystem`. By passing window.TEMPORARY in the method call (same as before), the returned FileSystem object (fs) represents the cache in the sandboxed file system. Use `fs.root` to get the DirectoryEntry object that you need.
+
+```js
+window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+ console.log('file system open: ' + fs.name);
+ getSampleFile(fs.root);
+
+}, onErrorLoadFs);
+```
+
+For completeness, here is the xhr request to get a Blob image. There is nothing Cordova-specific in this code, except that you forward the DirectoryEntry reference that you already obtained as an argument to the saveFile function. You will save the blob image and display it later after reading the file (to validate the operation).
+
+```js
+function getSampleFile(dirEntry) {
+
+ var xhr = new XMLHttpRequest();
+ xhr.open('GET', 'http://cordova.apache.org/static/img/cordova_bot.png', true);
+ xhr.responseType = 'blob';
+
+ xhr.onload = function() {
+ if (this.status == 200) {
+
+ var blob = new Blob([this.response], { type: 'image/png' });
+ saveFile(dirEntry, blob, "downloadedImage.png");
+ }
+ };
+ xhr.send();
+}
+```
+>*Note* For Cordova 5 security, the preceding code requires that you add the domain name, http://cordova.apache.org, to the Content-Security-Policy <meta> element in index.html.
+
+After getting the file, copy the contents to a new file. The current DirectoryEntry object is already associated with the app cache.
+
+```js
+function saveFile(dirEntry, fileData, fileName) {
+
+ dirEntry.getFile(fileName, { create: true, exclusive: false }, function (fileEntry) {
+
+ writeFile(fileEntry, fileData);
+
+ }, onErrorCreateFile);
+}
+```
+
+In writeFile, you pass in the Blob object as the dataObj and you will save that in the new file.
+
+```js
+function writeFile(fileEntry, dataObj, isAppend) {
+
+ // Create a FileWriter object for our FileEntry (log.txt).
+ fileEntry.createWriter(function (fileWriter) {
+
+ fileWriter.onwriteend = function() {
+ console.log("Successful file write...");
+ if (dataObj.type == "image/png") {
+ readBinaryFile(fileEntry);
+ }
+ else {
+ readFile(fileEntry);
+ }
+ };
+
+ fileWriter.onerror = function(e) {
+ console.log("Failed file write: " + e.toString());
+ };
+
+ fileWriter.write(dataObj);
+ });
+}
+```
+
+After writing to the file, read it and display it. You saved the image as binary data, so you can read it using FileReader.readAsArrayBuffer.
+
+```js
+function readBinaryFile(fileEntry) {
+
+ fileEntry.file(function (file) {
+ var reader = new FileReader();
+
+ reader.onloadend = function() {
+
+ console.log("Successful file write: " + this.result);
+ displayFileData(fileEntry.fullPath + ": " + this.result);
+
+ var blob = new Blob([new Uint8Array(this.result)], { type: "image/png" });
+ displayImage(blob);
+ };
+
+ reader.readAsArrayBuffer(file);
+
+ }, onErrorReadFile);
+}
+```
+
+After reading the data, you can display the image using code like this. Use window.URL.createObjectURL to get a DOM string for the Blob image.
+
+```js
+function displayImage(blob) {
+
+ // Displays image if result is a valid DOM string for an image.
+ var elem = document.getElementById('imageFile');
+ // Note: Use window.URL.revokeObjectURL when finished with image.
+ elem.src = window.URL.createObjectURL(blob);
+}
+```
+
+## Display an image file <a name="displayImage"></a>
+
+To display an image using a FileEntry, you can call the `toURL` method.
+
+```js
+function displayImageByFileURL(fileEntry) {
+ var elem = document.getElementById('imageFile');
+ elem.src = fileEntry.toURL();
+}
+```
+
+If you are using some platform-specific URIs instead of a FileEntry and you want to display an image, you may need to include the main part of the URI in the Content-Security-Policy <meta> element in index.html. For example, on Windows 10, you can include `ms-appdata:` in your <meta> element. Here is an example.
+
+```html
+<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: ms-appdata: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">
+```
+
+## Create Directories <a name="createDir"></a>
+
+In the code here, you create directories in the root of the app storage location. You could use this code with any writable storage location (that is, any DirectoryEntry). Here, you write to the application cache (assuming that you used window.TEMPORARY to get your FileSystem object) by passing fs.root into this function.
+
+This code creates the /NewDirInRoot/images folder in the application cache. For platform-specific values, look at _File System Layouts_.
+
+```js
+function createDirectory(rootDirEntry) {
+ rootDirEntry.getDirectory('NewDirInRoot', { create: true }, function (dirEntry) {
+ dirEntry.getDirectory('images', { create: true }, function (subDirEntry) {
+
+ createFile(subDirEntry, "fileInNewSubDir.txt");
+
+ }, onErrorGetDir);
+ }, onErrorGetDir);
+}
+```
+
+When creating subfolders, you need to create each folder separately as shown in the preceding code.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-geolocation/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-geolocation/index.md b/www/docs/en/6.x/reference/cordova-plugin-geolocation/index.md
index f0048ee..de11b0c 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-geolocation/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-geolocation/index.md
@@ -32,12 +32,16 @@ description: Access GPS data.
# cordova-plugin-geolocation
This plugin provides information about the device's location, such as
-latitude and longitude. Common sources of location information include
+latitude and longitude.
+
+Common sources of location information include
Global Positioning System (GPS) and location inferred from network
signals such as IP address, RFID, WiFi and Bluetooth MAC addresses,
and GSM/CDMA cell IDs. There is no guarantee that the API returns the
device's actual location.
+> To get a few ideas, check out the [sample](#sample) at the bottom of this page or go straight to the [reference](#reference) content.
+
This API is based on the
[W3C Geolocation API Specification](http://dev.w3.org/geo/api/spec-source.html),
and only executes on devices that don't already provide an implementation.
@@ -71,7 +75,7 @@ are not available until after the `deviceready` event.
}
```
-
+## <a id="reference"></a>Reference
## Installation
This requires cordova 5.0+ ( current stable 1.0.0 )
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-inappbrowser/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-inappbrowser/index.md b/www/docs/en/6.x/reference/cordova-plugin-inappbrowser/index.md
index c717263..01429d1 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-inappbrowser/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-inappbrowser/index.md
@@ -227,6 +227,79 @@ The object returned from a call to `cordova.InAppBrowser.open`.
- __callback__: the function that executes when the event fires. The function is passed an `InAppBrowserEvent` object as a parameter.
+## Example
+
+```javascript
+
+var inAppBrowserRef = undefined;
+
+function showHelp(url) {
+
+ var target = "_blank";
+
+ var options = "location=yes,hidden=yes";
+
+ inAppBrowserRef = cordova.InAppBrowser.open(url, target, options);
+
+ with (inAppBrowserRef) {
+
+ addEventListener('loadstart', loadStartCallBack);
+
+ addEventListener('loadstop', loadStopCallBack);
+
+ addEventListener('loaderror', loadErrorCallBack);
+ }
+
+}
+
+function loadStartCallBack() {
+
+ $('#status-message').text("loading please wait ...");
+
+}
+
+function loadStopCallBack() {
+
+ if (inAppBrowserRef != undefined) {
+
+ inAppBrowserRef.insertCSS({ code: "body{font-size: 25px;" });
+
+ $('#status-message').text("");
+
+ inAppBrowserRef.show();
+ }
+
+}
+
+function loadErrorCallBack(params) {
+
+ $('#status-message').text("");
+
+ var scriptErrorMesssage =
+ "alert('Sorry we cannot open that page. Message from the server is : "
+ + params.message + "');"
+
+ inAppBrowserRef.executeScript({ code: scriptErrorMesssage }, executeScriptCallBack);
+
+ inAppBrowserRef.close();
+
+ inAppBrowserRef = undefined;
+
+}
+
+function executeScriptCallBack(params) {
+
+ if (params[0] == null) {
+
+ $('#status-message').text(
+ "Sorry we couldn't open that page. Message from the server is : '"
+ + params.message + "'");
+ }
+
+}
+
+```
+
### InAppBrowserEvent Properties
- __type__: the eventname, either `loadstart`, `loadstop`, `loaderror`, or `exit`. _(String)_
@@ -404,3 +477,161 @@ Due to [MSDN docs](https://msdn.microsoft.com/en-us/library/windows.ui.xaml.cont
ref.addEventListener('loadstop', function() {
ref.insertCSS({file: "mystyles.css"});
});
+__
+
+## <a id="sample"></a>Sample: Show help pages with an InAppBrowser
+
+You can use this plugin to show helpful documentation pages within your app. Users can view online help documents and then close them without leaving the app.
+
+Here's a few snippets that show how you do this.
+
+* [Give users a way to ask for help](#give).
+* [Load a help page](#load).
+* [Let users know that you're getting their page ready](#let).
+* [Show the help page](#show).
+* [Handle page errors](#handle).
+
+### <a id="give"></a>Give users a way to ask for help
+
+There's lots of ways to do this in your app. A drop down list is a simple way to do that.
+
+```html
+
+<select id="help-select">
+ <option value="default">Need help?</option>
+ <option value="article">Show me a helpful article</option>
+ <option value="video">Show me a helpful video</option>
+ <option value="search">Search for other topics</option>
+</select>
+
+```
+
+Gather the users choice in the ``onDeviceReady`` function of the page and then send an appropriate URL to a helper function in some shared library file. Our helper function is named ``showHelp()`` and we'll write that function next.
+
+```javascript
+
+$('#help-select').on('change', function (e) {
+
+ var url;
+
+ switch (this.value) {
+
+ case "article":
+ url = "https://cordova.apache.org/docs/en/latest/"
+ + "reference/cordova-plugin-inappbrowser/index.html";
+ break;
+
+ case "video":
+ url = "https://youtu.be/F-GlVrTaeH0";
+ break;
+
+ case "search":
+ url = "https://www.google.com/#q=inAppBrowser+plugin";
+ break;
+ }
+
+ showHelp(url);
+
+});
+
+```
+
+### <a id="load"></a>Load a help page
+
+We'll use the ``open`` function to load the help page. We're setting the ``hidden`` property to ``yes`` so that we can show the browser only after the page content has loaded. That way, users don't see a blank browser while they wait for content to appear. When the ``loadstop`` event is raised, we'll know when the content has loaded. We'll handle that event shortly.
+
+```javascript
+
+function showHelp(url) {
+
+ var target = "_blank";
+
+ var options = "location=yes,hidden=yes";
+
+ inAppBrowserRef = cordova.InAppBrowser.open(url, target, options);
+
+ with (inAppBrowserRef) {
+
+ addEventListener('loadstart', loadStartCallBack);
+
+ addEventListener('loadstop', loadStopCallBack);
+
+ addEventListener('loaderror', loadErrorCallBack);
+ }
+
+}
+
+```
+
+### <a id="let"></a>Let users know that you're getting their page ready
+
+Because the browser doesn't immediately appear, we can use the ``loadstart`` event to show a status message, progress bar, or other indicator. This assures users that content is on the way.
+
+```javascript
+
+function loadStartCallBack() {
+
+ $('#status-message').text("loading please wait ...");
+
+}
+
+```
+
+### <a id="show"></a>Show the help page
+
+When the ``loadstopcallback`` event is raised, we know that the content has loaded and we can make the browser visible. This sort of trick can create the impression of better performance. The truth is that whether you show the browser before content loads or not, the load times are exactly the same.
+
+```javascript
+
+function loadStopCallBack() {
+
+ if (inAppBrowserRef != undefined) {
+
+ inAppBrowserRef.insertCSS({ code: "body{font-size: 25px;" });
+
+ $('#status-message').text("");
+
+ inAppBrowserRef.show();
+ }
+
+}
+
+```
+You might have noticed the call to the ``insertCSS`` function. This serves no particular purpose in our scenario. But it gives you an idea of why you might use it. In this case, we're just making sure that the font size of your pages have a certain size. You can use this function to insert any CSS style elements. You can even point to a CSS file in your project.
+
+### <a id="handle"></a>Handle page errors
+
+Sometimes a page no longer exists, a script error occurs, or a user lacks permission to view the resource. How or if you handle that situation is completely up to you and your design. You can let the browser show that message or you can present it in another way.
+
+We'll try to show that error in a message box. We can do that by injecting a script that calls the ``alert`` function. That said, this won't work in browsers on Windows devices so we'll have to look at the parameter of the ``executeScript`` callback function to see if our attempt worked. If it didn't work out for us, we'll just show the error message in a ``<div>`` on the page.
+
+```javascript
+
+function loadErrorCallBack(params) {
+
+ $('#status-message').text("");
+
+ var scriptErrorMesssage =
+ "alert('Sorry we cannot open that page. Message from the server is : "
+ + params.message + "');"
+
+ inAppBrowserRef.executeScript({ code: scriptErrorMesssage }, executeScriptCallBack);
+
+ inAppBrowserRef.close();
+
+ inAppBrowserRef = undefined;
+
+}
+
+function executeScriptCallBack(params) {
+
+ if (params[0] == null) {
+
+ $('#status-message').text(
+ "Sorry we couldn't open that page. Message from the server is : '"
+ + params.message + "'");
+ }
+
+}
+
+```
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-media-capture/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-media-capture/index.md b/www/docs/en/6.x/reference/cordova-plugin-media-capture/index.md
index b0f3a20..1dbf17d 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-media-capture/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-media-capture/index.md
@@ -643,3 +643,41 @@ Supports the following `MediaFileData` properties:
- __width__: Supported: image and video files only.
- __duration__: Supported: audio and video files only.
+
+## Android Lifecycle Quirks
+
+When capturing audio, video, or images on the Android platform, there is a chance that the
+application will get destroyed after the Cordova Webview is pushed to the background by
+the native capture application. See the [Android Lifecycle Guide][android-lifecycle] for
+a full description of the issue. In this case, the success and failure callbacks passed
+to the capture method will not be fired and instead the results of the call will be
+delivered via a document event that fires after the Cordova [resume event][resume-event].
+
+In your app, you should subscribe to the two possible events like so:
+
+```javascript
+function onDeviceReady() {
+ // pendingcaptureresult is fired if the capture call is successful
+ document.addEventListener('pendingcaptureresult', function(mediaFiles) {
+ // Do something with result
+ });
+
+ // pendingcaptureerror is fired if the capture call is unsuccessful
+ document.addEventListener('pendingcaptureerror', function(error) {
+ // Handle error case
+ });
+}
+
+// Only subscribe to events after deviceready fires
+document.addEventListener('deviceready', onDeviceReady);
+```
+
+It is up you to track what part of your code these results are coming from. Be sure to
+save and restore your app's state as part of the [pause][pause-event] and
+[resume][resume-event] events as appropriate. Please note that these events will only
+fire on the Android platform and only when the Webview was destroyed during a capture
+operation.
+
+[android-lifecycle]: http://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html#lifecycle-guide
+[pause-event]: http://cordova.apache.org/docs/en/latest/cordova/events/events.html#pause
+[resume-event]: http://cordova.apache.org/docs/en/latest/cordova/events/events.html#resume
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-media/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-media/index.md b/www/docs/en/6.x/reference/cordova-plugin-media/index.md
index 69b37c4..f12da05 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-media/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-media/index.md
@@ -112,8 +112,12 @@ The following constants are reported as the only parameter to the
- `media.pause`: Pause playback of an audio file.
+- `media.pauseRecord`: Pause recording of an audio file.
+
- `media.release`: Releases the underlying operating system's audio resources.
+- `media.resumeRecord`: Resume recording of an audio file.
+
- `media.seekTo`: Moves the position within the audio file.
- `media.setVolume`: Set the volume for audio playback.
@@ -267,6 +271,44 @@ Pauses playing an audio file.
}
+## media.pauseRecord
+
+Pauses recording an audio file.
+
+ media.pauseRecord();
+
+
+### Supported Platforms
+
+- iOS
+
+
+### Quick Example
+
+ // Record audio
+ //
+ function recordAudio() {
+ var src = "myrecording.mp3";
+ var mediaRec = new Media(src,
+ // success callback
+ function() {
+ console.log("recordAudio():Audio Success");
+ },
+
+ // error callback
+ function(err) {
+ console.log("recordAudio():Audio Error: "+ err.code);
+ });
+
+ // Record audio
+ mediaRec.startRecord();
+
+ // Pause Recording after 5 seconds
+ setTimeout(function() {
+ my_media.pauseRecord();
+ }, 5000);
+ }
+
## media.play
Starts or resumes playing an audio file.
@@ -339,6 +381,50 @@ function for any `Media` resource that is no longer needed.
my_media.release();
+## media.resumeRecord
+
+Resume recording an audio file.
+
+ media.resumeRecord();
+
+
+### Supported Platforms
+
+- iOS
+
+
+### Quick Example
+
+ // Record audio
+ //
+ function recordAudio() {
+ var src = "myrecording.mp3";
+ var mediaRec = new Media(src,
+ // success callback
+ function() {
+ console.log("recordAudio():Audio Success");
+ },
+
+ // error callback
+ function(err) {
+ console.log("recordAudio():Audio Error: "+ err.code);
+ });
+
+ // Record audio
+ mediaRec.startRecord();
+
+ // Pause Recording after 5 seconds
+ setTimeout(function() {
+ my_media.pauseRecord();
+ }, 5000);
+
+ // Resume Recording after 10 seconds
+ setTimeout(function() {
+ my_media.resumeRecord();
+ }, 10000);
+ }
+
+
## media.seekTo
Sets the current position within an audio file.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-network-information/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-network-information/index.md b/www/docs/en/6.x/reference/cordova-plugin-network-information/index.md
index 725d8a1..42067f7 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-network-information/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-network-information/index.md
@@ -37,8 +37,12 @@ This plugin provides an implementation of an old version of the
It provides information about the device's cellular and
wifi connection, and whether the device has an internet connection.
+> To get a few ideas how to use the plugin, check out the [sample](#sample) at the bottom of this page or go straight to the [reference](#reference) content.
+
Report issues with this plugin on the [Apache Cordova issue tracker][Apache Cordova issue tracker].
+##<a name="reference"></a>Reference
+
## Installation
cordova plugin add cordova-plugin-network-information
@@ -220,4 +224,120 @@ When running in the Emulator, the `connection.status` is always unknown, so this
The Emulator reports the connection type as `Cellular`, which does not change, so events does _not_ fire.
+## Sample: Upload a File Depending on your Network State <a name="sample"></a>
+
+The code examples in this section show examples of changing app behavior using the online and offline events and your network connection status.
+
+To start with, create a new FileEntry object (data.txt) to use for sample data. Call this function from the `deviceready` handler.
+
+>*Note* This code example requires the File plugin.
+
+```js
+
+var dataFileEntry;
+
+function createSomeData() {
+
+ window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+ console.log('file system open: ' + fs.name);
+ // Creates a new file or returns an existing file.
+ fs.root.getFile("data.txt", { create: true, exclusive: false }, function (fileEntry) {
+
+ dataFileEntry = fileEntry;
+
+ }, onErrorCreateFile);
+
+ }, onErrorLoadFs);
+}
+```
+
+Next, add listeners for the online and offline events in the `deviceready` handler.
+
+```js
+document.addEventListener("offline", onOffline, false);
+document.addEventListener("online", onOnline, false);
+```
+
+The app's `onOnline` function handles the online event. In the event handler, check the current network state. In this app, treat any connection type as good except Connection.NONE. If you have a connection, you try to upload a file.
+
+```js
+function onOnline() {
+ // Handle the online event
+ var networkState = navigator.connection.type;
+
+ if (networkState !== Connection.NONE) {
+ if (dataFileEntry) {
+ tryToUploadFile();
+ }
+ }
+ display('Connection type: ' + networkState);
+}
+```
+
+When the online event fires in the preceding code, call the app's `tryToUploadFile` function.
+
+If the FileTransfer object's upload function fails, call the app's `offlineWrite` function to save the current data somewhere.
+
+>*Note* This example requires the FileTransfer plugin.
+
+```js
+function tryToUploadFile() {
+ // !! Assumes variable fileURL contains a valid URL to a text file on the device,
+ var fileURL = getDataFileEntry().toURL();
+
+ var success = function (r) {
+ console.log("Response = " + r.response);
+ display("Uploaded. Response: " + r.response);
+ }
+
+ var fail = function (error) {
+ console.log("An error has occurred: Code = " + error.code);
+ offlineWrite("Failed to upload: some offline data");
+ }
+
+ var options = new FileUploadOptions();
+ options.fileKey = "file";
+ options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
+ options.mimeType = "text/plain";
+
+ var ft = new FileTransfer();
+ // Make sure you add the domain of your server URL to the
+ // Content-Security-Policy <meta> element in index.html.
+ ft.upload(fileURL, encodeURI(SERVER), success, fail, options);
+};
+```
+
+Here is the code for the `offlineWrite` function.
+
+>*Note* This code examples requires the File plugin.
+
+```js
+function offlineWrite(offlineData) {
+ // Create a FileWriter object for our FileEntry.
+ dataFileEntry.createWriter(function (fileWriter) {
+
+ fileWriter.onwriteend = function () {
+ console.log("Successful file write...");
+ display(offlineData);
+ };
+
+ fileWriter.onerror = function (e) {
+ console.log("Failed file write: " + e.toString());
+ };
+
+ fileWriter.write(offlineData);
+ });
+}
+```
+
+If the offline event occurs, just do something like notify the user (for this example, just log it).
+
+```js
+function onOffline() {
+ // Handle the offline event
+ console.log("lost connection");
+}
+```
+
[Apache Cordova issue tracker]: https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Network%20Information%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-splashscreen/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-splashscreen/index.md b/www/docs/en/6.x/reference/cordova-plugin-splashscreen/index.md
index 9750b0a..890551e 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-splashscreen/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-splashscreen/index.md
@@ -50,10 +50,11 @@ Report issues with this plugin on the [Apache Cordova issue tracker][Apache Cord
- BlackBerry 10
- iOS
- Windows Phone 7 and 8
-- Windows 8
-- Windows
+- Windows (`cordova-windows` version >= 4.4.0 is required)
- Browser
+__Note__: Extended splashscreen does not require the plugin on Windows (as opposed to Android and iOS) in case you don't use the plugin API, i.e. programmatic hide/show.
+
## Example Configuration
In the top-level `config.xml` file (not the one in `platforms`), add configuration elements like those specified here.
@@ -124,18 +125,27 @@ projectRoot
#### config.xml
-- __AutoHideSplashScreen__ (boolean, default to `true`). Indicates whether to hide splash screen automatically or not. Splash screen hidden after amount of time specified in the `SplashScreenDelay` preference.
+- `AutoHideSplashScreen` (boolean, default to `true`). Indicates whether to hide splash screen automatically or not. Splash screen hidden after amount of time specified in the `SplashScreenDelay` preference.
```xml
<preference name="AutoHideSplashScreen" value="true" />
```
-- __SplashScreenDelay__ (number, default to 3000). Amount of time in milliseconds to wait before automatically hide splash screen.
+- `SplashScreenDelay` (number, default to 3000). Amount of time in milliseconds to wait before automatically hide splash screen.
```xml
<preference name="SplashScreenDelay" value="3000" />
```
+Note also that this value used to be seconds, and not milliseconds, so values less than 30 will still be treated as seconds. ( Consider this a deprecated patch that will disapear in some future version. )
+
+To disable the splashscreen add the following preference to `config.xml`:
+```xml
+<preference name="SplashScreenDelay" value="0"/>
+```
+
+**iOS Quirk**: to disable the splashscreen on `ios` platform you should also add `<preference name="FadeSplashScreenDuration" value="0"/>` to `config.xml`.
+
- `FadeSplashScreen` (boolean, defaults to `true`): Set to `false` to
prevent the splash screen from fading in and out when its display
state changes.
@@ -144,15 +154,13 @@ projectRoot
<preference name="FadeSplashScreen" value="false"/>
```
-- `FadeSplashScreenDuration` (float, defaults to `3000`): Specifies the
+- `FadeSplashScreenDuration` (float, defaults to `500`): Specifies the
number of milliseconds for the splash screen fade effect to execute.
```xml
- <preference name="FadeSplashScreenDuration" value="3000"/>
+ <preference name="FadeSplashScreenDuration" value="750"/>
```
-Note also that this value used to be seconds, and not milliseconds, so values less than 30 will still be treated as seconds. ( Consider this a deprecated patch that will disapear in some future version. )
-
_Note_: `FadeSplashScreenDuration` is included into `SplashScreenDelay`, for example if you have `<preference name="SplashScreenDelay" value="3000" />` and `<preference name="FadeSplashScreenDuration" value="1000"/>` defined in `config.xml`:
- 00:00 - splashscreen is shown
@@ -179,16 +187,13 @@ window.setTimeout(function () {
### Android Quirks
-In your `config.xml`, you need to add the following preferences:
+In your `config.xml`, you can add the following preferences:
```xml
-<preference name="SplashScreenDelay" value="3000" />
<preference name="SplashMaintainAspectRatio" value="true|false" />
<preference name="SplashShowOnlyFirstTime" value="true|false" />
```
-The first parameter represents how long the splashscreen will appear in milliseconds. It defaults to 3000 ms.
-
"SplashMaintainAspectRatio" preference is optional. If set to true, splash screen drawable is not stretched to fit screen, but instead simply "covers" the screen, like CSS "background-size:cover". This is very useful when splash screen images cannot be distorted in any way, for example when they contain scenery or text. This setting works best with images that have large margins (safe areas) that can be safely cropped on screens with different aspect ratios.
The plugin reloads splash drawable whenever orientation changes, so you can specify different drawables for portrait and landscape orientations.
@@ -220,14 +225,17 @@ __Note__: `SplashScreen` value should be absolute in order to work in a sub-page
- `SplashScreenSpinnerColor` (string, defaults to system accent color): hash, rgb notation or CSS color name.
- <preference name="SplashScreenSpinnerColor" value="#242424"/>
- <preference name="SplashScreenSpinnerColor" value="DarkRed"/>
- <preference name="SplashScreenSpinnerColor" value="rgb(50,128,128)"/>
+```xml
+<preference name="SplashScreenSpinnerColor" value="#242424"/>
+<preference name="SplashScreenSpinnerColor" value="DarkRed"/>
+<preference name="SplashScreenSpinnerColor" value="rgb(50,128,128)"/>
+```
- `SplashScreenBackgroundColor` (string, defaults to #464646): hex notation.
- <preference name="SplashScreenBackgroundColor" value="0xFFFFFFFF"/>
-
+```xml
+<preference name="SplashScreenBackgroundColor" value="0xFFFFFFFF"/>
+```
## Methods
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org
[2/3] docs commit: Snapshotting dev to 6.x
Posted by ra...@apache.org.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/plugin_ref/spec.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/plugin_ref/spec.md b/www/docs/en/6.x/plugin_ref/spec.md
index 2fc4b02..c70d48f 100644
--- a/www/docs/en/6.x/plugin_ref/spec.md
+++ b/www/docs/en/6.x/plugin_ref/spec.md
@@ -30,7 +30,7 @@ Plugin.xml file defines the structure and settings required for your plugin. It
The `plugin` element is the plugin manifest's top-level element.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
xmlns(string) | *Required* <br/> 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 in the case of Android, those namespaces should also be included in the <plugin> element.
id(string) | *Required* <br/> A npm-style identifier for the plugin.
@@ -53,7 +53,7 @@ The child elements of the `<engines>` element specify versions of Apache Cordova
>is in a plugin's `package.json`. See [specifying Cordova dependencies](../guide/hybrid/plugins/index.html#specifying-cordova-dependencies)
>for more information
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
name(string) | *Required* <br/> Name of the engine. Here are the default engines that are supported : <ul><li> `cordova` </li> <li> `cordova-plugman` </li> <li> `cordova-android` </li> <li> `cordova-ios` </li> <li> `cordova-blackberry10` </li> <li> `cordova-wp8` </li> <li> `cordova-windows` </li> <li> `cordova-osx` </li> <li> `windows-os` </li> <li> `android-sdk` (returns the highest Android api level installed) </li> <li> `windows-sdk` (returns the native windows SDK version) </li> <li> `apple-xcode` (returns the xcode version) </li> <li> `apple-ios` (returns the highest iOS version installed) </li> <li> `apple-osx` (returns the OSX version) </li> <li> `blackberry-ndk` (returns the native blackberry SDK version) </li> You can also specify a custom framework apart from the default ones.
version(string) | *Required* <br/> The version that your framework must have in order to install. Semver syntax is supported.
@@ -70,16 +70,16 @@ Examples:
Engine elements may also specify fuzzy matches using '>', '>=' etc. to avoid repetition, and to reduce maintenance when the underlying platform is updated.
```xml
<engines>
- <engine name="cordova-android" version=">=1.8.0" />
+ <engine name="cordova-android" version=">=1.8.0" />
</engines>
```
The `<engine>` tags also has default support for all of the main platforms Cordova exists on. Specifying the cordova engine tag means that all versions of Cordova on any platform must satisfy the engine version attribute. You may also list specific platforms and their versions in order to override the catch-all cordova engine:
```xml
<engines>
- <engine name="cordova" version=">=1.7.0" />
- <engine name="cordova-android" version=">=1.8.0" />
- <engine name="cordova-ios" version=">=1.7.1" />
+ <engine name="cordova" version=">=1.7.0" />
+ <engine name="cordova-android" version=">=1.8.0" />
+ <engine name="cordova-ios" version=">=1.7.1" />
</engines>
```
@@ -87,8 +87,8 @@ Custom frameworks example:
```xml
<engines>
<engine name="my_custom_framework" version="1.0.0" platform="android" scriptSrc="path_to_my_custom_framework_version"/>
- <engine name="another_framework" version=">0.2.0" platform="ios|android" scriptSrc="path_to_another_framework_version"/>
- <engine name="even_more_framework" version=">=2.2.0" platform="*" scriptSrc="path_to_even_more_framework_version"/>
+ <engine name="another_framework" version=">0.2.0" platform="ios|android" scriptSrc="path_to_another_framework_version"/>
+ <engine name="even_more_framework" version=">=2.2.0" platform="*" scriptSrc="path_to_even_more_framework_version"/>
</engines>
```
@@ -141,7 +141,7 @@ Example:
This element is used to list the files or directories to be copied into a Cordova app's `www` directory. Any `<asset>` elements that are nested within `<platform>` elements specify platform-specific web assets.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
src(string) | *Required* <br/> 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, the CLI stops and reverses the installation process, issues a notification about the conflict, and exits with a non-zero code.
target(string) | *Required* <br/> Where the file or directory should be located in the Cordova app, relative to the `www` directory. If a file already exists at the target location, the CLI stops and reverses the installation process, issues a notification about the conflict, and exits with a non-zero code.
@@ -163,7 +163,7 @@ Assets can be targeted to subdirectories as well. This will create the `js/exper
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. 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. Nesting `<js-module>` elements within `<platform>` declares platform-specific JavaScript module bindings.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
src(string) | References a file in the plugin directory relative to the `plugin.xml` file. If src does not resolve to an existing file, the CLI stops and reverses the installation, issues a notification of the problem, and exits with a non-zero code.
name(string) | 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.
@@ -182,7 +182,7 @@ Also for this example, with a plugin id of `chrome-socket`, the module name will
Allowed within `<js-module>` element. Used to specify the namespace under `window` object where module.exports gets inserted. You can have as many `<clobbers>` as you
like. Any object not available on `window` is created.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
target(string) | The namespace where module.exports gets inserted to.
@@ -198,7 +198,7 @@ Here module.exports gets inserted into the `window` object as `window.chrome.soc
Allowed within `<js-module>` element. Used to specify the namespace under `window` object where module.exports gets merged with any existing 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.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
target(string) | The namespace which module.exports gets merged to.
@@ -225,7 +225,7 @@ Example:
The `<dependency>` tag allows you to specify other plugins on which the current plugin depends. The plugins are referenced by their unique npm ids or by github url.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
id(string) | Provides the ID of the plugin.
url(string) | A URL for the plugin. This should reference a git repository, which the CLI attempts to clone.
@@ -243,7 +243,7 @@ Examples:
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.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
name(string) | *Required* <br/> Allowed values: ios, android, blackberry10, amazon-fireos, wp8, windows <br/> Identifies a platform as supported, associating the element's children with that platform.
@@ -258,12 +258,12 @@ Example:
Identifies executable source code that should be installed into a project.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
src(string) | *Required* <br/> Location of the file relative to `plugin.xml`. If the src file can't be found, the CLI stops and reverses the installation, issues a notification about the problem, and exits with a non-zero code.
target-dir(string) | 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.
-framework(boolean) | *Default: false* <br/> ==iOS== <br/> If set to true, also adds the specified file as a framework to the project.
-compiler-flags(string) | ==iOS== <br/> If set, assigns the specified compiler flags for the particular source file.
+framework(boolean) <br/> ==iOS== | *Default: false* <br/> If set to true, also adds the specified file as a framework to the project.
+compiler-flags(string) <br/> ==iOS== | If set, assigns the specified compiler flags for the particular source file.
Examples:
```xml
@@ -279,7 +279,7 @@ Examples:
This is like `<source-file>` element but specifically for platforms such as iOS and Android that distinguish between source files, headers, and resources. This is not supported by Windows.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
src(string) | *Required* <br/> Location of the file relative to `plugin.xml`. If the src file can't be found, the CLI stops and reverses the installation, issues a notification about the problem, and exits with a non-zero code.
target(string) | Path to where the file will be copied in your directory.
@@ -295,13 +295,13 @@ For iOS:
This is like `<source-file>` element, but specifically for platforms such as iOS and Android that distinguish between source files, headers, and resources.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
src(string) | *Required* <br/> Location of the file relative to `plugin.xml`. If the src file can't be found, the CLI stops and reverses the installation, issues a notification about the problem, and exits with a non-zero code.
target(string) | Path to where the file will be copied in your directory.
-arch(string) | ==windows== <br/> Allowed values: `x86`, `x64` or `ARM`. <br/> Indicates that the file should only be included when building for the specified architecture.
-device-target | ==windows== <br/> Allowed values: `win` (or `windows`), `phone` or `all`. <br/> Indicates that the file should only be included when building for the specified target device type.
-versions | ==windows== <br/> Indicates that the file should only be included when building for versions that match the specified version string. Value can be any valid node semantic version range string.
+arch(string) <br/> ==windows== | Allowed values: `x86`, `x64` or `ARM`. <br/> Indicates that the file should only be included when building for the specified architecture.
+device-target <br/> ==windows== | Allowed values: `win` (or `windows`), `phone` or `all`. <br/> Indicates that the file should only be included when building for the specified target device type.
+versions <br/> ==windows== | Indicates that the file should only be included when building for versions that match the specified version string. Value can be any valid node semantic version range string.
Examples:
@@ -321,13 +321,13 @@ Identifies an XML-based configuration file to be modified, where in that documen
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.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
target(string) | The file to be modified, and the path relative to the root of the Cordova project. If the specified file does not exist, the tool ignores the configuration change and continues installation. <br/> The target can include wildcard (`*`) elements. In this case, the CLI recursively searches through the project directory structure and uses the first match. <br/> 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`.
parent(string) | 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`. 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. <br/> For `plist` files, the `parent` determines under what parent key the specified XML should be inserted.
after(string) | A prioritized list of accepted siblings after which to add the XML snippet. Useful for specifying changes in files which require strict ordering of XML elements like [this](http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff769509%28v=vs.105%29.aspx#BKMK_EXTENSIONSelement).
-device-target(string) | ==windows== <br/> Allowed values: `win`, `phone`, `all`. <br/> Applicable when affecting the meta-name `package.appxmanifest`, this attribute indicates that the file should only be modified when building for the specified target device type.
-versions(string) | ==windows== <br/> Applicable when affecting the meta-name `package.appxmanifest`, this attribute indicates that app manifests for specific Windows versions should only be altered for versions that match the specified version string. Value can be any valid node semantic version range string.
+device-target(string) <br/> ==windows== | Allowed values: `win`, `phone`, `all`. <br/> Applicable when affecting the meta-name `package.appxmanifest`, this attribute indicates that the file should only be modified when building for the specified target device type.
+versions(string) <br/> ==windows== | Applicable when affecting the meta-name `package.appxmanifest`, this attribute indicates that app manifests for specific Windows versions should only be altered for versions that match the specified version string. Value can be any valid node semantic version range string.
Examples:
@@ -355,11 +355,11 @@ For `plist`:
For windows-specific attributes:
```xml
-<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions="<8.1.0">
+<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions="<8.1.0">
<Capability Name="picturesLibrary" />
<DeviceCapability Name="webcam" />
</config-file>
-<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions=">=8.1.0" device-target="phone">
+<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions=">=8.1.0" device-target="phone">
<DeviceCapability Name="webcam" />
</config-file>
```
@@ -378,12 +378,12 @@ Example:
Like source, resource, and header files, but specifically for platforms such as BlackBerry 10 that use user-generated libraries. For the Windows platform, the `<lib-file>` element allows the inclusion of an `<SDKReference>` in the generated Windows project files.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
src(string) | *Required* <br/> The location of the file relative to `plugin.xml`. If `src` can't be found, the CLI stops and reverses the installation, issues a warning about the problem, and exits with a non-zero code. <br/> For Windows, it indicates the name of the SDK to include (which will be used as value of the `Include` attribute of the generated `<SDKReference>` element).
arch(string) | The architecture for which the `.so` file has been built, either `device` or `simulator`. <br/> For Windows, it indicates that the `<SDKReference>` should only be included when building for the specified architecture. Supported values are `x86`, `x64` or `ARM`.
-device-target(string) | ==windows== <br/> Allowed values: `win` (or `windows`), `phone` or `all`. <br/> Indicates that the `<SDKReference>` should only be included when building for the specified target device type.
-versions(string) | ==windows== <br/> Indicates that the `<SDKReference>` should only be included when building for versions that match the specified version string. Value can be any valid node semantic version range string.
+device-target(string) <br/> ==windows== | Allowed values: `win` (or `windows`), `phone` or `all`. <br/> Indicates that the `<SDKReference>` should only be included when building for the specified target device type.
+versions(string) <br/> ==windows== | Indicates that the `<SDKReference>` should only be included when building for versions that match the specified version string. Value can be any valid node semantic version range string.
Examples:
```xml
@@ -394,7 +394,7 @@ Examples:
For Windows:
```xml
<lib-file src="Microsoft.WinJS.2.0, Version=1.0" arch="x86" />
-<lib-file src="Microsoft.WinJS.2.0, Version=1.0" versions=">=8.1" />
+<lib-file src="Microsoft.WinJS.2.0, Version=1.0" versions=">=8.1" />
<lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="phone" />
<lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="win" versions="8.0" arch="x86" />
```
@@ -403,17 +403,17 @@ For Windows:
Identifies a framework (usually part of the OS/platform) on which the plugin depends.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
src(string) | *Required* <br/> The name of the system framework or the relative path to one which is included as part of your plugin files.
custom(boolean) | Indicates whether the framework is included as part of your plugin files.
weak(boolean) | *Default: false* <br/> Indicates whether the framework should be weakly linked.
type(string) | Indicates the type of framework to add.
parent(string) | *Default: .* <br/> Sets the relative path to the directory containing the sub-project to which to add the reference. The default, `.`, implies the application project.
-arch(string) | ==windows== <br/> Allowed values: `x86`, `x64` or `ARM`. <br/> Indicates that the framework should only be included when building for the specified architecture.
-device-target(string) | ==windows== <br/> Allowed values: `win` (or `windows`), `phone` or `all`. <br/> Indicates that the framework should only be included when building for the specified target device type.
-versions(string) | ==windows== <br/> Indicates that the framework should only be included when building for versions that match the specified version string. Value can be any valid node semantic version range string.
-target-dir(string) | ==windows== <br/> Indicates a subdirectory into which the framework should be copied. In practice, this is most important when plugin contains different framework versions for different chip architectures or device targets, but which have the same name. This allows you to specify different subfolders for each framework version so that they don't overlap each other.
+arch(string) <br/> ==windows== | Allowed values: `x86`, `x64` or `ARM`. <br/> Indicates that the framework should only be included when building for the specified architecture.
+device-target(string) <br/> ==windows== | Allowed values: `win` (or `windows`), `phone` or `all`. <br/> Indicates that the framework should only be included when building for the specified target device type.
+versions(string) <br/> ==windows== | Indicates that the framework should only be included when building for versions that match the specified version string. Value can be any valid node semantic version range string.
+target-dir(string) <br/> ==windows== | Indicates a subdirectory into which the framework should be copied. In practice, this is most important when plugin contains different framework versions for different chip architectures or device targets, but which have the same name. This allows you to specify different subfolders for each framework version so that they don't overlap each other.
Examples:
@@ -447,7 +447,7 @@ On Windows, using `custom='true'` and `type='projectReference'` will add a refer
Examples of using these Windows specific attributes:
```xml
<framework src="src/windows/example.dll" arch="x64" />
-<framework src="src/windows/example.dll" versions=">=8.0" />
+<framework src="src/windows/example.dll" versions=">=8.0" />
<framework src="src/windows/example.vcxproj" type="projectReference" target="win" />
<framework src="src/windows/example.vcxproj" type="projectReference" target="all" versions="8.1" arch="x86" />
<framework src="src/windows/example.dll" target-dir="bin/x64" arch="x64" custom="true"/>
@@ -506,13 +506,21 @@ Certain variable names should be reserved, like `$PACKAGE_NAME`. This is the rev
As seen in the previous section, sometimes plugin might require user to specify values for their variables. To make those variable mandatory, the `<platform>` tag needs to contain
a `<preference>` tag.
The CLI 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.
+Preferences can be referenced elsewhere in `plugin.xml` using the syntax `$PREFERENCE_NAME`.
-Attributes(type) | Description
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
-name(string) | *Required* <br/> Name of the variable.
+name(string) | *Required* <br/> Name of the variable. Can only contain capital letters, digits, and underscores.
default(string) | Default value of the variable. If present, its value will be used and no error will be emitted in case user does not enter any value.
Example:
```xml
-<preference name="API_KEY" default="default-value" />
+<preference name="MY_CUSTOM_STRING" default="default-value" />
+
+<!--
+ The preference may be referenced elsewhere in plugin.xml like so:
+-->
+<config-file target="./res/values/strings.xml" parent="/resources">
+ <string name="custom">$MY_CUSTOM_STRING</string>
+</config-file>
```
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-cli/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-cli/index.md b/www/docs/en/6.x/reference/cordova-cli/index.md
index 2c42629..e118d05 100644
--- a/www/docs/en/6.x/reference/cordova-cli/index.md
+++ b/www/docs/en/6.x/reference/cordova-cli/index.md
@@ -43,6 +43,7 @@ These commands are available at all times.
|----------|--------------
| create | Create a project
| help <command> | Get help for a command
+| telemetry | Turn telemetry collection on or off
## Project Command List
@@ -70,6 +71,7 @@ These options apply to all cordova-cli commands.
| -v or --version | Print out the version of your `cordova-cli` install.
| --no-update-notifier | Will disable updates check. Alternatively set `"optOut": true` in `~/.config/configstore/update-notifier-cordova.json` or set `NO_UPDATE_NOTIFIER` environment variable with any value (see details in [update-notifier docs](https://www.npmjs.com/package/update-notifier#user-settings)).
|--nohooks | Suppress executing hooks (taking RegExp hook patterns as parameters)
+| --no-telemetry | Disable telemetry collection for the current command.
## Platform-specific options
@@ -83,8 +85,12 @@ Certain commands have options (`platformOpts`) that are specific to a particular
cd myApp
# Add camera plugin to the project and remember that in config.xml
cordova plugin add cordova-plugin-camera --save
+ # Add camera plugin to the project and remember that in config.xml. Use npm install to fetch.
+ cordova plugin add cordova-plugin-camera --save --fetch
# Add android platform to the project and remember that in config.xml
cordova platform add android --save
+ # Add android platform to the project and remember that in config.xml. Use npm install to fetch.
+ cordova platform add android --save --fetch
# Check to see if your system is configured for building android platform.
cordova requirements android
# Build the android and emit verbose logs.
@@ -123,7 +129,7 @@ cordova create path [id [name [config]]] [options]
### Directory structure
-A Cordova application created with `cordova-cli` will have the following directory structure:
+Cordova CLI works with the following directory structure:
```
myapp/
@@ -207,11 +213,12 @@ Manage cordova platforms - allowing you to add, remove, update, list and check f
```bash
cordova {platform | platforms} [
- add <platform-spec> [...] {--save | link=<path> } |
- {remove | rm} platform [...] |
+ add <platform-spec> [...] {--save | link=<path> | --fetch } |
+ {remove | rm} platform [...] {--save | --fetch}|
{list | ls} |
check |
- save ]
+ save |
+ update ]
```
| Sub-command | Option | Description |
@@ -219,10 +226,13 @@ cordova {platform | platforms} [
| add `<platform-spec>` [...] | | Add specified platforms |
| | --save | Save `<platform-spec>` into `config.xml` after installing them using `<engine>` tag |
| | --link=`<path>` | When `<platform-spec>` is a local path, links the platform library directly instead of making a copy of it (support varies by platform; useful for platform development)
+| | --fetch | Fetches the platform using `npm install` and stores it into the apps `node_modules` directory |
| remove `<platform>` [...] | | Remove specified platforms |
| | --save | Delete specified platforms from `config.xml` after removing them |
+| | --fetch | Removes the platform using `npm uninstall` and removes it from the apps `node_modules` directory |
| update `platform` [...] | | Update specified platforms |
| | --save | Updates the version specified in `config.xml` |
+| | --fetch | Fetches the platform using `npm install` and stores it into the apps `node_modules` directory |
| list | | List all installed and available platforms |
| check | | List platforms which can be updated by `cordova-cli platform update` |
| save | | Save `<platform-spec>` of all platforms added to config.xml |
@@ -265,6 +275,11 @@ There are a number of ways to specify a platform:
cordova platform add android ios --save
+- Add pinned version of the `android` and `ios` platform and save the downloaded version to `config.xml`. Install
+to the project using `npm install` and store it in the apps `node_modules` directory:
+
+ cordova platform add android ios --save --fetch
+
- Add `android` platform with [semver](http://semver.org/) version ^5.0.0 and save it to `config.xml`:
cordova platform add android@^5.0.0 --save
@@ -285,6 +300,11 @@ There are a number of ways to specify a platform:
cordova platform rm android --save
+- Remove `android` platform from the project and from `config.xml`. Run `npm uninstall` to remove it
+from the `node_modules` directory.
+
+ cordova platform rm android --save --fetch
+
- List available and installed platforms with version numbers. This is useful to find version numbers when reporting issues:
cordova platform ls
@@ -303,8 +323,8 @@ Manage project plugins
```bash
cordova {plugin | plugins} [
- add <plugin-spec> [..] {--searchpath=<directory> | --noregistry | --link | --save | --browserify | --force} |
- {remove | rm} {<pluginid> | <name>} --save |
+ add <plugin-spec> [..] {--searchpath=<directory> | --noregistry | --link | --save | --browserify | --force | --fetch} |
+ {remove | rm} {<pluginid> | <name>} --save --fetch |
{list | ls} |
search [<keyword>] |
save |
@@ -314,14 +334,16 @@ cordova {plugin | plugins} [
| Sub-command | Option | Description
|------------------------|-------------|------
| add `<plugin-spec>` [...] | | Add specified plugins
-| |--searchpath `<directory>` | When looking up plugins by ID, look in this directory and each of its subdirectories before hitting the registry. Multiple search paths can be specified. Use ':' as a separator in *nix based systems and ';' for Windows.
+| |--searchpath `<directory>` | When looking up plugins by ID, look in this directory and each of its subdirectories before hitting the registry. Multiple search paths can be specified. Use ':' as a separator in `*nix` based systems and ';' for Windows.
| |--noregistry | Don't search the registry for plugins.
| |--link | When installing from a local path, creates a symbolic link instead of copying files. The extent to which files are linked varies by platform. Useful for plugin development.
| |--save | Save the `<plugin-spec>` as part of the `plugin` element into `config.xml`.
| |--browserify | Compile plugin JS at build time using browserify instead of runtime.
| |--force | _Introduced in version 6.1._ Forces copying source files from the plugin even if the same file already exists in the target directory.
+| |--fetch | Fetches the plugin using `npm install` and stores it into the apps `node_modules` directory |
| remove `<pluginid>|<name>` [...]| | Remove plugins with the given IDs/name.
| |--save | Remove the specified plugin from config.xml
+| |--fetch | Removes the plugin using `npm uninstall` and removes it from the apps `node_modules` directory |
|list | | List currently installed plugins
|search `[<keyword>]` [...] | | Search http://plugins.cordova.io for plugins matching the keywords
|save | | Save `<plugin-spec>` of all plugins currently added to the project
@@ -330,16 +352,17 @@ cordova {plugin | plugins} [
There are a number of ways to specify a plugin:
- <plugin-spec> : pluginID[@version]|directory|url[#commit-ish][:subdir]
+ <plugin-spec> : [@scope/]pluginID[@version]|directory|url[#commit-ish][:subdir]
| Value | Description
|-------------|--------------------
+| scope | Scope of plugin published as a [scoped npm package]
| plugin | Plugin id (id of plugin in npm registry or in --searchPath)
| version | Major.minor.patch version specifier using semver
| directory | Directory containing plugin.xml
| url | Url to a git repository containing a plugin.xml
| commit-ish | Commit/tag/branch reference. If none is specified, 'master' is used
-| subdir | Sub-directory to find plugin.xml for the specified plugin.
+| subdir | Sub-directory to find plugin.xml for the specified plugin. (Doesn't work with `--fetch` option)
### Algorithm for resolving plugins
@@ -361,6 +384,10 @@ based on the following criteria (listed in order of precedence):
cordova plugin add cordova-plugin-camera@^2.0.0 --save
+- Add `cordova-plugin-camera` with [semver](http://semver.org/) version ^2.0.0 and `npm install` it. It will be stored in the `node_modules` directory:
+
+ cordova plugin add cordova-plugin-camera@^2.0.0 --fetch
+
- Clone the specified git repo, checkout to tag `2.1.0`, look for plugin.xml in the `plugin` directory, and add it to the project. Save the `plugin-spec` to `config.xml`:
cordova plugin add https://github.com/apache/cordova-plugin-camera.git#2.1.0:plugin --save
@@ -377,6 +404,10 @@ based on the following criteria (listed in order of precedence):
cordova plugin rm camera --save
+- Remove the plugin from the project and `npm uninstall` it. Removes it from the `node_modules` directory:
+
+ cordova plugin rm camera --fetch
+
- List all plugins installed in the project:
cordova plugin ls
@@ -392,7 +423,7 @@ copies plugin files for specified platforms so that the project is ready to buil
```
cordova prepare [<platform> [..]]
- [--browserify]
+ [--browserify | --fetch]
```
###Options
@@ -401,6 +432,8 @@ cordova prepare [<platform> [..]]
|------------|------------------
| `<platform> [..]` | Platform name(s) to prepare. If not specified, all platforms are built.
|--browserify | Compile plugin JS at build time using browserify instead of runtime.
+|--fetch | When restoring plugins or platforms, fetch will `npm install` the missing modules.
+
## cordova compile command
@@ -583,6 +616,38 @@ Run a local web server for www/ assets using specified `port` or default of 8000
cordova serve [port]
```
+## cordova telemetry command
+
+### Synopsis
+
+Turns telemetry collection on or off.
+
+### Syntax
+
+```
+cordova telemetry [STATE]
+```
+
+| Option | Description
+|-------------|------------------
+| on | Turn telemetry collection on.
+| off | Turn telemetry collection off.
+
+### Details
+ A timed prompt asking the user to opt-in or out is displayed the first time cordova is run.
+ It lasts for 30 seconds, after which the user is automatically opted-out if he doesn't provide any answer.
+ In CI environments, the `CI` environment variable can be set, which will prevent the prompt from showing up.
+ Telemetry collection can also be turned off on a single command by using the `--no-telemetry` flag.
+
+### Examples
+```
+cordova telemetry on
+cordova telemetry off
+cordova build --no-telemetry
+```
+
+For details, see our privacy notice: https://cordova.apache.org/privacy
+
## cordova help command
### Synopsis
@@ -600,3 +665,4 @@ cordova -h [command]
[Hooks guide]: http://cordova.apache.org/docs/en/latest/guide_appdev_hooks_index.md.html
[config.xml ref]: http://cordova.apache.org/docs/en/latest/config_ref/index.html
[Cordova dependencies]: http://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html#specifying-project-requirements
+[scoped npm package]: https://docs.npmjs.com/misc/scope
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-camera/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-camera/index.md b/www/docs/en/6.x/reference/cordova-plugin-camera/index.md
index 3ecf438..a9181c1 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-camera/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-camera/index.md
@@ -104,8 +104,10 @@ Documentation consists of template and API docs produced from the plugin JS code
---
<a name="module_camera"></a>
+
## camera
<a name="module_camera.getPicture"></a>
+
### camera.getPicture(successCallback, errorCallback, options)
Takes a photo using the camera, or retrieves a photo from the device's
image gallery. The image is passed to the success callback as a
@@ -173,6 +175,7 @@ More examples [here](#camera-getPicture-examples). Quirks [here](#camera-getPict
navigator.camera.getPicture(cameraSuccess, cameraError, cameraOptions);
```
<a name="module_camera.cleanup"></a>
+
### camera.cleanup()
Removes intermediate image files that are kept in temporary storage
after calling [`camera.getPicture`](#module_camera.getPicture). Applies only when the value of
@@ -197,6 +200,7 @@ function onFail(message) {
}
```
<a name="module_camera.onError"></a>
+
### camera.onError : <code>function</code>
Callback function that provides an error message.
@@ -207,6 +211,7 @@ Callback function that provides an error message.
| message | <code>string</code> | The message is provided by the device's native code. |
<a name="module_camera.onSuccess"></a>
+
### camera.onSuccess : <code>function</code>
Callback function that provides the image data.
@@ -226,6 +231,7 @@ function cameraCallback(imageData) {
}
```
<a name="module_camera.CameraOptions"></a>
+
### camera.CameraOptions : <code>Object</code>
Optional parameters to customize the camera settings.
* [Quirks](#CameraOptions-quirks)
@@ -251,8 +257,10 @@ Optional parameters to customize the camera settings.
---
<a name="module_Camera"></a>
+
## Camera
<a name="module_Camera.DestinationType"></a>
+
### Camera.DestinationType : <code>enum</code>
**Kind**: static enum property of <code>[Camera](#module_Camera)</code>
**Properties**
@@ -264,6 +272,7 @@ Optional parameters to customize the camera settings.
| NATIVE_URI | <code>number</code> | <code>2</code> | Return native uri (eg. asset-library://... for iOS) |
<a name="module_Camera.EncodingType"></a>
+
### Camera.EncodingType : <code>enum</code>
**Kind**: static enum property of <code>[Camera](#module_Camera)</code>
**Properties**
@@ -274,6 +283,7 @@ Optional parameters to customize the camera settings.
| PNG | <code>number</code> | <code>1</code> | Return PNG encoded image |
<a name="module_Camera.MediaType"></a>
+
### Camera.MediaType : <code>enum</code>
**Kind**: static enum property of <code>[Camera](#module_Camera)</code>
**Properties**
@@ -285,6 +295,7 @@ Optional parameters to customize the camera settings.
| ALLMEDIA | <code>number</code> | <code>2</code> | Allow selection from all media types |
<a name="module_Camera.PictureSourceType"></a>
+
### Camera.PictureSourceType : <code>enum</code>
**Kind**: static enum property of <code>[Camera](#module_Camera)</code>
**Properties**
@@ -296,6 +307,7 @@ Optional parameters to customize the camera settings.
| SAVEDPHOTOALBUM | <code>number</code> | <code>2</code> | Choose image from picture library (same as PHOTOLIBRARY for Android) |
<a name="module_Camera.PopoverArrowDirection"></a>
+
### Camera.PopoverArrowDirection : <code>enum</code>
Matches iOS UIPopoverArrowDirection constants to specify arrow location on popover.
@@ -311,6 +323,7 @@ Matches iOS UIPopoverArrowDirection constants to specify arrow location on popov
| ARROW_ANY | <code>number</code> | <code>15</code> |
<a name="module_Camera.Direction"></a>
+
### Camera.Direction : <code>enum</code>
**Kind**: static enum property of <code>[Camera](#module_Camera)</code>
**Properties**
@@ -323,6 +336,7 @@ Matches iOS UIPopoverArrowDirection constants to specify arrow location on popov
---
<a name="module_CameraPopoverOptions"></a>
+
## CameraPopoverOptions
iOS-only parameters that specify the anchor element location and arrow
direction of the popover when selecting images from an iPad's library
@@ -344,6 +358,7 @@ location.
---
<a name="module_CameraPopoverHandle"></a>
+
## CameraPopoverHandle
A handle to an image picker popover.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-contacts/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-contacts/index.md b/www/docs/en/6.x/reference/cordova-plugin-contacts/index.md
index 5890058..9bd4f6c 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-contacts/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-contacts/index.md
@@ -34,11 +34,12 @@ description: Manage the contacts on the device.
This plugin defines a global `navigator.contacts` object, which provides access to the device contacts database.
Although the object is attached to the global scoped `navigator`, it is not available until after the `deviceready` event.
-
- document.addEventListener("deviceready", onDeviceReady, false);
- function onDeviceReady() {
- console.log(navigator.contacts);
- }
+```js
+document.addEventListener("deviceready", onDeviceReady, false);
+function onDeviceReady() {
+console.log(navigator.contacts);
+}
+```
__WARNING__: Collection and use of contact data raises
important privacy issues. Your app's privacy policy should discuss
@@ -80,14 +81,15 @@ Add relevant permisions.
There is also a need to change the webapp type to "privileged" - [Manifest Docs](https://developer.mozilla.org/en-US/Apps/Developing/Manifest#type).
__WARNING__: All privileged apps enforce [Content Security Policy](https://developer.mozilla.org/en-US/Apps/CSP) which forbids inline script. Initialize your application in another way.
- "type": "privileged",
- "permissions": {
- "contacts": {
- "access": "readwrite",
- "description": "Describe why there is a need for such permission"
- }
+```json
+"type": "privileged",
+"permissions": {
+ "contacts": {
+ "access": "readwrite",
+ "description": "Describe why there is a need for such permission"
}
-
+}
+```
### Windows Quirks
**Prior to Windows 10:** Any contacts returned from `find` and `pickContact` methods are readonly, so your application cannot modify them.
@@ -136,7 +138,9 @@ database, for which you need to invoke the `Contact.save` method.
### Example
+```js
var myContact = navigator.contacts.create({"displayName": "Test User"});
+```
## navigator.contacts.find
@@ -190,22 +194,24 @@ Supported values for both __contactFields__ and __contactFindOptions.desiredFiel
### Example
- function onSuccess(contacts) {
- alert('Found ' + contacts.length + ' contacts.');
- };
-
- function onError(contactError) {
- alert('onError!');
- };
-
- // find all contacts with 'Bob' in any name field
- var options = new ContactFindOptions();
- options.filter = "Bob";
- options.multiple = true;
- options.desiredFields = [navigator.contacts.fieldType.id];
- options.hasPhoneNumber = true;
- var fields = [navigator.contacts.fieldType.displayName, navigator.contacts.fieldType.name];
- navigator.contacts.find(fields, onSuccess, onError, options);
+```js
+function onSuccess(contacts) {
+ alert('Found ' + contacts.length + ' contacts.');
+};
+
+function onError(contactError) {
+ alert('onError!');
+};
+
+// find all contacts with 'Bob' in any name field
+var options = new ContactFindOptions();
+options.filter = "Bob";
+options.multiple = true;
+options.desiredFields = [navigator.contacts.fieldType.id];
+options.hasPhoneNumber = true;
+var fields = [navigator.contacts.fieldType.displayName, navigator.contacts.fieldType.name];
+navigator.contacts.find(fields, onSuccess, onError, options);
+```
### Windows Quirks
@@ -232,11 +238,13 @@ function specified by the __contactSuccess__ parameter.
### Example
- navigator.contacts.pickContact(function(contact){
- console.log('The following contact has been selected:' + JSON.stringify(contact));
- },function(err){
- console.log('Error: ' + err);
- });
+```js
+navigator.contacts.pickContact(function(contact){
+ console.log('The following contact has been selected:' + JSON.stringify(contact));
+ },function(err){
+ console.log('Error: ' + err);
+ });
+```
### Android Quirks
@@ -321,75 +329,82 @@ for details.
### Save Example
- function onSuccess(contact) {
- alert("Save Success");
- };
+```js
+function onSuccess(contact) {
+ alert("Save Success");
+};
- function onError(contactError) {
- alert("Error = " + contactError.code);
- };
+function onError(contactError) {
+ alert("Error = " + contactError.code);
+};
- // create a new contact object
- var contact = navigator.contacts.create();
- contact.displayName = "Plumber";
- contact.nickname = "Plumber"; // specify both to support all devices
+// create a new contact object
+var contact = navigator.contacts.create();
+contact.displayName = "Plumber";
+contact.nickname = "Plumber"; // specify both to support all devices
- // populate some fields
- var name = new ContactName();
- name.givenName = "Jane";
- name.familyName = "Doe";
- contact.name = name;
+// populate some fields
+var name = new ContactName();
+name.givenName = "Jane";
+name.familyName = "Doe";
+contact.name = name;
- // save to device
- contact.save(onSuccess,onError);
+// save to device
+contact.save(onSuccess,onError);
+```
### Clone Example
- // clone the contact object
- var clone = contact.clone();
- clone.name.givenName = "John";
- console.log("Original contact name = " + contact.name.givenName);
- console.log("Cloned contact name = " + clone.name.givenName);
+```js
+// clone the contact object
+var clone = contact.clone();
+clone.name.givenName = "John";
+console.log("Original contact name = " + contact.name.givenName);
+console.log("Cloned contact name = " + clone.name.givenName);
+```
### Remove Example
- function onSuccess() {
- alert("Removal Success");
- };
-
- function onError(contactError) {
- alert("Error = " + contactError.code);
- };
+```js
+function onSuccess() {
+ alert("Removal Success");
+};
- // remove the contact from the device
- contact.remove(onSuccess,onError);
+function onError(contactError) {
+ alert("Error = " + contactError.code);
+};
+// remove the contact from the device
+contact.remove(onSuccess,onError);
+```
### Removing phone number(s) from a saved contact
- // Example to create a contact with 3 phone numbers and then remove
- // 2 phone numbers. This example is for illustrative purpose only
- var myContact = navigator.contacts.create({"displayName": "Test User"});
- var phoneNumbers = [];
-
- phoneNumbers[0] = new ContactField('work', '768-555-1234', false);
- phoneNumbers[1] = new ContactField('mobile', '999-555-5432', true); // preferred number
- phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
-
- myContact.phoneNumbers = phoneNumbers;
- myContact.save(function (contact_obj) {
- var contactObjToModify = contact_obj.clone();
- contact_obj.remove(function(){
- var phoneNumbers = [contactObjToModify.phoneNumbers[0]];
- contactObjToModify.phoneNumbers = phoneNumbers;
- contactObjToModify.save(function(c_obj){
- console.log("All Done");
- }, function(error){
- console.log("Not able to save the cloned object: " + error);
- });
- }, function(contactError) {
- console.log("Contact Remove Operation failed: " + contactError);
+```js
+// Example to create a contact with 3 phone numbers and then remove
+// 2 phone numbers. This example is for illustrative purpose only
+var myContact = navigator.contacts.create({"displayName": "Test User"});
+var phoneNumbers = [];
+
+phoneNumbers[0] = new ContactField('work', '768-555-1234', false);
+phoneNumbers[1] = new ContactField('mobile', '999-555-5432', true); // preferred number
+phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
+
+myContact.phoneNumbers = phoneNumbers;
+myContact.save(function (contact_obj) {
+ var contactObjToModify = contact_obj.clone();
+ contact_obj.remove(function(){
+ var phoneNumbers = [contactObjToModify.phoneNumbers[0]];
+ contactObjToModify.phoneNumbers = phoneNumbers;
+ contactObjToModify.save(function(c_obj){
+ console.log("All Done");
+ }, function(error){
+ console.log("Not able to save the cloned object: " + error);
});
+ }, function(contactError) {
+ console.log("Contact Remove Operation failed: " + contactError);
});
+});
+```
### Android 2.X Quirks
@@ -489,33 +504,35 @@ a `ContactAddress[]` array.
### Example
- // display the address information for all contacts
-
- function onSuccess(contacts) {
- for (var i = 0; i < contacts.length; i++) {
- for (var j = 0; j < contacts[i].addresses.length; j++) {
- alert("Pref: " + contacts[i].addresses[j].pref + "\n" +
- "Type: " + contacts[i].addresses[j].type + "\n" +
- "Formatted: " + contacts[i].addresses[j].formatted + "\n" +
- "Street Address: " + contacts[i].addresses[j].streetAddress + "\n" +
- "Locality: " + contacts[i].addresses[j].locality + "\n" +
- "Region: " + contacts[i].addresses[j].region + "\n" +
- "Postal Code: " + contacts[i].addresses[j].postalCode + "\n" +
- "Country: " + contacts[i].addresses[j].country);
- }
+```js
+// display the address information for all contacts
+
+function onSuccess(contacts) {
+ for (var i = 0; i < contacts.length; i++) {
+ for (var j = 0; j < contacts[i].addresses.length; j++) {
+ alert("Pref: " + contacts[i].addresses[j].pref + "\n" +
+ "Type: " + contacts[i].addresses[j].type + "\n" +
+ "Formatted: " + contacts[i].addresses[j].formatted + "\n" +
+ "Street Address: " + contacts[i].addresses[j].streetAddress + "\n" +
+ "Locality: " + contacts[i].addresses[j].locality + "\n" +
+ "Region: " + contacts[i].addresses[j].region + "\n" +
+ "Postal Code: " + contacts[i].addresses[j].postalCode + "\n" +
+ "Country: " + contacts[i].addresses[j].country);
}
- };
-
- function onError(contactError) {
- alert('onError!');
- };
-
- // find all contacts
- var options = new ContactFindOptions();
- options.filter = "";
- options.multiple = true;
- var filter = ["displayName", "addresses"];
- navigator.contacts.find(filter, onSuccess, onError, options);
+ }
+};
+
+function onError(contactError) {
+ alert('onError!');
+};
+
+// find all contacts
+var options = new ContactFindOptions();
+options.filter = "";
+options.multiple = true;
+var filter = ["displayName", "addresses"];
+navigator.contacts.find(filter, onSuccess, onError, options);
+```
### Android 2.X Quirks
@@ -613,18 +630,20 @@ string.
### Example
- // create a new contact
- var contact = navigator.contacts.create();
+```js
+// create a new contact
+var contact = navigator.contacts.create();
- // store contact phone numbers in ContactField[]
- var phoneNumbers = [];
- phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
- phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
- phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
- contact.phoneNumbers = phoneNumbers;
+// store contact phone numbers in ContactField[]
+var phoneNumbers = [];
+phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
+phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
+phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
+contact.phoneNumbers = phoneNumbers;
- // save the contact
- contact.save();
+// save the contact
+contact.save();
+```
### Android Quirks
@@ -677,26 +696,28 @@ Contains different kinds of information about a `Contact` object's name.
### Example
- function onSuccess(contacts) {
- for (var i = 0; i < contacts.length; i++) {
- alert("Formatted: " + contacts[i].name.formatted + "\n" +
- "Family Name: " + contacts[i].name.familyName + "\n" +
- "Given Name: " + contacts[i].name.givenName + "\n" +
- "Middle Name: " + contacts[i].name.middleName + "\n" +
- "Suffix: " + contacts[i].name.honorificSuffix + "\n" +
- "Prefix: " + contacts[i].name.honorificSuffix);
- }
- };
+```js
+function onSuccess(contacts) {
+ for (var i = 0; i < contacts.length; i++) {
+ alert("Formatted: " + contacts[i].name.formatted + "\n" +
+ "Family Name: " + contacts[i].name.familyName + "\n" +
+ "Given Name: " + contacts[i].name.givenName + "\n" +
+ "Middle Name: " + contacts[i].name.middleName + "\n" +
+ "Suffix: " + contacts[i].name.honorificSuffix + "\n" +
+ "Prefix: " + contacts[i].name.honorificSuffix);
+ }
+};
- function onError(contactError) {
- alert('onError!');
- };
+function onError(contactError) {
+ alert('onError!');
+};
- var options = new ContactFindOptions();
- options.filter = "";
- options.multiple = true;
- filter = ["displayName", "name"];
- navigator.contacts.find(filter, onSuccess, onError, options);
+var options = new ContactFindOptions();
+options.filter = "";
+options.multiple = true;
+filter = ["displayName", "name"];
+navigator.contacts.find(filter, onSuccess, onError, options);
+```
### Android Quirks
@@ -770,27 +791,29 @@ properties. A `Contact` object stores one or more
### Example
- function onSuccess(contacts) {
- for (var i = 0; i < contacts.length; i++) {
- for (var j = 0; j < contacts[i].organizations.length; j++) {
- alert("Pref: " + contacts[i].organizations[j].pref + "\n" +
- "Type: " + contacts[i].organizations[j].type + "\n" +
- "Name: " + contacts[i].organizations[j].name + "\n" +
- "Department: " + contacts[i].organizations[j].department + "\n" +
- "Title: " + contacts[i].organizations[j].title);
- }
+```js
+function onSuccess(contacts) {
+ for (var i = 0; i < contacts.length; i++) {
+ for (var j = 0; j < contacts[i].organizations.length; j++) {
+ alert("Pref: " + contacts[i].organizations[j].pref + "\n" +
+ "Type: " + contacts[i].organizations[j].type + "\n" +
+ "Name: " + contacts[i].organizations[j].name + "\n" +
+ "Department: " + contacts[i].organizations[j].department + "\n" +
+ "Title: " + contacts[i].organizations[j].title);
}
- };
+ }
+};
- function onError(contactError) {
- alert('onError!');
- };
+function onError(contactError) {
+ alert('onError!');
+};
- var options = new ContactFindOptions();
- options.filter = "";
- options.multiple = true;
- filter = ["displayName", "organizations"];
- navigator.contacts.find(filter, onSuccess, onError, options);
+var options = new ContactFindOptions();
+options.filter = "";
+options.multiple = true;
+filter = ["displayName", "organizations"];
+navigator.contacts.find(filter, onSuccess, onError, options);
+```
### Android 2.X Quirks
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-dialogs/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-dialogs/index.md b/www/docs/en/6.x/reference/cordova-plugin-dialogs/index.md
index a487600..cb566b0 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-dialogs/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-dialogs/index.md
@@ -89,6 +89,7 @@ function, which is typically less customizable.
- Amazon Fire OS
- Android
- BlackBerry 10
+- Browser
- Firefox OS
- iOS
- Tizen
@@ -153,6 +154,7 @@ indexing, so the value is `1`, `2`, `3`, etc.
- Amazon Fire OS
- Android
- BlackBerry 10
+- Browser
- Firefox OS
- iOS
- Tizen
@@ -224,6 +226,7 @@ contains the following properties:
- Amazon Fire OS
- Android
+- Browser
- Firefox OS
- iOS
- Windows Phone 7 and 8
@@ -262,6 +265,7 @@ The device plays a beep sound.
- Amazon Fire OS
- Android
- BlackBerry 10
+- Browser
- iOS
- Tizen
- Windows Phone 7 and 8
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-file-transfer/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-file-transfer/index.md b/www/docs/en/6.x/reference/cordova-plugin-file-transfer/index.md
index 623bee5..454bbb3 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-file-transfer/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-file-transfer/index.md
@@ -35,16 +35,20 @@ This plugin allows you to upload and download files.
This plugin defines global `FileTransfer`, `FileUploadOptions` constructors. Although in the global scope, they are not available until after the `deviceready` event.
- document.addEventListener("deviceready", onDeviceReady, false);
- function onDeviceReady() {
- console.log(FileTransfer);
- }
+```js
+document.addEventListener("deviceready", onDeviceReady, false);
+function onDeviceReady() {
+ console.log(FileTransfer);
+}
+```
Report issues with this plugin on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20File%20Transfer%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC)
## Installation
- cordova plugin add cordova-plugin-file-transfer
+```bash
+cordova plugin add cordova-plugin-file-transfer
+```
## Supported Platforms
@@ -104,70 +108,74 @@ __Parameters__:
### Example
- // !! Assumes variable fileURL contains a valid URL to a text file on the device,
- // for example, cdvfile://localhost/persistent/path/to/file.txt
+```js
+// !! Assumes variable fileURL contains a valid URL to a text file on the device,
+// for example, cdvfile://localhost/persistent/path/to/file.txt
- var win = function (r) {
- console.log("Code = " + r.responseCode);
- console.log("Response = " + r.response);
- console.log("Sent = " + r.bytesSent);
- }
+var win = function (r) {
+ console.log("Code = " + r.responseCode);
+ console.log("Response = " + r.response);
+ console.log("Sent = " + r.bytesSent);
+}
- var fail = function (error) {
- alert("An error has occurred: Code = " + error.code);
- console.log("upload error source " + error.source);
- console.log("upload error target " + error.target);
- }
+var fail = function (error) {
+ alert("An error has occurred: Code = " + error.code);
+ console.log("upload error source " + error.source);
+ console.log("upload error target " + error.target);
+}
- var options = new FileUploadOptions();
- options.fileKey = "file";
- options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
- options.mimeType = "text/plain";
+var options = new FileUploadOptions();
+options.fileKey = "file";
+options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
+options.mimeType = "text/plain";
- var params = {};
- params.value1 = "test";
- params.value2 = "param";
+var params = {};
+params.value1 = "test";
+params.value2 = "param";
- options.params = params;
+options.params = params;
- var ft = new FileTransfer();
- ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail, options);
+var ft = new FileTransfer();
+ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail, options);
+```
### Example with Upload Headers and Progress Events (Android and iOS only)
- function win(r) {
- console.log("Code = " + r.responseCode);
- console.log("Response = " + r.response);
- console.log("Sent = " + r.bytesSent);
- }
+```js
+function win(r) {
+ console.log("Code = " + r.responseCode);
+ console.log("Response = " + r.response);
+ console.log("Sent = " + r.bytesSent);
+}
- function fail(error) {
- alert("An error has occurred: Code = " + error.code);
- console.log("upload error source " + error.source);
- console.log("upload error target " + error.target);
- }
+function fail(error) {
+ alert("An error has occurred: Code = " + error.code);
+ console.log("upload error source " + error.source);
+ console.log("upload error target " + error.target);
+}
- var uri = encodeURI("http://some.server.com/upload.php");
+var uri = encodeURI("http://some.server.com/upload.php");
- var options = new FileUploadOptions();
- options.fileKey="file";
- options.fileName=fileURL.substr(fileURL.lastIndexOf('/')+1);
- options.mimeType="text/plain";
+var options = new FileUploadOptions();
+options.fileKey="file";
+options.fileName=fileURL.substr(fileURL.lastIndexOf('/')+1);
+options.mimeType="text/plain";
- var headers={'headerParam':'headerValue'};
+var headers={'headerParam':'headerValue'};
- options.headers = headers;
-
- var ft = new FileTransfer();
- ft.onprogress = function(progressEvent) {
- if (progressEvent.lengthComputable) {
- loadingStatus.setPercentage(progressEvent.loaded / progressEvent.total);
- } else {
- loadingStatus.increment();
- }
- };
- ft.upload(fileURL, uri, win, fail, options);
+options.headers = headers;
+var ft = new FileTransfer();
+ft.onprogress = function(progressEvent) {
+ if (progressEvent.lengthComputable) {
+ loadingStatus.setPercentage(progressEvent.loaded / progressEvent.total);
+ } else {
+ loadingStatus.increment();
+ }
+};
+ft.upload(fileURL, uri, win, fail, options);
+```
+
## FileUploadResult
A `FileUploadResult` object is passed to the success callback of the
@@ -214,30 +222,32 @@ __Parameters__:
### Example
- // !! Assumes variable fileURL contains a valid URL to a path on the device,
- // for example, cdvfile://localhost/persistent/path/to/downloads/
-
- var fileTransfer = new FileTransfer();
- var uri = encodeURI("http://some.server.com/download.php");
-
- fileTransfer.download(
- uri,
- fileURL,
- function(entry) {
- console.log("download complete: " + entry.toURL());
- },
- function(error) {
- console.log("download error source " + error.source);
- console.log("download error target " + error.target);
- console.log("upload error code" + error.code);
- },
- false,
- {
- headers: {
- "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
- }
+```js
+// !! Assumes variable fileURL contains a valid URL to a path on the device,
+// for example, cdvfile://localhost/persistent/path/to/downloads/
+
+var fileTransfer = new FileTransfer();
+var uri = encodeURI("http://some.server.com/download.php");
+
+fileTransfer.download(
+ uri,
+ fileURL,
+ function(entry) {
+ console.log("download complete: " + entry.toURL());
+ },
+ function(error) {
+ console.log("download error source " + error.source);
+ console.log("download error target " + error.target);
+ console.log("upload error code" + error.code);
+ },
+ false,
+ {
+ headers: {
+ "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
}
- );
+ }
+);
+```
### WP8 Quirks
@@ -253,29 +263,30 @@ Aborts an in-progress transfer. The onerror callback is passed a FileTransferErr
### Example
- // !! Assumes variable fileURL contains a valid URL to a text file on the device,
- // for example, cdvfile://localhost/persistent/path/to/file.txt
-
- var win = function(r) {
- console.log("Should not be called.");
- }
+```js
+// !! Assumes variable fileURL contains a valid URL to a text file on the device,
+// for example, cdvfile://localhost/persistent/path/to/file.txt
- var fail = function(error) {
- // error.code == FileTransferError.ABORT_ERR
- alert("An error has occurred: Code = " + error.code);
- console.log("upload error source " + error.source);
- console.log("upload error target " + error.target);
- }
+var win = function(r) {
+ console.log("Should not be called.");
+}
- var options = new FileUploadOptions();
- options.fileKey="file";
- options.fileName="myphoto.jpg";
- options.mimeType="image/jpeg";
+var fail = function(error) {
+ // error.code == FileTransferError.ABORT_ERR
+ alert("An error has occurred: Code = " + error.code);
+ console.log("upload error source " + error.source);
+ console.log("upload error target " + error.target);
+}
- var ft = new FileTransfer();
- ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail, options);
- ft.abort();
+var options = new FileUploadOptions();
+options.fileKey="file";
+options.fileName="myphoto.jpg";
+options.mimeType="image/jpeg";
+var ft = new FileTransfer();
+ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail, options);
+ft.abort();
+```
## FileTransferError
@@ -325,3 +336,253 @@ If you are upgrading to a new (1.0.0 or newer) version of File, and you have pre
cdvfile://localhost/persistent/path/to/file
which can be used in place of the absolute file path in both `download()` and `upload()` methods.
+
+## Sample: Download and Upload Files <a name="sample"></a>
+
+Use the File-Transfer plugin to upload and download files. In these examples, we demonstrate several tasks like:
+
+* [Downloading a binary file to the application cache](#binaryFile)
+* [Uploading a file created in your application's root](#uploadFile)
+* [Downloading the uploaded file](#downloadFile)
+
+## Download a Binary File to the application cache <a name="binaryFile"></a>
+
+Use the File plugin with the File-Transfer plugin to provide a target for the files that you download (the target must be a FileEntry object). Before you download the file, create a DirectoryEntry object by using `resolveLocalFileSystemURL` and calling `fs.root` in the success callback. Use the `getFile` method of DirectoryEntry to create the target file.
+
+```js
+window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+ console.log('file system open: ' + fs.name);
+
+ // Make sure you add the domain name to the Content-Security-Policy <meta> element.
+ var url = 'http://cordova.apache.org/static/img/cordova_bot.png';
+ // Parameters passed to getFile create a new file or return the file if it already exists.
+ fs.root.getFile('downloaded-image.png', { create: true, exclusive: false }, function (fileEntry) {
+ download(fileEntry, url, true);
+
+ }, onErrorCreateFile);
+
+}, onErrorLoadFs);
+```
+
+>*Note* For persistent storage, pass LocalFileSystem.PERSISTENT to requestFileSystem.
+
+When you have the FileEntry object, download the file using the `download` method of the FileTransfer object. The 3rd argument to the `download` function of FileTransfer is the success callback, which you can use to call the app's `readBinaryFile` function. In this code example, the `entry` variable is a new FileEntry object that receives the result of the download operation.
+
+```js
+function download(fileEntry, uri, readBinaryData) {
+
+ var fileTransfer = new FileTransfer();
+ var fileURL = fileEntry.toURL();
+
+ fileTransfer.download(
+ uri,
+ fileURL,
+ function (entry) {
+ console.log("Successful download...");
+ console.log("download complete: " + entry.toURL());
+ if (readBinaryData) {
+ // Read the file...
+ readBinaryFile(entry);
+ }
+ else {
+ // Or just display it.
+ displayImageByFileURL(entry);
+ }
+ },
+ function (error) {
+ console.log("download error source " + error.source);
+ console.log("download error target " + error.target);
+ console.log("upload error code" + error.code);
+ },
+ null, // or, pass false
+ {
+ //headers: {
+ // "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
+ //}
+ }
+ );
+}
+```
+
+If you just need to display the image, take the FileEntry to call its toURL() function.
+
+```js
+function displayImageByFileURL(fileEntry) {
+ var elem = document.getElementById('imageFile');
+ elem.src = fileEntry.toURL();
+}
+```
+
+Depending on your app requirements, you may want to read the file. To support operations with binary files, FileReader supports two methods, `readAsBinaryString` and `readAsArrayBuffer`. In this example, use `readAsArrayBuffer` and pass the FileEntry object to the method. Once you read the file successfully, construct a Blob object using the result of the read.
+
+```js
+function readBinaryFile(fileEntry) {
+ fileEntry.file(function (file) {
+ var reader = new FileReader();
+
+ reader.onloadend = function() {
+
+ console.log("Successful file read: " + this.result);
+ // displayFileData(fileEntry.fullPath + ": " + this.result);
+
+ var blob = new Blob([new Uint8Array(this.result)], { type: "image/png" });
+ displayImage(blob);
+ };
+
+ reader.readAsArrayBuffer(file);
+
+ }, onErrorReadFile);
+}
+```
+
+Once you read the file successfully, you can create a DOM URL string using `createObjectURL`, and then display the image.
+
+```js
+function displayImage(blob) {
+
+ // Note: Use window.URL.revokeObjectURL when finished with image.
+ var objURL = window.URL.createObjectURL(blob);
+
+ // Displays image if result is a valid DOM string for an image.
+ var elem = document.getElementById('imageFile');
+ elem.src = objURL;
+}
+```
+
+As you saw previously, you can call FileEntry.toURL() instead to just display the downloaded image (skip the file read).
+
+## Upload a File <a name="uploadFile"></a>
+
+When you upload a File using the File-Transfer plugin, use the File plugin to provide files for upload (again, they must be FileEntry objects). Before you can upload anything, create a file for upload using the `getFile` method of DirectoryEntry. In this example, create the file in the application's cache (fs.root). Then call the app's writeFile function so you have some content to upload.
+
+```js
+function onUploadFile() {
+ window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+ console.log('file system open: ' + fs.name);
+ var fileName = "uploadSource.txt";
+ var dirEntry = fs.root;
+ dirEntry.getFile(fileName, { create: true, exclusive: false }, function (fileEntry) {
+
+ // Write something to the file before uploading it.
+ writeFile(fileEntry);
+
+ }, onErrorCreateFile);
+
+ }, onErrorLoadFs);
+}
+```
+
+In this example, create some simple content, and then call the app's upload function.
+
+```js
+function writeFile(fileEntry, dataObj) {
+ // Create a FileWriter object for our FileEntry (log.txt).
+ fileEntry.createWriter(function (fileWriter) {
+
+ fileWriter.onwriteend = function () {
+ console.log("Successful file write...");
+ upload(fileEntry);
+ };
+
+ fileWriter.onerror = function (e) {
+ console.log("Failed file write: " + e.toString());
+ };
+
+ if (!dataObj) {
+ dataObj = new Blob(['file data to upload'], { type: 'text/plain' });
+ }
+
+ fileWriter.write(dataObj);
+ });
+}
+```
+
+Forward the FileEntry object to the upload function. To perform the actual upload, use the upload function of the FileTransfer object.
+
+```js
+function upload(fileEntry) {
+ // !! Assumes variable fileURL contains a valid URL to a text file on the device,
+ var fileURL = fileEntry.toURL();
+
+ var success = function (r) {
+ console.log("Successful upload...");
+ console.log("Code = " + r.responseCode);
+ displayFileData(fileEntry.fullPath + " (content uploaded to server)");
+ }
+
+ var fail = function (error) {
+ alert("An error has occurred: Code = " + error.code);
+ }
+
+ var options = new FileUploadOptions();
+ options.fileKey = "file";
+ options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
+ options.mimeType = "text/plain";
+
+ var params = {};
+ params.value1 = "test";
+ params.value2 = "param";
+
+ options.params = params;
+
+ var ft = new FileTransfer();
+ // SERVER must be a URL that can handle the request, like
+ // http://some.server.com/upload.php
+ ft.upload(fileURL, encodeURI(SERVER), success, fail, options);
+};
+```
+
+## Download the uploaded file <a name="downloadFile"></a>
+
+To download the image you just uploaded, you will need a valid URL that can handle the request, for example, http://some.server.com/download.php. Again, the success handler for the FileTransfer.download method receives a FileEntry object. The main difference here from previous examples is that we call FileReader.readAsText to read the result of the download operation, because we uploaded a file with text content.
+
+```js
+function download(fileEntry, uri) {
+
+ var fileTransfer = new FileTransfer();
+ var fileURL = fileEntry.toURL();
+
+ fileTransfer.download(
+ uri,
+ fileURL,
+ function (entry) {
+ console.log("Successful download...");
+ console.log("download complete: " + entry.toURL());
+ readFile(entry);
+ },
+ function (error) {
+ console.log("download error source " + error.source);
+ console.log("download error target " + error.target);
+ console.log("upload error code" + error.code);
+ },
+ null, // or, pass false
+ {
+ //headers: {
+ // "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
+ //}
+ }
+ );
+}
+```
+
+In the readFile function, call the `readAsText` method of the FileReader object.
+
+```js
+function readFile(fileEntry) {
+ fileEntry.file(function (file) {
+ var reader = new FileReader();
+
+ reader.onloadend = function () {
+
+ console.log("Successful file read: " + this.result);
+ // displayFileData(fileEntry.fullPath + ": " + this.result);
+
+ };
+
+ reader.readAsText(file);
+
+ }, onErrorReadFile);
+}
+```
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org
[3/3] docs commit: Snapshotting dev to 6.x
Posted by ra...@apache.org.
Snapshotting dev to 6.x
This closes #603
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/1360af4b
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/1360af4b
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/1360af4b
Branch: refs/heads/master
Commit: 1360af4b50dbe0f38aa9bfa4187f4c92ea799472
Parents: 1a1cbcc
Author: Raghav Katyal <ra...@microsoft.com>
Authored: Mon May 16 12:04:12 2016 -0700
Committer: Raghav Katyal <ra...@microsoft.com>
Committed: Mon May 16 14:52:49 2016 -0700
----------------------------------------------------------------------
www/docs/en/6.x/config_ref/images.md | 31 +-
www/docs/en/6.x/config_ref/index.md | 708 ++++++++++---------
www/docs/en/6.x/cordova/events/events.md | 18 +
www/docs/en/6.x/cordova/storage/storage.md | 12 +-
www/docs/en/6.x/guide/platforms/win8/index.md | 6 +-
www/docs/en/6.x/guide/platforms/win8/plugin.md | 2 +-
www/docs/en/6.x/plugin_ref/plugman.md | 42 +-
www/docs/en/6.x/plugin_ref/spec.md | 88 +--
www/docs/en/6.x/reference/cordova-cli/index.md | 86 ++-
.../reference/cordova-plugin-camera/index.md | 15 +
.../reference/cordova-plugin-contacts/index.md | 339 ++++-----
.../reference/cordova-plugin-dialogs/index.md | 4 +
.../cordova-plugin-file-transfer/index.md | 453 +++++++++---
.../6.x/reference/cordova-plugin-file/index.md | 327 ++++++++-
.../cordova-plugin-geolocation/index.md | 8 +-
.../cordova-plugin-inappbrowser/index.md | 231 ++++++
.../cordova-plugin-media-capture/index.md | 38 +
.../6.x/reference/cordova-plugin-media/index.md | 86 +++
.../cordova-plugin-network-information/index.md | 120 ++++
.../cordova-plugin-splashscreen/index.md | 42 +-
20 files changed, 1945 insertions(+), 711 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/config_ref/images.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/config_ref/images.md b/www/docs/en/6.x/config_ref/images.md
index 699645e..c50956d 100644
--- a/www/docs/en/6.x/config_ref/images.md
+++ b/www/docs/en/6.x/config_ref/images.md
@@ -19,17 +19,17 @@ license: >
title: Customize app icons
toc_title: Customize icons
-description: Learn how to customize icons for your Cordova app.
+description: Learn how to customize icons for your Cordova application.
---
# Customize Icons
-This section shows how to configure an app's icon for various platforms. Support for splash screen has moved to a Cordova plugin of its own. The configuration options can be found in the [Splashscreen plugin docs][splashscreen_plugin].
+This section shows how to configure an application's icon for various platforms. Documentation about splash screen images can be found in the Cordova-Plugin-Splashscreen documentation [Splashscreen plugin docs][splashscreen_plugin].
## Configuring Icons in the CLI
-When working in the CLI you can define app icon(s) via `<icon>` element (`config.xml`).
-If you do not specify an icon then the Apache Cordova logo is used.
+When working in the CLI you can define application icon(s) via the `<icon>` element (`config.xml`).
+If you do not specify an icon, the Apache Cordova logo is used.
```xml
<icon src="res/ios/icon.png" platform="ios" width="57" height="57" density="mdpi" />
@@ -45,12 +45,12 @@ density | *Optional* <br/> ==Android== <br/> Specified icon density
target | *Optional* <br/> ==Windows== <br/> Destination filename for the image file and all its' MRT companions
-The following configuration can be used to define single default icon
+The following configuration can be used to define a single default icon
which will be used for all platforms.
```xml
<icon src="res/icon.png" />
```
-For each platform you can also define a pixel-perfect icons set to fit
+For each platform, you can also define a pixel-perfect icon set to fit
different screen resolutions.
##Android
@@ -86,6 +86,9 @@ different screen resolutions.
###See Also
- [BlackBerry's documentation][blackberry_icon] for targeting multiple sizes and locales.
+##Browser
+Icons are not applicable to the Browser platform.
+
##iOS
```xml
<platform name="ios">
@@ -122,7 +125,7 @@ different screen resolutions.
##Windows
-For Windows the recommended approach to define app icons is to use `target` attribute.
+For Windows the recommended approach to define application icons is to use the `target` attribute.
```xml
<platform name="windows">
@@ -137,15 +140,17 @@ For Windows the recommended approach to define app icons is to use `target` attr
</platform>
```
-where `source` is the path to the icon which needs to be added.
+where `src` is the path to the icon which needs to be added.
+
+The Windows platform handles MRT icons automatically, so if you specify `src="res/windows/storelogo.png"` the following files will be copied into the application's `images` folder: `res/windows/storelogo.scale-100.png`, `res/windows/storelogo.scale-200.png`, etc.
-Please note that Windows platform handles MRT icons automatically, so if you specify `src="res/windows/storelogo.png"` the following files will be copied into app's `images` folder: `res/windows/storelogo.scale-100.png`, `res/windows/storelogo.scale-200.png`, etc.
+TODO Define what MRT is.
-The `target` attribute specifies the base name for resultant icons. For every icon file destination filename is calculated as `target + '.' + MRT_qualifiers + extension(src)`. For the icons to display properly in resultant app every `target` value should be the one of icon filenames, defined in application's `.appxmanifest` file.
+The `target` attribute specifies the base name for the resultant icons. For every icon file, its destination filename is calculated as `target + '.' + MRT_qualifiers + extension(src)`. For the icons to display properly in the application, every `target` value should be one of the icon filenames defined in the application's `.appxmanifest` file.
-Summarizing the above, using `target` attribute it is possible to:
+Summarizing the above... using the `target` attribute it is possible to:
- * define a group of icons for different device scale factors using single `<icon ...>` element, for example:
+ * define a group of icons for different device scale factors using a single `<icon ...>` element, for example:
```xml
<icon src="res/Windows/AppListIcon.png" target="Square44x44Logo" />
```
@@ -158,7 +163,7 @@ Summarizing the above, using `target` attribute it is possible to:
```
* define icons with scale factors other than `scale-100` and `scale-240` (and any other MRT qualifiers)
-Though it is not recommended but is still possible to define icons using `width` and `height` attributes:
+Although it is not recommended, it is also possible to define icons using the `width` and `height` attributes:
```xml
<platform name="windows">
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/config_ref/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/config_ref/index.md b/www/docs/en/6.x/config_ref/index.md
index 7d5878d..bac6ea0 100644
--- a/www/docs/en/6.x/config_ref/index.md
+++ b/www/docs/en/6.x/config_ref/index.md
@@ -56,423 +56,453 @@ can also configure an application's core set of images for each target
platform. See [Customize icons topic](images.html) for more information.
# widget
- Root element of the config.xml document.
-
- Attributes(type) | Description
- ---------------- | ------------
- id(string) | *Required* <br/> Specifies the app's reverse-domain identifier, and the `version` its full version number expressed in major/minor/patch notation.
- version(string) | *Required* <br/> Full version number expressed in major/minor/patch notation.
- android-versionCode(string) | ==Android== <br/> Alternative version for Android. Sets the [version code](http://developer.android.com/tools/publishing/versioning.html) for the application. See [the Android guide](../guide/platforms/android/index.html#setting-the-version-code) for information on how this attribute may be modified.
- ios-CFBundleVersion(string) | ==iOS== <br/> Alternative version for iOS. For further details, see [iOS versioning](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-102364).
- osx-CFBundleVersion(string) | ==OS X== <br/> Alternative version for OS X. For further details, see [OS X versioning](https://developer.apple.com/library/prerelease/mac/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-102364).
- windows-packageVersion(string) | ==Windows== <br/> Alternative version for Windows. For futher details, see [Windows versioning](https://msdn.microsoft.com/en-us/library/windows/apps/br211441.aspx)
- packageName(string) | *Default: Cordova.Example* <br/> ==Windows== <br/> Package name for Windows.
- xmlns(string) | *Required* <br/> Namespace for the config.xml document.
- xmlns:cdv(string) | *Required* <br/> Namespace prefix.
-
- Examples:
-
- ```xml
- <!-- Android -->
- <widget id="io.cordova.hellocordova" version="0.0.1" android-versionCode="0.1.3" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
- </widget>
-
- <!-- iOS -->
- <widget id="io.cordova.hellocordova" version="0.0.1" ios-CFBundleVersion="0.1.3" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
- </widget>
-
- <!-- Windows -->
- <widget id="io.cordova.hellocordova" version="0.0.1" windows-packageVersion="0.1.3" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
- </widget>
-
- <!-- OS X -->
- <widget id="io.cordova.hellocordova" version="0.0.1" osx-CFBundleVersion="0.1.3" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
- </widget>
- ```
+Root element of the config.xml document.
+
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+---------------- | ------------
+id(string) | *Required* <br/> Specifies the app's reverse-domain identifier, and the `version` its full version number expressed in major/minor/patch notation.
+version(string) | *Required* <br/> Full version number expressed in major/minor/patch notation.
+android-versionCode(string) <br/> ==Android== | Alternative version for Android. Sets the [version code](http://developer.android.com/tools/publishing/versioning.html) for the application. See [the Android guide](../guide/platforms/android/index.html#setting-the-version-code) for information on how this attribute may be modified.
+ios-CFBundleVersion(string) <br/> ==iOS== | Alternative version for iOS. For further details, see [iOS versioning](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-102364).
+osx-CFBundleVersion(string) <br/> ==OS X== | Alternative version for OS X. For further details, see [OS X versioning](https://developer.apple.com/library/prerelease/mac/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-102364).
+windows-packageVersion(string) <br/> ==Windows== | Alternative version for Windows. For futher details, see [Windows versioning](https://msdn.microsoft.com/en-us/library/windows/apps/br211441.aspx)
+packageName(string) <br/> ==Windows== | *Default: Cordova.Example* <br/> Package name for Windows.
+xmlns(string) | *Required* <br/> Namespace for the config.xml document.
+xmlns:cdv(string) | *Required* <br/> Namespace prefix.
+
+Examples:
+
+```xml
+<!-- Android -->
+<widget id="io.cordova.hellocordova" version="0.0.1" android-versionCode="0.1.3" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
+</widget>
+
+<!-- iOS -->
+<widget id="io.cordova.hellocordova" version="0.0.1" ios-CFBundleVersion="0.1.3" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
+</widget>
+
+<!-- Windows -->
+<widget id="io.cordova.hellocordova" version="0.0.1" windows-packageVersion="0.1.3" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
+</widget>
+
+<!-- OS X -->
+<widget id="io.cordova.hellocordova" version="0.0.1" osx-CFBundleVersion="0.1.3" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
+</widget>
+```
## name
- Specifies the app's formal name, as it appears on the device's home screen and within app-store interfaces.
+Specifies the app's formal name, as it appears on the device's home screen and within app-store interfaces.
- Examples:
+Examples:
- ```xml
- <widget ...>
- <name>HelloCordova</name>
- </widget>
- ```
+```xml
+<widget ...>
+ <name>HelloCordova</name>
+</widget>
+```
## description
- Specifies metadata that may appear within app-store listings.
+Specifies metadata that may appear within app-store listings.
- Examples:
+Examples:
- ```xml
- <widget ...>
- <description>A sample Apache Cordova application</description>
- </widget>
- ```
+```xml
+<widget ...>
+ <description>A sample Apache Cordova application</description>
+</widget>
+```
## author
- Specifies contact information that may appear within app-store lisitngs.
+Specifies contact information that may appear within app-store lisitngs.
- Attributes(type) | Description
- ----------------- | ------------
- email(string) | *Required* <br/> Email of the author.
- href(string) | *Required* <br/> Website of the author.
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+email(string) | *Required* <br/> Email of the author.
+href(string) | *Required* <br/> Website of the author.
- Examples:
+Examples:
- ```xml
- <widget ...>
- <author email="dev@cordova.apache.org" href="http://cordova.io"></author>
- </widget>
- ```
+```xml
+<widget ...>
+ <author email="dev@cordova.apache.org" href="http://cordova.io"></author>
+</widget>
+```
## content
- Defines the app's starting page in the top-level web assets directory. The default value is index.html, which customarily
- appears in a project's top-level ```www``` directory.
+Defines the app's starting page in the top-level web assets directory. The default value is index.html, which customarily
+appears in a project's top-level ```www``` directory.
- Attributes(type) | Description
- ----------------- | ------------
- src(string) | *Required* <br/> Defines the app's starting page in the top-level web assets directory. The default value is index.html, which customarily
- appears in a project's top-level ```www``` directory.
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+src(string) | *Required* <br/> Defines the app's starting page in the top-level web assets directory. The default value is index.html, which customarily
+appears in a project's top-level ```www``` directory.
- Examples:
+Examples:
- ```xml
- <widget ...>
- <content src="startPage.html"></content>
- </widget>
- ```
+```xml
+<widget ...>
+ <content src="startPage.html"></content>
+</widget>
+```
## access
- Defines the set of external domains the app is allowed to communicate with. The default value shown above allows it to access any server.
- See the Domain [Whitelist Guide](../guide/appdev/whitelist/index.html) for details.
+Defines the set of external domains the app is allowed to communicate with. The default value shown above allows it to access any server.
+See the Domain [Whitelist Guide](../guide/appdev/whitelist/index.html) for details.
- Attributes(type) | Description
- ----------------- | ------------
- origin(string) | *Required* <br/> Defines the set of external domains the app is allowed to communicate with.
- The default value shown above allows it to access any server.
- See the Domain [Whitelist Guide](../guide/appdev/whitelist/index.html) for details.
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+origin(string) | *Required* <br/> Defines the set of external domains the app is allowed to communicate with.
+The default value shown above allows it to access any server.
+See the Domain [Whitelist Guide](../guide/appdev/whitelist/index.html) for details.
- Examples:
+Examples:
- ```xml
- <widget ...>
- <access origin="*"></content>
- </widget>
+```xml
+<widget ...>
+ <access origin="*"></content>
+</widget>
- <widget ...>
- <access origin="http://google.com"></content>
- </widget>
- ```
+<widget ...>
+ <access origin="http://google.com"></content>
+</widget>
+```
## allow-navigation
- Controls which URLs the WebView itself can be navigated to. Applies to top-level navigations only.
+Controls which URLs the WebView itself can be navigated to. Applies to top-level navigations only.
- Attributes(type) | Description
- ----------------- | ------------
- href(string) | *Required* <br/> Defines the set of external domains the WebView is allowed to navigate to.
- See the cordova-plugin-whitelist [cordova-plugin-whitelist][whitelist_navigation] for details.
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+href(string) | *Required* <br/> Defines the set of external domains the WebView is allowed to navigate to.
+See the cordova-plugin-whitelist [cordova-plugin-whitelist][whitelist_navigation] for details.
- Examples:
+Examples:
- ```xml
- <!-- Allow links to example.com -->
- <allow-navigation href="http://example.com/*" />
+```xml
+<!-- Allow links to example.com -->
+<allow-navigation href="http://example.com/*" />
- <!-- Wildcards are allowed for the protocol, as a prefix to the host, or as a suffix to the path -->
- <allow-navigation href="*://*.example.com/*" />
- ```
+<!-- Wildcards are allowed for the protocol, as a prefix to the host, or as a suffix to the path -->
+<allow-navigation href="*://*.example.com/*" />
+```
## allow-intent
- Controls which URLs the app is allowed to ask the system to open. By default, no external URLs are allowed.
+Controls which URLs the app is allowed to ask the system to open. By default, no external URLs are allowed.
- Attributes(type) | Description
- ----------------- | ------------
- href(string) | *Required* <br/> Defines which URLs the app is allowed to ask the system to open.
- See the cordova-plugin-whitelist [cordova-plugin-whitelist][whitelist_intent] for details.
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+href(string) | *Required* <br/> Defines which URLs the app is allowed to ask the system to open.
+See the cordova-plugin-whitelist [cordova-plugin-whitelist][whitelist_intent] for details.
- Examples:
+Examples:
- ```xml
- <allow-intent href="http://*/*" />
- <allow-intent href="https://*/*" />
- <allow-intent href="tel:*" />
- <allow-intent href="sms:*" />
- ```
+```xml
+<allow-intent href="http://*/*" />
+<allow-intent href="https://*/*" />
+<allow-intent href="tel:*" />
+<allow-intent href="sms:*" />
+```
## engine
- Specifies details about what platform to restore during a prepare.
+Specifies details about what platform to restore during a prepare.
- Attributes(type) | Description
- ----------------- | ------------
- name(string) | *Required* <br/> Name of the platform to be restored
- spec(string) | *Required* <br/> Details about the platform to be restored. This could be a ```major.minor.patch``` version number, a directory containing the platform or a url pointing to a git repository. This information will be used to retrieve the platform code to restore from NPM, a local directory or a git repository. See [Platform Spec][platform_spec] for further details.
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+name(string) | *Required* <br/> Name of the platform to be restored
+spec(string) | *Required* <br/> Details about the platform to be restored. This could be a ```major.minor.patch``` version number, a directory containing the platform or a url pointing to a git repository. This information will be used to retrieve the platform code to restore from NPM, a local directory or a git repository. See [Platform Spec][platform_spec] for further details.
- Examples:
+Examples:
- ```xml
- <engine name="android" spec="https://github.com/apache/cordova-android.git#5.1.1" />
- <engine name="ios" spec="^4.0.0" />
- ```
+```xml
+<engine name="android" spec="https://github.com/apache/cordova-android.git#5.1.1" />
+<engine name="ios" spec="^4.0.0" />
+```
## plugin
- Specifies details about what plugin to restore during a prepare.
+Specifies details about what plugin to restore during a prepare. This element
+is automatically added to a project's `config.xml` when a plugin is added using
+the `--save` flag. See the [CLI reference][plugin_cli] for more information on
+adding plugins.
- Attributes(type) | Description
- ----------------- | ------------
- name(string) | *Required* <br/> Name of the plugin to be restored
- spec(string) | *Required* <br/> Details about the plugin to be restored. This could be a ```major.minor.patch``` version number, a directory containing the plugin or a url pointing to a git repository. This information will be used to retrieve the plugin code to restore from NPM, a local directory or a git repository. See [Plugin Spec][plugin_spec] for further details.
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+name(string) | *Required* <br/> Name of the plugin to be restored
+spec(string) | *Required* <br/> Details about the plugin to be restored. This could be a ```major.minor.patch``` version number, a directory containing the plugin or a url pointing to a git repository. This information will be used to retrieve the plugin code to restore from NPM, a local directory or a git repository. See [Plugin Spec][plugin_spec] for further details.
- Examples:
+Examples:
- ```xml
- <plugin name="cordova-plugin-device" spec="^1.1.0" />
- <plugin name="cordova-plugin-device" spec="https://github.com/apache/cordova-plugin-device.git#1.0.0" />
- ```
+```xml
+<plugin name="cordova-plugin-device" spec="^1.1.0" />
+<plugin name="cordova-plugin-device" spec="https://github.com/apache/cordova-plugin-device.git#1.0.0" />
+```
+
+### variable
+Persists the value of a CLI variable to be used when restoring a plugin during a
+prepare. This element is added to `config.xml` when a plugin that uses CLI variables
+is added using the `--save` flag. See the [CLI reference][plugin_cli] for more
+information on adding plugins.
+
+Note that this value is only used when the plugin is restored to the project during a
+prepare, changing it will *not* change the value used by the plugin in the current
+project. In order for changes to this value to take effect, remove the plugin from the
+project and restore it by running `cordova prepare`. See the
+[preference element][plugin_preference] of `plugin.xml` for more details on CLI variables.
+
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+name(string) | *Required* <br/> Name of the CLI variable. Can only contain capital letters, digits, and underscores.
+value(string) | *Required* <br/> Value of the CLI variable to be used when restoring the parent plugin during a prepare.
+
+Examples:
+
+```xml
+<plugin name="cordova-plugin-device" spec="^1.1.0">
+ <variable name="MY_VARIABLE" value="my_variable_value" />
+</plugin>
+```
## preference
- Sets various options as pairs of name/value attributes. Each preference's name is case-insensitive. Many preferences are unique to specific platforms,
- and will be indicated as such.
-
- Attributes(type) | Description
- ----------------- | ------------
- AllowInlineMediaPlayback(boolean) | *Default: false* <br/> ==iOS== <br/> Set to true to allow HTML5 media playback to appear inline within the screen layout, using browser-supplied controls rather than native controls. For this to work, add the webkit-playsinline attribute to any ```<video>``` elements.
- AndroidLaunchMode(string) | *Default: singleTop* <br/> Allowed values: standard, singleTop, singleTask, singleInstance <br/> ==Android== <br/> Sets the Activity android:launchMode attribute. This changes what happens when the app is launched from app icon or intent and is already running.
- android-maxSdkVersion(integer) | *Default: Not Specified* <br/> ==Android== <br/> Sets the `maxSdkVersion` attribute of the `<uses-sdk>` tag in the project's `AndroidManifest.xml` (see [here][uses-sdk]).
- android-minSdkVersion(integer) | *Default: Dependent on cordova-android Version* <br/> ==Android== <br/> Sets the `minSdkVersion` attribute of the `<uses-sdk>` tag in the project's `AndroidManifest.xml` (see [here][uses-sdk]).
- android-targetSdkVersion(integer) | *Default: Dependent on cordova-android Version* <br/> ==Android== <br/> Sets the `targetSdkVersion` attribute of the `<uses-sdk>` tag in the project's `AndroidManifest.xml` (see [here][uses-sdk]).
- AppendUserAgent(string) | ==Android== ==iOS== <br/> If set, the value will append to the end of old UserAgent of webview. When using with OverrideUserAgent, this value will be ignored.
- BackgroundColor(string) | ==Android== ==BlackBerry== ==Windows== <br/> Sets the app's background color. Supports a four-byte hex value, with the first byte representing the alpha channel, and standard RGB values for the following three bytes. <br/> For Windows, the alpha channel is ignored. <br/> __Note__: `transparent` value will set the application tile background to the accent color on Windows.
- BackupWebStorage(string) | *Default: cloud* <br/> Allowed values: none, local, cloud. <br/> ==iOS== <br/> Set to cloud to allow web storage data to backup via iCloud. Set to local to allow only local backups via iTunes sync. Set to none prevent web storage backups.
- ChildBrowser(string) | *Default: enable* <br/> ==BlackBerry== <br/> Disables child browser windows. By default, apps launch a secondary browser window to display resources accessed via window.open() or by specifying a _blank anchor target. Specify disable to override this default behavior.
- CordovaWebViewEngine(string) | *Default: CDVUIWebViewEngine* <br/> ==iOS== <br/> This sets the WebView engine plugin to be used to render the host app. The plugin must conform to the CDVWebViewEngineProtocol protocol. The 'value' here should match the 'feature' name of the WebView engine plugin that is installed. This preference usually would be set by the WebView engine plugin that is installed, automatically.
- DefaultVolumeStream(string) | *Default: default* <br/> ==Android==<br/> Added in cordova-android 3.7.0, This preference sets which volume the hardware volume buttons link to. By default this is "call" for phones and "media" for tablets. Set this to "media" to have your app's volume buttons always change the media volume. Note that when using Cordova's media plugin, the volume buttons will dynamically change to controlling the media volume when any Media objects are active.
- DisallowOverscroll(boolean) | *Default: false* <br/> ==iOS== ==Android== <br/> Set to **true** if you don't want the interface to display any feedback when users scroll past the beginning or end of content. On iOS, overscroll gestures cause content to bounce back to its original position. on Android, they produce a more subtle glowing effect along the top or bottom edge of the content. <br/>
- EnableViewportScale(boolean) | *Default: false* <br/> ==iOS== <br/> Set to true to allow a viewport meta tag to either disable or restrict the range of user scaling, which is enabled by default. Place a viewport such as the following in the HTML to disable scaling and fit content flexibly within the rendering WebView: <br/> ```<meta name='viewport' content='width=device-width, initial-scale=1, user-scalable=no' />```
- EnableWebGL(boolean) | *Default: false* <br/> ==OS X **4.0.0**== <br/> Set to true to enable WebGL on the web view.
- ErrorUrl(URL) | *Default: null* <br/> ==Android== <br/> If set, will display the referenced page upon an error in the application instead of a dialog with the title "Application Error".
- ErrorUrl(string) | ==iOS== <br/> If set, will display the referenced local page upon an error in the application.
- FullScreen(boolean) | *Default: false* <br/> ==Android== <br/> Allows you to hide the status bar at the top of the screen. <br/> __Note__: Recommended platform-agnostic way to achieve this is to use the [StatusBar plugin][statusbar_plugin].
- GapBetweenPages(float) | *Default: 0* <br/> ==iOS== <br/> The size of the gap, in points, between pages.
- HideKeyboardFormAccessoryBar(boolean) | *Default: false* <br/> ==BlackBerry== <br/> Set to true to hide the additional toolbar that appears above the keyboard, helping users navigate from one form input to another.
- HideMousePointer(integer) | *Default: -1* <br/> ==OS X **4.0.0**== <br/> Sets the timeout for hiding the mouse pointer. Set to 0 for immediate, set to -1 for never.
- InAppBrowserStorageEnabled (boolean) | *Default: true* <br/> ==Android== <br/> Controls whether pages opened within an InAppBrowser can access the same localStorage and WebSQL storage as pages opened with the default browser.
- KeepRunning(boolean) | *Default: true* <br/> ==Android== <br/> Determines whether the application stays running in the background even after a [pause](../../../cordova/events/events.pause.html) event fires. Setting this to false does not kill the app after a [pause](../../../cordova/events/events.pause.html) event, but simply halts execution of code within the cordova webview while the app is in the background.
- KeyboardDisplayRequiresUserAction(boolean) | *Default: true* <br/> ==iOS== <br/> Set to false to allow the keyboard to appear when calling focus() on form inputs.
- LoadUrlTimeoutValue(number in milliseconds) | *Default: 20000, 20 seconds* <br/> ==Android== <br/> When loading a page, the amount of time to wait before throwing a timeout error.
- LoadingDialog(string) | *Default: null* <br/> ==Android== <br/> If set, displays a dialog with the specified title and message, and a spinner, when loading the first page of an application. The title and message are separated by a comma in this value string, and that comma is removed before the dialog is displayed.
- 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 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. <br/> **Note:** These preferences are only set in the appxmanifest files of the desired target-platform and not in the jsproj files.
- 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'.
- OSXLocalStoragePath(string) | ==OS X **4.0.0**== <br/> *Default: `~/Library/Application Support/{bundle.id}`* <br/> Sets the directory for the local storage path.
- 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.
- PaginationBreakingMode(string) | *Default: page* <br/> Allowed values: page, column <br/> ==iOS== <br/> Valid values are page and column.The manner in which column- or page-breaking occurs. This property determines whether certain CSS properties regarding column- and page-breaking are honored or ignored. When this property is set to column, the content respects the CSS properties related to column-breaking in place of page-breaking.
- PaginationMode(string) | *Default: unpaginated* <br/> Allowed values: unpaginated, leftToRight, topToBottom, bottomToTop, rightToLeft <br/> ==iOS== <br/> This property determines whether content in the web view is broken up into pages that fill the view one screen at a time,or shown as one long scrolling view. If set to a paginated form, this property toggles a paginated layout on the content, causing the web view to use the values of PageLength and GapBetweenPages to relayout its content.
- PopupBlocker(string) | *Default: enable* <br/> ==BlackBerry== <br/> Enables the popup blocker, which prevents calls to window.open(). By default, popups display in a child browser window. Setting the preference to enable prevents it from displaying at all.
- SetFullscreen(boolean) | *Default: false* <br/> ==Android== <br/> Same as the Fullscreen parameter in the global configuration of this xml file. This Android-specific element is deprecated in favor of the global Fullscreen element, and will be removed in a future version.
- ShowTitle(boolean) | *Default: false* <br/> ==Android== <br/> Show the title at the top of the screen.
- SplashScreenBackgroundColor | *Default: #464646* <br/> ==Windows== <br/> Sets the splashscreen background color. Supports a CSS color name or a four-byte hex value, with the first byte representing the alpha channel, and standard RGB values for the following three bytes. <br/> The alpha channel is ignored although `transparent` value will cause black/white background color in case of Dark/Light theme accordingly.
- Suppresses3DTouchGesture(boolean) | *Default: false* <br/> ==iOS== <br/> Set to true to avoid 3D Touch capable iOS devices rendering a magnifying glass widget when the user applies force while longpressing the webview. Test your app thoroughly since this disables onclick handlers, but plays nice with ontouchend. If this setting is true, SuppressesLongPressGesture will effectively be true as well.
- SuppressesIncrementalRendering(boolean) | *Default: false* <br/> ==iOS== <br/> Set to true to wait until all content has been received before it renders to the screen.
- SuppressesLongPressGesture(boolean) | *Default: false* <br/> ==iOS== <br/> Set to true to avoid iOS9+ rendering a magnifying glass widget when the user longpresses the webview. Test your app thoroughly since this may interfere with text selection capabilities.
- TopActivityIndicator(string) | *Default: gray* <br/> Allowed values: whiteLarge, white, gray. <br/> ==iOS== <br/> <br/> Controls the appearance of the small spinning icon in the status bar that indicates significant processor activity.
- uap-target-min-version(string) | ==Windows== <br/> This property sets the MinTargetVersion for the Windows UAP. If not specified, this is set to the initial release version 10.0.10240.0 <br/> **Note:** This preference is set in the jsproj file and not in the appxmanifest file. So users with OS version lower than this value would not be able to run the app.
- UIWebViewDecelerationSpeed(string) | *Default: normal* <br/> Allowed values: normal, fast <br/> ==iOS== <br/> This property controls the deceleration speed of momentum scrolling. normal is the default speed for most native apps, and fast is the default for Mobile Safari.
- WebSecurity(string) | *Default: enable* <br/> ==BlackBerry== <br/> Set to disable to override web security settings, allowing access to remote content from unknown sources. This preference is intended as a development convenience only, so remove it before packaging the app for distribution. For the released app, all URIs should be known and whitelisted using the <access> element, described in the Domain Whitelist Guide.
- WindowSize(string) | *Default: auto* <br/> ==OS X **4.0.0**== <br/> Sets the size of the application window. <br/> Accepts the format `WxH` for a specific width and height or the special values `auto` and `fullscreen`. The latter will open a borderless window spanning the entire desktop area. Please note, that this is different from the _normal_ OS X fullscreen mode, which would never span multiple displays. <br/> **Note**: The global cordova `fullscreen` preference has no effect in OS X.
- 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
- WindowsStoreDisplayName(string) | ==Windows== <br/> A friendly name for the publisher that can be displayed to users.
- WindowsStoreIdentityName(string) | ==Windows== <br/> Identity name used for Windows store. The identity defines a globally unique identifier for a package. A package identity is represented as a tuple of attributes of the package. See the [identity page on the package manifest schema reference](https://msdn.microsoft.com/en-us/library/windows/apps/br211441.aspx) for further details.
- WindowsStorePublisherName(string) | ==Windows== <br/> Publisher Display Name.
- WindowsToastCapable(boolean) | *Default: false* <br/> ==Windows== <br/> A value of ```true``` indicates that the app is allowed to provide 'toast notifications'.
- deployment-target(string) | ==iOS== <br/> This sets the IPHONEOS_DEPLOYMENT_TARGET in the build, which ultimately tranlsates to the MinimumOSVersion in the ipa. For more details please refer to Apple's documentation on Deployment Target Settings
- 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'.
-
- Examples:
-
- ```xml
- <preference name="DisallowOverscroll" value="true"/>
- <preference name="Fullscreen" value="true" />
- <preference name="BackgroundColor" value="0xff0000ff"/>
- <preference name="HideKeyboardFormAccessoryBar" value="true"/>
- <preference name="Orientation" value="landscape" />
-
- <!-- iOS only preferences -->
- <preference name="EnableViewportScale" value="true"/>
- <preference name="MediaPlaybackAllowsAirPlay" value="false"/>
- <preference name="MediaPlaybackRequiresUserAction" value="true"/>
- <preference name="AllowInlineMediaPlayback" value="true"/>
- <preference name="BackupWebStorage" value="local"/>
- <preference name="TopActivityIndicator" value="white"/>
- <preference name="SuppressesIncrementalRendering" value="true"/>
- <preference name="GapBetweenPages" value="0"/>
- <preference name="PageLength" value="0"/>
- <preference name="PaginationBreakingMode" value="page"/>
- <preference name="PaginationMode" value="unpaginated"/>
- <preference name="UIWebViewDecelerationSpeed" value="fast" />
- <preference name="ErrorUrl" value="myErrorPage.html"/>
- <preference name="OverrideUserAgent" value="Mozilla/5.0 My Browser" />
- <preference name="AppendUserAgent" value="My Browser" />
- <preference name="target-device" value="universal" />
- <preference name="deployment-target" value="7.0" />
- <preference name="CordovaWebViewEngine" value="CDVUIWebViewEngine" />
- <preference name="SuppressesLongPressGesture" value="true" />
- <preference name="Suppresses3DTouchGesture" value="true" />
-
- <!-- Android only preferences -->
- <preference name="KeepRunning" value="false"/>
- <preference name="LoadUrlTimeoutValue" value="10000"/>
- <preference name="InAppBrowserStorageEnabled" value="true"/>
- <preference name="LoadingDialog" value="My Title,My Message"/>
- <preference name="ErrorUrl" value="myErrorPage.html"/>
- <preference name="ShowTitle" value="true"/>
- <preference name="LogLevel" value="VERBOSE"/>
- <preference name="AndroidLaunchMode" value="singleTop"/>
- <preference name="DefaultVolumeStream" value="call" />
- <preference name="OverrideUserAgent" value="Mozilla/5.0 My Browser" />
- <preference name="AppendUserAgent" value="My Browser" />
-
- <!-- Windows only preferences -->
- <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" />
- <preference name="WindowsStoreIdentityName" value="Cordova.Example.ApplicationDataSample" />
- <preference name="WindowsStorePublisherName" value="CN=Contoso Corp, O=Contoso Corp, L=Redmond, S=Washington, C=US" />
- <preference name="WindowsToastCapable" value="true" />
- <preference name="uap-target-min-version" value="10.0.10586.0" />
-
- <!-- BlackBerry only preferences -->
- <preference name="ChildBrowser" value="disable"/>
- <preference name="PopupBlocker" value="enable"/>
- <preference name="WebSecurity" value="disable"/>
-
- <!-- OS X only preferences -->
- <preference name="HideMousePointer" value="5"/>
- <preference name="OSXLocalStoragePath" value="~/.myapp/database"/>
- <preference name="WindowSize" value="800x400"/>
- <preference name="EnableWebGL" value="true"/>
- ```
+Sets various options as pairs of name/value attributes. Each preference's name is case-insensitive. Many preferences are unique to specific platforms,
+and will be indicated as such.
+
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+AllowInlineMediaPlayback(boolean) <br/> ==iOS== | *Default: false* <br/> Set to true to allow HTML5 media playback to appear inline within the screen layout, using browser-supplied controls rather than native controls. For this to work, add the webkit-playsinline attribute to any ```<video>``` elements.
+AndroidLaunchMode(string) <br/> ==Android== | *Default: singleTop* <br/> Allowed values: standard, singleTop, singleTask, singleInstance <br/> Sets the Activity android:launchMode attribute. This changes what happens when the app is launched from app icon or intent and is already running.
+android-maxSdkVersion(integer) <br/> ==Android== | *Default: Not Specified* <br/> Sets the `maxSdkVersion` attribute of the `<uses-sdk>` tag in the project's `AndroidManifest.xml` (see [here][uses-sdk]).
+android-minSdkVersion(integer) <br/> ==Android== | *Default: Dependent on cordova-android Version* <br/> Sets the `minSdkVersion` attribute of the `<uses-sdk>` tag in the project's `AndroidManifest.xml` (see [here][uses-sdk]).
+android-targetSdkVersion(integer) <br/> ==Android== | *Default: Dependent on cordova-android Version* <br/> Sets the `targetSdkVersion` attribute of the `<uses-sdk>` tag in the project's `AndroidManifest.xml` (see [here][uses-sdk]).
+AppendUserAgent(string) <br/> ==Android== ==iOS== | If set, the value will append to the end of old UserAgent of webview. When using with OverrideUserAgent, this value will be ignored.
+BackgroundColor(string) <br/> ==Android== ==BlackBerry== ==Windows== | Sets the app's background color. Supports a four-byte hex value, with the first byte representing the alpha channel, and standard RGB values for the following three bytes. <br/> For Windows, the alpha channel is ignored. <br/> __Note__: `transparent` value will set the application tile background to the accent color on Windows.
+BackupWebStorage(string) <br/> ==iOS== | *Default: cloud* <br/> Allowed values: none, local, cloud. <br/> Set to cloud to allow web storage data to backup via iCloud. Set to local to allow only local backups via iTunes sync. Set to none prevent web storage backups.
+ChildBrowser(string) <br/> ==BlackBerry== | *Default: enable* <br/> Disables child browser windows. By default, apps launch a secondary browser window to display resources accessed via window.open() or by specifying a _blank anchor target. Specify disable to override this default behavior.
+CordovaWebViewEngine(string) <br/> ==iOS== | *Default: CDVUIWebViewEngine* <br/> This sets the WebView engine plugin to be used to render the host app. The plugin must conform to the CDVWebViewEngineProtocol protocol. The 'value' here should match the 'feature' name of the WebView engine plugin that is installed. This preference usually would be set by the WebView engine plugin that is installed, automatically.
+DefaultVolumeStream(string) <br/> ==Android== | *Default: default* <br/> Added in cordova-android 3.7.0, This preference sets which volume the hardware volume buttons link to. By default this is "call" for phones and "media" for tablets. Set this to "media" to have your app's volume buttons always change the media volume. Note that when using Cordova's media plugin, the volume buttons will dynamically change to controlling the media volume when any Media objects are active.
+DisallowOverscroll(boolean) <br/> ==iOS== ==Android== | *Default: false* <br/> Set to **true** if you don't want the interface to display any feedback when users scroll past the beginning or end of content. On iOS, overscroll gestures cause content to bounce back to its original position. on Android, they produce a more subtle glowing effect along the top or bottom edge of the content. <br/>
+EnableViewportScale(boolean) <br/> ==iOS== | *Default: false* <br/> Set to true to allow a viewport meta tag to either disable or restrict the range of user scaling, which is enabled by default. Place a viewport such as the following in the HTML to disable scaling and fit content flexibly within the rendering WebView: <br/> ```<meta name='viewport' content='width=device-width, initial-scale=1, user-scalable=no' />```
+EnableWebGL(boolean) <br/> ==OS X== | *Default: false* <br/> **(OS X 4.0.0+)** Set to true to enable WebGL on the web view.
+ErrorUrl(URL) <br/> ==Android== | *Default: null* <br/> If set, will display the referenced page upon an error in the application instead of a dialog with the title "Application Error".
+ErrorUrl(string) <br/> ==iOS== | If set, will display the referenced local page upon an error in the application.
+FullScreen(boolean) <br/> ==Android== | *Default: false* <br/> Allows you to hide the status bar at the top of the screen. <br/> __Note__: Recommended platform-agnostic way to achieve this is to use the [StatusBar plugin][statusbar_plugin].
+GapBetweenPages(float) <br/> ==iOS== | *Default: 0* <br/> The size of the gap, in points, between pages.
+HideKeyboardFormAccessoryBar(boolean) <br/> ==BlackBerry== | *Default: false* <br/> Set to true to hide the additional toolbar that appears above the keyboard, helping users navigate from one form input to another.
+HideMousePointer(integer) <br/> ==OS X== | *Default: -1* <br/> **(OS X 4.0.0+)** Sets the timeout for hiding the mouse pointer. Set to 0 for immediate, set to -1 for never.
+InAppBrowserStorageEnabled (boolean) <br/> ==Android== | *Default: true* <br/> Controls whether pages opened within an InAppBrowser can access the same localStorage and WebSQL storage as pages opened with the default browser.
+KeepRunning(boolean) <br/> ==Android== | *Default: true* <br/> Determines whether the application stays running in the background even after a [pause](../../../cordova/events/events.pause.html) event fires. Setting this to false does not kill the app after a [pause](../../../cordova/events/events.pause.html) event, but simply halts execution of code within the cordova webview while the app is in the background.
+KeyboardDisplayRequiresUserAction(boolean) <br/> ==iOS== | *Default: true* <br/> Set to false to allow the keyboard to appear when calling focus() on form inputs.
+LoadUrlTimeoutValue(number in milliseconds) <br/> ==Android== | *Default: 20000, 20 seconds* <br/> When loading a page, the amount of time to wait before throwing a timeout error.
+LoadingDialog(string) <br/> ==Android== | *Default: null* <br/> If set, displays a dialog with the specified title and message, and a spinner, when loading the first page of an application. The title and message are separated by a comma in this value string, and that comma is removed before the dialog is displayed.
+LogLevel(string) <br/> ==Android== | *Default: ERROR* <br/> Allowed values: ERROR, WARN, INFO, DEBUG, VERBOSE <br/> Sets the minimum log level through which log messages from your application will be filtered.
+MediaPlaybackAllowsAirPlay(boolean) <br/> ==iOS== | *Default: true* <br/> Set to false to prevent Air Play from being used in this view. Available in default UIWebView and WKWebView.
+MediaPlaybackRequiresUserAction(boolean) <br/> ==iOS== | *Default: false* <br/> Set to true to prevent HTML5 videos or audios from playing automatically with the autoplay attribute or via JavaScript.
+Min/Max Version(Regex) <br/> ==Windows== | 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 highes
t-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. <br/> **Note:** These preferences are only set in the appxmanifest files of the desired target-platform and not in the jsproj files.
+Orientation(string) | *Default: default* <br/> Allowed values: default, landscape, portrait <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'.
+OSXLocalStoragePath(string) <br/> ==OS X== | *Default: `~/Library/Application Support/{bundle.id}`* <br/> **(OS X 4.0.0+)** Sets the directory for the local storage path.
+OverrideUserAgent(string) <br/> ==Android== | 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) <br/> ==iOS== | *Default: 0* <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.
+PaginationBreakingMode(string) <br/> ==iOS== | *Default: page* <br/> Allowed values: page, column <br/> Valid values are page and column.The manner in which column- or page-breaking occurs. This property determines whether certain CSS properties regarding column- and page-breaking are honored or ignored. When this property is set to column, the content respects the CSS properties related to column-breaking in place of page-breaking.
+PaginationMode(string) <br/> ==iOS== | *Default: unpaginated* <br/> Allowed values: unpaginated, leftToRight, topToBottom, bottomToTop, rightToLeft <br/> This property determines whether content in the web view is broken up into pages that fill the view one screen at a time,or shown as one long scrolling view. If set to a paginated form, this property toggles a paginated layout on the content, causing the web view to use the values of PageLength and GapBetweenPages to relayout its content.
+PopupBlocker(string) <br/> ==BlackBerry== | *Default: enable* <br/> Enables the popup blocker, which prevents calls to window.open(). By default, popups display in a child browser window. Setting the preference to enable prevents it from displaying at all.
+SetFullscreen(boolean) <br/> ==Android== | *Default: false* <br/> Same as the Fullscreen parameter in the global configuration of this xml file. This Android-specific element is deprecated in favor of the global Fullscreen element, and will be removed in a future version.
+ShowTitle(boolean) <br/> ==Android== | *Default: false* <br/> Show the title at the top of the screen.
+SplashScreenBackgroundColor <br/> ==Windows== | *Default: #464646* <br/> Sets the splashscreen background color. Supports a CSS color name or a four-byte hex value, with the first byte representing the alpha channel, and standard RGB values for the following three bytes. <br/> The alpha channel is ignored although `transparent` value will cause black/white background color in case of Dark/Light theme accordingly.
+Suppresses3DTouchGesture(boolean) <br/> ==iOS== | *Default: false* <br/> Set to true to avoid 3D Touch capable iOS devices rendering a magnifying glass widget when the user applies force while longpressing the webview. Test your app thoroughly since this disables onclick handlers, but plays nice with ontouchend. If this setting is true, SuppressesLongPressGesture will effectively be true as well.
+SuppressesIncrementalRendering(boolean) <br/> ==iOS== | *Default: false* <br/> Set to true to wait until all content has been received before it renders to the screen.
+SuppressesLongPressGesture(boolean) <br/> ==iOS== | *Default: false* <br/> Set to true to avoid iOS9+ rendering a magnifying glass widget when the user longpresses the webview. Test your app thoroughly since this may interfere with text selection capabilities.
+TopActivityIndicator(string) <br/> ==iOS== | *Default: gray* <br/> Allowed values: whiteLarge, white, gray. <br/> <br/> Controls the appearance of the small spinning icon in the status bar that indicates significant processor activity.
+uap-target-min-version(string) <br/> ==Windows== | This property sets the MinTargetVersion for the Windows UAP. If not specified, this is set to the initial release version 10.0.10240.0 <br/> **Note:** This preference is set in the jsproj file and not in the appxmanifest file. So users with OS version lower than this value would not be able to run the app.
+UIWebViewDecelerationSpeed(string) <br/> ==iOS== | *Default: normal* <br/> Allowed values: normal, fast <br/> This property controls the deceleration speed of momentum scrolling. normal is the default speed for most native apps, and fast is the default for Mobile Safari.
+WebSecurity(string) <br/> ==BlackBerry== | *Default: enable* <br/> Set to disable to override web security settings, allowing access to remote content from unknown sources. This preference is intended as a development convenience only, so remove it before packaging the app for distribution. For the released app, all URIs should be known and whitelisted using the <access> element, described in the Domain Whitelist Guide.
+WindowSize(string) <br/> ==OS X== | *Default: auto* <br/> **(OS X 4.0.0+)** Sets the size of the application window. <br/> Accepts the format `WxH` for a specific width and height or the special values `auto` and `fullscreen`. The latter will open a borderless window spanning the entire desktop area. Please note, that this is different from the _normal_ OS X fullscreen mode, which would never span multiple displays. <br/> **Note**: The global cordova `fullscreen` preference has no effect in OS X.
+WindowsDefaultUriPrefix(string) <br/> ==Windows== | 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
+WindowsStoreDisplayName(string) <br/> ==Windows== | A friendly name for the publisher that can be displayed to users.
+WindowsStoreIdentityName(string) <br/> ==Windows== | Identity name used for Windows store. The identity defines a globally unique identifier for a package. A package identity is represented as a tuple of attributes of the package. See the [identity page on the package manifest schema reference](https://msdn.microsoft.com/en-us/library/windows/apps/br211441.aspx) for further details.
+WindowsStorePublisherName(string) <br/> ==Windows== | Publisher Display Name.
+WindowsToastCapable(boolean) <br/> ==Windows== | *Default: false* <br/> A value of ```true``` indicates that the app is allowed to provide 'toast notifications'.
+deployment-target(string) <br/> ==iOS== | This sets the IPHONEOS_DEPLOYMENT_TARGET in the build, which ultimately tranlsates to the MinimumOSVersion in the ipa. For more details please refer to Apple's documentation on Deployment Target Settings
+target-device(string) <br/> ==iOS== | *Default: universal* <br/> Allowed values: handset, tablet, universal <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) <br/> ==Windows== | 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) <br/> ==Windows== | 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'.
+
+Examples:
+
+```xml
+<preference name="DisallowOverscroll" value="true"/>
+<preference name="Fullscreen" value="true" />
+<preference name="BackgroundColor" value="0xff0000ff"/>
+<preference name="HideKeyboardFormAccessoryBar" value="true"/>
+<preference name="Orientation" value="landscape" />
+
+<!-- iOS only preferences -->
+<preference name="EnableViewportScale" value="true"/>
+<preference name="MediaPlaybackAllowsAirPlay" value="false"/>
+<preference name="MediaPlaybackRequiresUserAction" value="true"/>
+<preference name="AllowInlineMediaPlayback" value="true"/>
+<preference name="BackupWebStorage" value="local"/>
+<preference name="TopActivityIndicator" value="white"/>
+<preference name="SuppressesIncrementalRendering" value="true"/>
+<preference name="GapBetweenPages" value="0"/>
+<preference name="PageLength" value="0"/>
+<preference name="PaginationBreakingMode" value="page"/>
+<preference name="PaginationMode" value="unpaginated"/>
+<preference name="UIWebViewDecelerationSpeed" value="fast" />
+<preference name="ErrorUrl" value="myErrorPage.html"/>
+<preference name="OverrideUserAgent" value="Mozilla/5.0 My Browser" />
+<preference name="AppendUserAgent" value="My Browser" />
+<preference name="target-device" value="universal" />
+<preference name="deployment-target" value="7.0" />
+<preference name="CordovaWebViewEngine" value="CDVUIWebViewEngine" />
+<preference name="SuppressesLongPressGesture" value="true" />
+<preference name="Suppresses3DTouchGesture" value="true" />
+
+<!-- Android only preferences -->
+<preference name="KeepRunning" value="false"/>
+<preference name="LoadUrlTimeoutValue" value="10000"/>
+<preference name="InAppBrowserStorageEnabled" value="true"/>
+<preference name="LoadingDialog" value="My Title,My Message"/>
+<preference name="ErrorUrl" value="myErrorPage.html"/>
+<preference name="ShowTitle" value="true"/>
+<preference name="LogLevel" value="VERBOSE"/>
+<preference name="AndroidLaunchMode" value="singleTop"/>
+<preference name="DefaultVolumeStream" value="call" />
+<preference name="OverrideUserAgent" value="Mozilla/5.0 My Browser" />
+<preference name="AppendUserAgent" value="My Browser" />
+
+<!-- Windows only preferences -->
+<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" />
+<preference name="WindowsStoreIdentityName" value="Cordova.Example.ApplicationDataSample" />
+<preference name="WindowsStorePublisherName" value="CN=Contoso Corp, O=Contoso Corp, L=Redmond, S=Washington, C=US" />
+<preference name="WindowsToastCapable" value="true" />
+<preference name="uap-target-min-version" value="10.0.10586.0" />
+
+<!-- BlackBerry only preferences -->
+<preference name="ChildBrowser" value="disable"/>
+<preference name="PopupBlocker" value="enable"/>
+<preference name="WebSecurity" value="disable"/>
+
+<!-- OS X only preferences -->
+<preference name="HideMousePointer" value="5"/>
+<preference name="OSXLocalStoragePath" value="~/.myapp/database"/>
+<preference name="WindowSize" value="800x400"/>
+<preference name="EnableWebGL" value="true"/>
+```
## feature
- If you use the CLI to build applications, you use the plugin command to enable device APIs. This does not modify the top-level config.xml file, so the <feature> element does not apply to your workflow. If you work directly in an SDK and using the platform-specific config.xml file as source, you use the <feature> tag to enable device-level APIs and external plugins. They often appear with custom values in platform-specific config.xml files. See the API Reference for details on how to specify each feature. See
- the [Plugin Development Guide](../guide/hybrid/plugins/index.html) for more information on plugins.
- NOTE: Most of the time, you do NOT want to set this directly.
+If you use the CLI to build applications, you use the plugin command to enable device APIs. This does not modify the top-level config.xml file, so the <feature> element does not apply to your workflow. If you work directly in an SDK and using the platform-specific config.xml file as source, you use the <feature> tag to enable device-level APIs and external plugins. They often appear with custom values in platform-specific config.xml files. See the API Reference for details on how to specify each feature. See
+the [Plugin Development Guide](../guide/hybrid/plugins/index.html) for more information on plugins.
+NOTE: Most of the time, you do NOT want to set this directly.
- Attributes(type) | Description
- ----------------- | ------------
- name(string) | *Required* <br/> The name of the plugin to enable.
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+name(string) | *Required* <br/> The name of the plugin to enable.
### param
- Used to specify what certain plugin parameters such as: what package to retrieve the plugin code from, and whether the plugin code is to be initialized during the Webview's initialization.
+Used to specify what certain plugin parameters such as: what package to retrieve the plugin code from, and whether the plugin code is to be initialized during the Webview's initialization.
- Attributes(type) | Description
- ----------------- | ------------
- name(string) | *Required* <br/> Allowed values: android-package, ios-package, osx-package, onload. <br/> ==iOS== ==OS X== ==Android== <br/> 'ios-package', 'osx-package' and 'android-package' are used to specify the name of the package (as specified by the 'value' attribute) to be used to initialize the plugin code, while 'onload' is used to specify whether the corresponding plugin (as specified in the 'value' attribute) is to be instantiated when the controller is initialized.
- value(string or boolean) | *Required* <br/> ==iOS== ==OS X== ==Android== <br/> Specifies the name of the package to be used to initialize the plugin code (when the 'name' attribute is android-package, ios-package or osx-package), specifies the name of the plugin to be loaded during controller initialization (when 'name' attribute is set to 'onload').
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+name(string) <br/> ==iOS== ==OS X== ==Android== | *Required* <br/> Allowed values: android-package, ios-package, osx-package, onload. <br/> 'ios-package', 'osx-package' and 'android-package' are used to specify the name of the package (as specified by the 'value' attribute) to be used to initialize the plugin code, while 'onload' is used to specify whether the corresponding plugin (as specified in the 'value' attribute) is to be instantiated when the controller is initialized.
+value(string or boolean) <br/> ==iOS== ==OS X== ==Android== | *Required* <br/> Specifies the name of the package to be used to initialize the plugin code (when the 'name' attribute is android-package, ios-package or osx-package), specifies the name of the plugin to be loaded during controller initialization (when 'name' attribute is set to 'onload').
- Examples:
+Examples:
- ```xml
- <!-- Here is how to specify the Device API for Android projects -->
- <feature name="Device">
- <param name="android-package" value="org.apache.cordova.device.Device" />
- </feature>
+```xml
+<!-- Here is how to specify the Device API for Android projects -->
+<feature name="Device">
+ <param name="android-package" value="org.apache.cordova.device.Device" />
+</feature>
- <!-- Here's how the element appears for iOS projects -->
- <feature name="Device">
- <param name="ios-package" value="CDVDevice" />
- <param name="onload" value="true" />
- </feature>
+<!-- Here's how the element appears for iOS projects -->
+<feature name="Device">
+ <param name="ios-package" value="CDVDevice" />
+ <param name="onload" value="true" />
+</feature>
- <!-- Here's how the element appears for OS X projects -->
- <feature name="Device">
- <param name="osx-package" value="CDVDevice" />
- <param name="onload" value="true" />
- </feature>
- ```
+<!-- Here's how the element appears for OS X projects -->
+<feature name="Device">
+ <param name="osx-package" value="CDVDevice" />
+ <param name="onload" value="true" />
+</feature>
+```
## platform
- When using the CLI to build applications, it is sometimes necessary to specify preferences or other elements specific to a particular platform. Use the <platform> element to specify configuration that should only appear in a single platform-specific config.xml file.
+When using the CLI to build applications, it is sometimes necessary to specify preferences or other elements specific to a particular platform. Use the <platform> element to specify configuration that should only appear in a single platform-specific config.xml file.
- Attributes(type) | Description
- ----------------- | ------------
- name(string) | *Required* <br/> The platform whose preferences are being defined.
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+name(string) | *Required* <br/> The platform whose preferences are being defined.
- Examples:
+Examples:
- ```xml
- <platform name="android">
- <preference name="Fullscreen" value="true" />
- </platform>
- ```
+```xml
+<platform name="android">
+ <preference name="Fullscreen" value="true" />
+</platform>
+```
## hook
- Represents your custom script which will be called by Cordova when
- certain action occurs (for example, after plugin is added or platform
- prepare logic is invoked). This is useful when you need to extend
- default Cordova functionality. See [Hooks Guide](../guide/appdev/hooks/index.html) for more information.
+Represents your custom script which will be called by Cordova when
+certain action occurs (for example, after plugin is added or platform
+prepare logic is invoked). This is useful when you need to extend
+default Cordova functionality. See [Hooks Guide](../guide/appdev/hooks/index.html) for more information.
- Attributes(type) | Description
- ----------------- | ------------
- type(string) | *Required* <br/> Specifies the action during which the custom script is to be called.
- src(string) | *Required* <br/> Specifies the location of the script to be called when a specific action occurs.
+Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+----------------- | ------------
+type(string) | *Required* <br/> Specifies the action during which the custom script is to be called.
+src(string) | *Required* <br/> Specifies the location of the script to be called when a specific action occurs.
- Examples:
+Examples:
- ```xml
- <hook type="after_plugin_install" src="scripts/afterPluginInstall.js" />
- ```
+```xml
+<hook type="after_plugin_install" src="scripts/afterPluginInstall.js" />
+```
# Sample config.xml
- Below is a sample config.xml file:
-
- ```xml
- <?xml version='1.0' encoding='utf-8'?>
- <widget id="io.cordova.hellocordova" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
- <name>HelloCordova</name>
- <description>
- A sample Apache Cordova application that responds to the deviceready event.
- </description>
- <author email="dev@cordova.apache.org" href="http://cordova.io">
- Apache Cordova Team
- </author>
- <content src="index.html" />
- <plugin name="cordova-plugin-whitelist" spec="1" />
- <access origin="*" />
- <allow-intent href="http://*/*" />
- <allow-intent href="https://*/*" />
- <allow-intent href="tel:*" />
- <allow-intent href="sms:*" />
- <allow-intent href="mailto:*" />
- <allow-intent href="geo:*" />
- <platform name="android">
- <allow-intent href="market:*" />
- </platform>
- <platform name="ios">
- <allow-intent href="itms:*" />
- <allow-intent href="itms-apps:*" />
- </platform>
- </widget>
- ```
+Below is a sample config.xml file:
+
+```xml
+<?xml version='1.0' encoding='utf-8'?>
+<widget id="io.cordova.hellocordova" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
+ <name>HelloCordova</name>
+ <description>
+ A sample Apache Cordova application that responds to the deviceready event.
+ </description>
+ <author email="dev@cordova.apache.org" href="http://cordova.io">
+ Apache Cordova Team
+ </author>
+ <content src="index.html" />
+ <plugin name="cordova-plugin-whitelist" spec="1" />
+ <access origin="*" />
+ <allow-intent href="http://*/*" />
+ <allow-intent href="https://*/*" />
+ <allow-intent href="tel:*" />
+ <allow-intent href="sms:*" />
+ <allow-intent href="mailto:*" />
+ <allow-intent href="geo:*" />
+ <platform name="android">
+ <allow-intent href="market:*" />
+ </platform>
+ <platform name="ios">
+ <allow-intent href="itms:*" />
+ <allow-intent href="itms-apps:*" />
+ </platform>
+</widget>
+```
[uses-sdk]: http://developer.android.com/guide/topics/manifest/uses-sdk-element.html
[platform_spec]: ../reference/cordova-cli/index.html#platform-spec
+[plugin_preference]: ../plugin_ref/spec.html#preference
[plugin_spec]: ../reference/cordova-cli/index.html#plugin-spec
+[plugin_cli]: ../reference/cordova-cli/index.html#cordova-plugin-command
[whitelist_navigation]: ../reference/cordova-plugin-whitelist/index.html#navigation-whitelist
[whitelist_intent]: ../reference/cordova-plugin-whitelist/index.html#intent-whitelist
[statusbar_plugin]: ../reference/cordova-plugin-statusbar/
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/cordova/events/events.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/cordova/events/events.md b/www/docs/en/6.x/cordova/events/events.md
index c93124b..0e988bf 100644
--- a/www/docs/en/6.x/cordova/events/events.md
+++ b/www/docs/en/6.x/cordova/events/events.md
@@ -324,6 +324,24 @@ function onBackKeyDown() {
}
```
+### Windows Quirks
+
+Throw an error in a `backbutton` callback to force the default behavior, which is an app exit:
+
+```javascript
+document.addEventListener('backbutton', function (evt) {
+ if (cordova.platformId !== 'windows') {
+ return;
+ }
+
+ if (window.location.href !== firstPageUrl) {
+ window.history.back();
+ } else {
+ throw new Error('Exit'); // This will suspend the app
+ }
+}, false);
+```
+
## menubutton
The event fires when the user presses the menu button. Applying an event handler
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/cordova/storage/storage.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/cordova/storage/storage.md b/www/docs/en/6.x/cordova/storage/storage.md
index eac2a32..0a63ca7 100644
--- a/www/docs/en/6.x/cordova/storage/storage.md
+++ b/www/docs/en/6.x/cordova/storage/storage.md
@@ -294,11 +294,9 @@ The main differences are:
It is available in the following variations:
-* **[cordova-sqlite-storage][SQLiteStorage]** - core version that relies
- on native SQLite implementation. As such, it is only available for iOS
- and Android platforms.
+* **[cordova-sqlite-storage][SQLiteStorage]** - core version that includes its own sqlite3 implementation. It supports iOS, Android & Windows platforms.
* **[cordova-sqlite-ext][SQLiteExt]** - extended version with additional
- features including support for Windows and REGEXP support on Android and iOS.
+ features including REGEXP support on Android and iOS.
* **[cordova-sqlite-evfree][SQLiteEVFree]** - similar to *cordova-sqlite-ext*
but with improved memory handling. Available under GPL v3 or commercial license.
@@ -323,7 +321,7 @@ alternative storage options.
[StructuredCloneAlgorithm]: http://w3c.github.io/html/infrastructure.html#safe-passing-of-structured-data
[Html5RocksFileSystemTutorial]: http://www.html5rocks.com/en/tutorials/file/filesystem/
[FileAPI]: https://github.com/apache/cordova-plugin-file/blob/master/README.md
-[SQLiteStorage]: https://github.com/litehelpers/Cordova-sqlite-storage/blob/core-master/README.md
-[SQLiteExt]: https://github.com/litehelpers/cordova-sqlite-ext/blob/ext-master/README.md
-[SQLiteEVFree]: https://github.com/litehelpers/Cordova-sqlite-enterprise-free/blob/evfree-ext-rc/README.md
+[SQLiteStorage]: https://github.com/litehelpers/Cordova-sqlite-storage#readme
+[SQLiteExt]: https://github.com/litehelpers/cordova-sqlite-ext#readme
+[SQLiteEVFree]: https://github.com/litehelpers/Cordova-sqlite-enterprise-free#readme
[CordovaPlugins]: {{ site.baseurl }}/plugins
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/guide/platforms/win8/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/guide/platforms/win8/index.md b/www/docs/en/6.x/guide/platforms/win8/index.md
index c374952..d227445 100644
--- a/www/docs/en/6.x/guide/platforms/win8/index.md
+++ b/www/docs/en/6.x/guide/platforms/win8/index.md
@@ -80,11 +80,9 @@ 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/>
+The tools and SDKs for the target Windows platforms (UWP, 8.1, etc.) must also be selected in the installer. They can be found under the "Windows and Web Development" heading.
-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.
+<br/><p align="center"><img src="{{ site.baseurl }}/static/img/guide/platforms/win8/win8_installTools.png" /></p><br/>
## Project Configuration
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/guide/platforms/win8/plugin.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/guide/platforms/win8/plugin.md b/www/docs/en/6.x/guide/platforms/win8/plugin.md
index d84ee68..4239fa6 100644
--- a/www/docs/en/6.x/guide/platforms/win8/plugin.md
+++ b/www/docs/en/6.x/guide/platforms/win8/plugin.md
@@ -70,7 +70,7 @@ cordova.commandProxy.add("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.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.
+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
<?xml version="1.0" encoding="UTF-8"?>
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/plugin_ref/plugman.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/plugin_ref/plugman.md b/www/docs/en/6.x/plugin_ref/plugman.md
index 5a80df6..4321080 100644
--- a/www/docs/en/6.x/plugin_ref/plugman.md
+++ b/www/docs/en/6.x/plugin_ref/plugman.md
@@ -77,7 +77,7 @@ listed on the Platform guides page.
Once you have installed Plugman and have created a Cordova project, you can start adding plugins to the platform with:
```bash
-$ plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]
+$ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]
```
Using minimum parameters, this command installs a plugin into a cordova project. You must specify a platform and cordova project location for that platform. You also must specify a plugin, with the different `--plugin` parameter forms being:
@@ -94,10 +94,10 @@ Other parameters:
## Remove a Plugin
-To uninstall a plugin, you simply pass the `--uninstall` flag and provide the plugin ID.
+To uninstall a plugin, you simply pass the `uninstall` command and provide the plugin ID.
```bash
-$ plugman --uninstall --platform <ios|android|blackberry10|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]
+$ plugman uninstall --platform <ios|android|blackberry10|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]
```
@@ -171,107 +171,107 @@ platform, and reference the platform's project directory.
* cordova-plugin-battery-status
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-battery-status
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-battery-status
```
* cordova-plugin-camera
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-camera
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-camera
```
* cordova-plugin-console
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-console
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-console
```
* cordova-plugin-contacts
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-contacts
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-contacts
```
* cordova-plugin-device
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-device
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-device
```
* cordova-plugin-device-motion (accelerometer)
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-device-motion
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-device-motion
```
* cordova-plugin-device-orientation (compass)
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-device-orientation
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-device-orientation
```
* cordova-plugin-dialogs
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-dialogs
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-dialogs
```
* cordova-plugin-file
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-file
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-file
```
* cordova-plugin-file-transfer
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-file-transfer
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-file-transfer
```
* cordova-plugin-geolocation
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-geolocation
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-geolocation
```
* cordova-plugin-globalization
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-globalization
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-globalization
```
* cordova-plugin-inappbrowser
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-inappbrowser
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-inappbrowser
```
* cordova-plugin-media
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-media
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-media
```
* cordova-plugin-media-capture
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-media-capture
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-media-capture
```
* cordova-plugin-network-information
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-network-information
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-network-information
```
* cordova-plugin-splashscreen
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-splashscreen
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-splashscreen
```
* cordova-plugin-vibration
```bash
- plugman --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-vibration
+ plugman install --platform <ios|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-vibration
```
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org