You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by st...@apache.org on 2016/10/26 18:23:29 UTC
[2/4] docs commit: Updated 6.x docs from latest
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5280960d/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 d656549..db3ff4c 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
@@ -1,8 +1,9 @@
---
edit_link: 'https://github.com/apache/cordova-plugin-geolocation/blob/master/README.md'
-title: cordova-plugin-geolocation
+title: Geolocation
plugin_name: cordova-plugin-geolocation
plugin_version: master
+description: Access GPS data.
---
<!-- WARNING: This file is generated. See fetch_docs.js. -->
@@ -26,17 +27,23 @@ plugin_version: master
# under the License.
-->
-[](https://travis-ci.org/apache/cordova-plugin-geolocation)
+|Android|iOS| Windows 8.1 Store | Windows 8.1 Phone | Windows 10 Store | Travis CI |
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-geolocation/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-geolocation/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-store,PLUGIN=cordova-plugin-geolocation/)|[](http://cordova-ci.cloudapp
.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-phone,PLUGIN=cordova-plugin-geolocation/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-geolocation/)|[](https://travis-ci.org/apache/cordova-plugin-geolocation)|
# 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.
@@ -62,11 +69,15 @@ where it is otherwise missing).
Although the object is in the global scope, features provided by this plugin
are not available until after the `deviceready` event.
+```javascript
+
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
console.log("navigator.geolocation works well");
}
+```
+## <a id="reference"></a>Reference
## Installation
This requires cordova 5.0+ ( current stable 1.0.0 )
@@ -126,6 +137,8 @@ error, the `geolocationError` callback is passed a
### Example
+```javascript
+
// onSuccess Callback
// This method accepts a Position object, which contains the
// current GPS coordinates
@@ -150,6 +163,19 @@ error, the `geolocationError` callback is passed a
navigator.geolocation.getCurrentPosition(onSuccess, onError);
+```
+
+### iOS Quirks
+
+ Since iOS 10 it's mandatory to add a `NSLocationWhenInUseUsageDescription` entry in the info.plist.
+
+ `NSLocationWhenInUseUsageDescription` describes the reason that the app accesses the user's location. When the system prompts the user to allow access, this string is displayed as part of the dialog box. To add this entry you can pass the variable `GEOLOCATION_USAGE_DESCRIPTION` on plugin install.
+
+ Example:
+ `cordova plugin add cordova-plugin-geolocation --variable GEOLOCATION_USAGE_DESCRIPTION="your usage message"`
+
+ If you don't pass the variable, the plugin will add an empty string as value.
+
### Android Quirks
If Geolocation service is turned off the `onError` callback is invoked after `timeout` interval (if specified).
@@ -181,6 +207,8 @@ there is an error, the `geolocationError` callback executes with a
### Example
+```javascript
+
// onSuccess Callback
// This method accepts a `Position` object, which contains
// the current GPS coordinates
@@ -203,6 +231,7 @@ there is an error, the `geolocationError` callback executes with a
//
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { timeout: 30000 });
+```
## geolocationOptions
@@ -237,6 +266,8 @@ Stop watching for changes to the device's location referenced by the
### Example
+```javascript
+
// Options: watch for changes in position, and use the most
// accurate position acquisition method available.
//
@@ -246,6 +277,8 @@ Stop watching for changes to the device's location referenced by the
navigator.geolocation.clearWatch(watchID);
+```
+
## Position
Contains `Position` coordinates and timestamp, created by the geolocation API.
@@ -305,3 +338,438 @@ callback function when an error occurs with navigator.geolocation.
- Returned when the device is unable to retrieve a position. In general, this means the device is not connected to a network or can't get a satellite fix.
- `PositionError.TIMEOUT`
- Returned when the device is unable to retrieve a position within the time specified by the `timeout` included in `geolocationOptions`. When used with `navigator.geolocation.watchPosition`, this error could be repeatedly passed to the `geolocationError` callback every `timeout` milliseconds.
+
+
+## <a id="sample"></a>Sample: Get the weather, find stores, and see photos of things nearby with Geolocation ##
+
+Use this plugin to help users find things near them such as Groupon deals, houses for sale, movies playing, sports and entertainment events and more.
+
+Here's a "cookbook" of ideas to get you started. In the snippets below, we'll show you some basic ways to add these features to your app.
+
+* [Get your coordinates](#coords).
+* [Get the weather forecast](#weather).
+* [Receive updated weather forecasts as you drive around](#receive).
+* [See where you are on a map](#see).
+* [Find stores near you](#find).
+* [See pictures of things around you](#see).
+
+## <a id="coord"></a>Get your geolocation coordinates
+
+```javascript
+
+function getWeatherLocation() {
+
+ navigator.geolocation.getCurrentPosition
+ (onWeatherSuccess, onWeatherError, { enableHighAccuracy: true });
+}
+
+```
+## <a id="weather"></a>Get the weather forecast
+
+```javascript
+
+// Success callback for get geo coordinates
+
+var onWeatherSuccess = function (position) {
+
+ Latitude = position.coords.latitude;
+ Longitude = position.coords.longitude;
+
+ getWeather(Latitude, Longitude);
+}
+
+// Get weather by using coordinates
+
+function getWeather(latitude, longitude) {
+
+ // Get a free key at http://openweathermap.org/. Replace the "Your_Key_Here" string with that key.
+ var OpenWeatherAppKey = "Your_Key_Here";
+
+ var queryString =
+ 'http://api.openweathermap.org/data/2.5/weather?lat='
+ + latitude + '&lon=' + longitude + '&appid=' + OpenWeatherAppKey + '&units=imperial';
+
+ $.getJSON(queryString, function (results) {
+
+ if (results.weather.length) {
+
+ $.getJSON(queryString, function (results) {
+
+ if (results.weather.length) {
+
+ $('#description').text(results.name);
+ $('#temp').text(results.main.temp);
+ $('#wind').text(results.wind.speed);
+ $('#humidity').text(results.main.humidity);
+ $('#visibility').text(results.weather[0].main);
+
+ var sunriseDate = new Date(results.sys.sunrise);
+ $('#sunrise').text(sunriseDate.toLocaleTimeString());
+
+ var sunsetDate = new Date(results.sys.sunrise);
+ $('#sunset').text(sunsetDate.toLocaleTimeString());
+ }
+
+ });
+ }
+ }).fail(function () {
+ console.log("error getting location");
+ });
+}
+
+// Error callback
+
+function onWeatherError(error) {
+ console.log('code: ' + error.code + '\n' +
+ 'message: ' + error.message + '\n');
+}
+
+```
+
+## <a id="receive"></a>Receive updated weather forecasts as you drive around
+
+```javascript
+
+// Watch your changing position
+
+function watchWeatherPosition() {
+
+ return navigator.geolocation.watchPosition
+ (onWeatherWatchSuccess, onWeatherError, { enableHighAccuracy: true });
+}
+
+// Success callback for watching your changing position
+
+var onWeatherWatchSuccess = function (position) {
+
+ var updatedLatitude = position.coords.latitude;
+ var updatedLongitude = position.coords.longitude;
+
+ if (updatedLatitude != Latitude && updatedLongitude != Longitude) {
+
+ Latitude = updatedLatitude;
+ Longitude = updatedLongitude;
+
+ // Calls function we defined earlier.
+ getWeather(updatedLatitude, updatedLongitude);
+ }
+}
+
+```
+
+## <a id="see"></a>See where you are on a map
+
+Both Bing and Google have map services. We'll use Google's. You'll need a key but it's free if you're just trying things out.
+
+Add a reference to the **maps** service.
+
+```HTML
+
+ <script src="https://maps.googleapis.com/maps/api/js?key=Your_API_Key"></script>
+
+```
+Then, add code to use it.
+
+```javascript
+
+var Latitude = undefined;
+var Longitude = undefined;
+
+// Get geo coordinates
+
+function getMapLocation() {
+
+ navigator.geolocation.getCurrentPosition
+ (onMapSuccess, onMapError, { enableHighAccuracy: true });
+}
+
+// Success callback for get geo coordinates
+
+var onMapSuccess = function (position) {
+
+ Latitude = position.coords.latitude;
+ Longitude = position.coords.longitude;
+
+ getMap(Latitude, Longitude);
+
+}
+
+// Get map by using coordinates
+
+function getMap(latitude, longitude) {
+
+ var mapOptions = {
+ center: new google.maps.LatLng(0, 0),
+ zoom: 1,
+ mapTypeId: google.maps.MapTypeId.ROADMAP
+ };
+
+ map = new google.maps.Map
+ (document.getElementById("map"), mapOptions);
+
+
+ var latLong = new google.maps.LatLng(latitude, longitude);
+
+ var marker = new google.maps.Marker({
+ position: latLong
+ });
+
+ marker.setMap(map);
+ map.setZoom(15);
+ map.setCenter(marker.getPosition());
+}
+
+// Success callback for watching your changing position
+
+var onMapWatchSuccess = function (position) {
+
+ var updatedLatitude = position.coords.latitude;
+ var updatedLongitude = position.coords.longitude;
+
+ if (updatedLatitude != Latitude && updatedLongitude != Longitude) {
+
+ Latitude = updatedLatitude;
+ Longitude = updatedLongitude;
+
+ getMap(updatedLatitude, updatedLongitude);
+ }
+}
+
+// Error callback
+
+function onMapError(error) {
+ console.log('code: ' + error.code + '\n' +
+ 'message: ' + error.message + '\n');
+}
+
+// Watch your changing position
+
+function watchMapPosition() {
+
+ return navigator.geolocation.watchPosition
+ (onMapWatchSuccess, onMapError, { enableHighAccuracy: true });
+}
+
+```
+
+## <a id="find"></a>Find stores near you
+
+You can use the same Google key for this.
+
+Add a reference to the **places** service.
+
+```HTML
+
+<script src=
+"https://maps.googleapis.com/maps/api/js?key=Your_API_Key&libraries=places">
+</script>
+
+```
+
+Then, add code to use it.
+
+```javascript
+
+var Map;
+var Infowindow;
+var Latitude = undefined;
+var Longitude = undefined;
+
+// Get geo coordinates
+
+function getPlacesLocation() {
+ navigator.geolocation.getCurrentPosition
+ (onPlacesSuccess, onPlacesError, { enableHighAccuracy: true });
+}
+
+// Success callback for get geo coordinates
+
+var onPlacesSuccess = function (position) {
+
+ Latitude = position.coords.latitude;
+ Longitude = position.coords.longitude;
+
+ getPlaces(Latitude, Longitude);
+
+}
+
+// Get places by using coordinates
+
+function getPlaces(latitude, longitude) {
+
+ var latLong = new google.maps.LatLng(latitude, longitude);
+
+ var mapOptions = {
+
+ center: new google.maps.LatLng(latitude, longitude),
+ zoom: 15,
+ mapTypeId: google.maps.MapTypeId.ROADMAP
+
+ };
+
+ Map = new google.maps.Map(document.getElementById("places"), mapOptions);
+
+ Infowindow = new google.maps.InfoWindow();
+
+ var service = new google.maps.places.PlacesService(Map);
+ service.nearbySearch({
+
+ location: latLong,
+ radius: 500,
+ type: ['store']
+ }, foundStoresCallback);
+
+}
+
+// Success callback for watching your changing position
+
+var onPlacesWatchSuccess = function (position) {
+
+ var updatedLatitude = position.coords.latitude;
+ var updatedLongitude = position.coords.longitude;
+
+ if (updatedLatitude != Latitude && updatedLongitude != Longitude) {
+
+ Latitude = updatedLatitude;
+ Longitude = updatedLongitude;
+
+ getPlaces(updatedLatitude, updatedLongitude);
+ }
+}
+
+// Success callback for locating stores in the area
+
+function foundStoresCallback(results, status) {
+
+ if (status === google.maps.places.PlacesServiceStatus.OK) {
+
+ for (var i = 0; i < results.length; i++) {
+
+ createMarker(results[i]);
+
+ }
+ }
+}
+
+// Place a pin for each store on the map
+
+function createMarker(place) {
+
+ var placeLoc = place.geometry.location;
+
+ var marker = new google.maps.Marker({
+ map: Map,
+ position: place.geometry.location
+ });
+
+ google.maps.event.addListener(marker, 'click', function () {
+
+ Infowindow.setContent(place.name);
+ Infowindow.open(Map, this);
+
+ });
+}
+
+// Error callback
+
+function onPlacesError(error) {
+ console.log('code: ' + error.code + '\n' +
+ 'message: ' + error.message + '\n');
+}
+
+// Watch your changing position
+
+function watchPlacesPosition() {
+
+ return navigator.geolocation.watchPosition
+ (onPlacesWatchSuccess, onPlacesError, { enableHighAccuracy: true });
+}
+
+```
+
+## <a id="pictures"></a>See pictures of things around you
+
+Digital photos can contain geo coordinates that identify where the picture was taken.
+
+Use Flickr API's to find pictures that folks have taken near you. Like Google services, you'll need a key, but it's free if you just want to try things out.
+
+```javascript
+
+var Latitude = undefined;
+var Longitude = undefined;
+
+// Get geo coordinates
+
+function getPicturesLocation() {
+
+ navigator.geolocation.getCurrentPosition
+ (onPicturesSuccess, onPicturesError, { enableHighAccuracy: true });
+
+}
+
+// Success callback for get geo coordinates
+
+var onPicturesSuccess = function (position) {
+
+ Latitude = position.coords.latitude;
+ Longitude = position.coords.longitude;
+
+ getPictures(Latitude, Longitude);
+}
+
+// Get pictures by using coordinates
+
+function getPictures(latitude, longitude) {
+
+ $('#pictures').empty();
+
+ var queryString =
+ "https://api.flickr.com/services/rest/?method=flickr.photos.search&api_key=Your_API_Key&lat="
+ + latitude + "&lon=" + longitude + "&format=json&jsoncallback=?";
+
+ $.getJSON(queryString, function (results) {
+ $.each(results.photos.photo, function (index, item) {
+
+ var photoURL = "http://farm" + item.farm + ".static.flickr.com/" +
+ item.server + "/" + item.id + "_" + item.secret + "_m.jpg";
+
+ $('#pictures').append($("<img />").attr("src", photoURL));
+
+ });
+ }
+ );
+}
+
+// Success callback for watching your changing position
+
+var onPicturesWatchSuccess = function (position) {
+
+ var updatedLatitude = position.coords.latitude;
+ var updatedLongitude = position.coords.longitude;
+
+ if (updatedLatitude != Latitude && updatedLongitude != Longitude) {
+
+ Latitude = updatedLatitude;
+ Longitude = updatedLongitude;
+
+ getPictures(updatedLatitude, updatedLongitude);
+ }
+}
+
+// Error callback
+
+function onPicturesError(error) {
+
+ console.log('code: ' + error.code + '\n' +
+ 'message: ' + error.message + '\n');
+}
+
+// Watch your changing position
+
+function watchPicturePosition() {
+
+ return navigator.geolocation.watchPosition
+ (onPicturesWatchSuccess, onPicturesError, { enableHighAccuracy: true });
+}
+
+```
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5280960d/www/docs/en/6.x/reference/cordova-plugin-globalization/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-globalization/index.md b/www/docs/en/6.x/reference/cordova-plugin-globalization/index.md
index 91c4906..11dcd54 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-globalization/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-globalization/index.md
@@ -1,8 +1,9 @@
---
edit_link: 'https://github.com/apache/cordova-plugin-globalization/blob/master/README.md'
-title: cordova-plugin-globalization
+title: Globalization
plugin_name: cordova-plugin-globalization
plugin_version: master
+description: Access locale data.
---
<!-- WARNING: This file is generated. See fetch_docs.js. -->
@@ -26,7 +27,9 @@ plugin_version: master
# under the License.
-->
-[](https://travis-ci.org/apache/cordova-plugin-globalization)
+|Android|iOS| Windows 8.1 Store | Windows 8.1 Phone | Windows 10 Store | Travis CI |
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-globalization/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-globalization/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-store,PLUGIN=cordova-plugin-globalization/)|[](http://cordo
va-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-phone,PLUGIN=cordova-plugin-globalization/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-globalization/)|[](https://travis-ci.org/apache/cordova-plugin-globalization)|
# cordova-plugin-globalization
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5280960d/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 7f0d306..2f162ec 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
@@ -1,8 +1,9 @@
---
edit_link: 'https://github.com/apache/cordova-plugin-inappbrowser/blob/master/README.md'
-title: cordova-plugin-inappbrowser
+title: Inappbrowser
plugin_name: cordova-plugin-inappbrowser
plugin_version: master
+description: Open an in-app browser window.
---
<!-- WARNING: This file is generated. See fetch_docs.js. -->
@@ -26,10 +27,16 @@ plugin_version: master
# under the License.
-->
-[](https://travis-ci.org/apache/cordova-plugin-inappbrowser)
+|Android|iOS| Windows 8.1 Store | Windows 8.1 Phone | Windows 10 Store | Travis CI |
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-inappbrowser/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-inappbrowser/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-store,PLUGIN=cordova-plugin-inappbrowser/)|[](http://cordova-ci.c
loudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-phone,PLUGIN=cordova-plugin-inappbrowser/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-inappbrowser/)|[](https://travis-ci.org/apache/cordova-plugin-inappbrowser)|
# cordova-plugin-inappbrowser
+You can show helpful articles, videos, and web resources inside of your app. Users can view web pages without leaving your app.
+
+> 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 plugin provides a web browser view that displays when calling `cordova.InAppBrowser.open()`.
var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
@@ -68,7 +75,7 @@ Although `window.open` is in the global scope, InAppBrowser is not available unt
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%20InAppBrowser%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC)
-
+## <a id="reference">Reference</a>
## Installation
cordova plugin add cordova-plugin-inappbrowser
@@ -88,7 +95,7 @@ instance, or the system browser.
var ref = cordova.InAppBrowser.open(url, target, options);
-- __ref__: Reference to the `InAppBrowser` window. _(InAppBrowser)_
+- __ref__: Reference to the `InAppBrowser` window when the target is set to `'_blank'`. _(InAppBrowser)_
- __url__: The URL to load _(String)_. Call `encodeURI()` on this if the URL contains Unicode characters.
@@ -112,6 +119,7 @@ instance, or the system browser.
- __zoom__: set to `yes` to show Android browser's zoom controls, set to `no` to hide them. Default value is `yes`.
- __hardwareback__: set to `yes` to use the hardware back button to navigate backwards through the `InAppBrowser`'s history. If there is no previous page, the `InAppBrowser` will close. The default value is `yes`, so you must set it to `no` if you want the back button to simply close the InAppBrowser.
- __mediaPlaybackRequiresUserAction__: Set to `yes` to prevent HTML5 audio or video from autoplaying (defaults to `no`).
+ - __shouldPauseOnSuspend__: Set to `yes` to make InAppBrowser WebView to pause/resume with the app to stop background audio (this may be required to avoid Google Play issues like described in [CB-11013](https://issues.apache.org/jira/browse/CB-11013)).
iOS only:
@@ -134,6 +142,7 @@ instance, or the system browser.
- __hidden__: set to `yes` to create the browser and load the page, but not show it. The loadstop event fires when loading is complete. Omit or set to `no` (default) to have the browser open and load normally.
- __fullscreen__: set to `yes` to create the browser control without a border around it. Please note that if __location=no__ is also specified, there will be no control presented to user to close IAB window.
+ - __hardwareback__: works the same way as on Android platform.
### Supported Platforms
@@ -142,6 +151,7 @@ instance, or the system browser.
- BlackBerry 10
- Firefox OS
- iOS
+- OSX
- Windows 8 and 8.1
- Windows Phone 7 and 8
- Browser
@@ -182,6 +192,12 @@ opened with `target='_blank'`. The rules might look like these
}
```
+### OSX Quirks
+
+At the moment the only supported target in OSX is `_system`.
+
+`_blank` and `_self` targets are not yet implemented and are ignored silently. Pull requests and patches to get these to work are greatly appreciated.
+
### Windows Quirks
Windows 8.0, 8.1 and Windows Phone 8.1 don't support remote urls to be opened in the Cordova WebView so remote urls are always showed in the system's web browser if opened with `target='_self'`.
@@ -198,7 +214,7 @@ Similar to Firefox OS IAB window visual behaviour can be overridden via `inAppBr
## InAppBrowser
-The object returned from a call to `cordova.InAppBrowser.open`.
+The object returned from a call to `cordova.InAppBrowser.open` when the target is set to `'_blank'`.
### Methods
@@ -206,6 +222,7 @@ The object returned from a call to `cordova.InAppBrowser.open`.
- removeEventListener
- close
- show
+- hide
- executeScript
- insertCSS
@@ -226,6 +243,76 @@ 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;
+
+function showHelp(url) {
+
+ var target = "_blank";
+
+ var options = "location=yes,hidden=yes";
+
+ inAppBrowserRef = cordova.InAppBrowser.open(url, target, options);
+
+ inAppBrowserRef.addEventListener('loadstart', loadStartCallBack);
+
+ inAppBrowserRef.addEventListener('loadstop', loadStopCallBack);
+
+ inAppBrowserRef.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)_
@@ -334,6 +421,27 @@ The function is passed an `InAppBrowserEvent` object.
// some time later...
ref.show();
+## InAppBrowser.hide
+
+> Hides the InAppBrowser window. Calling this has no effect if the InAppBrowser was already hidden.
+
+ ref.hide();
+
+- __ref__: reference to the InAppBrowser window (`InAppBrowser`)
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- iOS
+- Windows 8 and 8.1
+
+### Quick Example
+
+ var ref = cordova.InAppBrowser.open('http://apache.org', '_blank');
+ // some time later...
+ ref.hide();
+
## InAppBrowser.executeScript
> Injects JavaScript code into the `InAppBrowser` window
@@ -403,3 +511,204 @@ 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);
+
+ inAppBrowserRef.addEventListener('loadstart', loadStartCallBack);
+
+ inAppBrowserRef.addEventListener('loadstop', loadStopCallBack);
+
+ inAppBrowserRef.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 + "'");
+ }
+
+}
+
+```
+
+## More Usage Info
+
+### Local Urls ( source is in the app package )
+```
+var iab = cordova.InAppBrowser;
+
+iab.open('local-url.html'); // loads in the Cordova WebView
+iab.open('local-url.html', '_self'); // loads in the Cordova WebView
+iab.open('local-url.html', '_system'); // Security error: system browser, but url will not load (iOS)
+iab.open('local-url.html', '_blank'); // loads in the InAppBrowser
+iab.open('local-url.html', 'random_string'); // loads in the InAppBrowser
+iab.open('local-url.html', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar
+
+```
+
+
+
+### Whitelisted Content
+
+```
+var iab = cordova.InAppBrowser;
+
+iab.open('http://whitelisted-url.com'); // loads in the Cordova WebView
+iab.open('http://whitelisted-url.com', '_self'); // loads in the Cordova WebView
+iab.open('http://whitelisted-url.com', '_system'); // loads in the system browser
+iab.open('http://whitelisted-url.com', '_blank'); // loads in the InAppBrowser
+iab.open('http://whitelisted-url.com', 'random_string'); // loads in the InAppBrowser
+
+iab.open('http://whitelisted-url.com', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar
+
+```
+
+### Urls that are not white-listed
+
+```
+var iab = cordova.InAppBrowser;
+
+iab.open('http://url-that-fails-whitelist.com'); // loads in the InAppBrowser
+iab.open('http://url-that-fails-whitelist.com', '_self'); // loads in the InAppBrowser
+iab.open('http://url-that-fails-whitelist.com', '_system'); // loads in the system browser
+iab.open('http://url-that-fails-whitelist.com', '_blank'); // loads in the InAppBrowser
+iab.open('http://url-that-fails-whitelist.com', 'random_string'); // loads in the InAppBrowser
+iab.open('http://url-that-fails-whitelist.com', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar
+
+```
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5280960d/www/docs/en/6.x/reference/cordova-plugin-legacy-whitelist/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-legacy-whitelist/index.md b/www/docs/en/6.x/reference/cordova-plugin-legacy-whitelist/index.md
index 2cc5d53..ab3fbc1 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-legacy-whitelist/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-legacy-whitelist/index.md
@@ -1,8 +1,10 @@
---
-edit_link: 'https://github.com/apache/cordova-plugin-legacy-whitelist/blob/master/README.md'
-title: cordova-plugin-legacy-whitelist
+edit_link: >-
+ https://github.com/apache/cordova-plugin-legacy-whitelist/blob/master/README.md
+title: Legacy Whitelist
plugin_name: cordova-plugin-legacy-whitelist
plugin_version: master
+description: Legacy implementation of the whitelist plugin.
---
<!-- WARNING: This file is generated. See fetch_docs.js. -->
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5280960d/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 dd6b295..2cdbcb4 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
@@ -1,8 +1,9 @@
---
edit_link: 'https://github.com/apache/cordova-plugin-media-capture/blob/master/README.md'
-title: cordova-plugin-media-capture
+title: Media Capture
plugin_name: cordova-plugin-media-capture
plugin_version: master
+description: 'Capture audio, video, and images.'
---
<!-- WARNING: This file is generated. See fetch_docs.js. -->
@@ -26,7 +27,9 @@ plugin_version: master
# under the License.
-->
-[](https://travis-ci.org/apache/cordova-plugin-media-capture)
+|Android|iOS| Windows 8.1 Store | Windows 8.1 Phone | Windows 10 Store | Travis CI |
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-media-capture/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-media-capture/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-store,PLUGIN=cordova-plugin-media-capture/)|[](http://cordo
va-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-phone,PLUGIN=cordova-plugin-media-capture/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-media-capture/)|[](https://travis-ci.org/apache/cordova-plugin-media-capture)|
# cordova-plugin-media-capture
@@ -201,6 +204,29 @@ object featuring a `CaptureError.CAPTURE_NO_MEDIA_FILES` error code.
- Windows 8
- Windows
+### iOS Quirks
+
+Since iOS 10 it's mandatory to add a `NSCameraUsageDescription`, `NSMicrophoneUsageDescription` and `NSPhotoLibraryUsageDescriptionentry` in the info.plist.
+
+* `NSCameraUsageDescription` describes the reason that the app accesses the user\u2019s camera.
+* `NSMicrophoneUsageDescription` describes the reason that the app accesses the user\u2019s microphone.
+* `NSPhotoLibraryUsageDescriptionentry` describes the reason the app accesses the user's photo library.
+
+When the system prompts the user to allow access, this string is displayed as part of the dialog box.
+
+To add this entry you can pass the following variables on plugin install.
+
+* `CAMERA_USAGE_DESCRIPTION` for `NSCameraUsageDescription`
+* `MICROPHONE_USAGE_DESCRIPTION` for `NSMicrophoneUsageDescription`
+* `PHOTOLIBRARY_USAGE_DESCRIPTION` for `NSPhotoLibraryUsageDescriptionentry`
+
+-
+Example:
+
+`cordova plugin add cordova-plugin-media-capture --variable CAMERA_USAGE_DESCRIPTION="your usage message"`
+
+If you don't pass the variable, the plugin will add an empty string as value.
+
### Windows Phone 7 Quirks
Invoking the native camera application while your device is connected
@@ -432,6 +458,8 @@ Each `MediaFile` object describes a captured media file.
- `CaptureError.CAPTURE_NO_MEDIA_FILES`: The user exits the camera or audio capture application before capturing anything.
+- `CaptureError.CAPTURE_PERMISSION_DENIED`: The user denied a permission required to perform the given capture request.
+
- `CaptureError.CAPTURE_NOT_SUPPORTED`: The requested capture operation is not supported.
## CaptureErrorCB
@@ -640,3 +668,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
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5280960d/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 55b8aa5..1cc5b18 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
@@ -1,8 +1,9 @@
---
edit_link: 'https://github.com/apache/cordova-plugin-media/blob/master/README.md'
-title: cordova-plugin-media
+title: Media
plugin_name: cordova-plugin-media
plugin_version: master
+description: Record and play audio on the device.
---
<!-- WARNING: This file is generated. See fetch_docs.js. -->
@@ -26,7 +27,9 @@ plugin_version: master
# under the License.
-->
-[](https://travis-ci.org/apache/cordova-plugin-media)
+|Android|iOS| Windows 8.1 Store | Windows 8.1 Phone | Windows 10 Store | Travis CI |
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-media/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-media/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-store,PLUGIN=cordova-plugin-media/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATF
ORM=windows-8.1-phone,PLUGIN=cordova-plugin-media/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-media/)|[](https://travis-ci.org/apache/cordova-plugin-media)|
# cordova-plugin-media
@@ -42,17 +45,21 @@ This plugin defines a global `Media` Constructor.
Although in the global scope, it is not available until after the `deviceready` event.
- document.addEventListener("deviceready", onDeviceReady, false);
- function onDeviceReady() {
- console.log(Media);
- }
+```js
+document.addEventListener("deviceready", onDeviceReady, false);
+function onDeviceReady() {
+ console.log(Media);
+}
+```
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%20Media%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC)
## Installation
- cordova plugin add cordova-plugin-media
+```bash
+cordova plugin add cordova-plugin-media
+```
## Supported Platforms
@@ -71,7 +78,9 @@ Report issues with this plugin on the [Apache Cordova issue tracker](https://iss
## Media
- var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]);
+```js
+var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]);
+```
### Parameters
@@ -101,6 +110,8 @@ The following constants are reported as the only parameter to the
### Methods
+- `media.getCurrentAmplitude`: Returns the current position within an audio file.
+
- `media.getCurrentPosition`: Returns the current position within an audio file.
- `media.getDuration`: Returns the duration of an audio file.
@@ -109,8 +120,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.
@@ -129,6 +144,48 @@ The following constants are reported as the only parameter to the
- __duration__: The duration of the media, in seconds.
+## media.getCurrentAmplitude
+
+Returns the current amplitude of the current recording.
+
+ media.getCurrentAmplitude(mediaSuccess, [mediaError]);
+
+### Supported Platforms
+
+- Android
+- iOS
+
+### Parameters
+
+- __mediaSuccess__: The callback that is passed the current amplitude (0.0 - 1.0).
+
+- __mediaError__: (Optional) The callback to execute if an error occurs.
+
+### Quick Example
+
+```js
+// Audio player
+//
+var my_media = new Media(src, onSuccess, onError);
+
+// Record audio
+my_media.startRecord();
+
+mediaTimer = setInterval(function () {
+ // get media amplitude
+ my_media.getCurrentAmplitude(
+ // success callback
+ function (amp) {
+ console.log(amp + "%");
+ },
+ // error callback
+ function (e) {
+ console.log("Error getting amp=" + e);
+ }
+ );
+}, 1000);
+```
+
## media.getCurrentPosition
Returns the current position within an audio file. Also updates the `Media` object's `position` parameter.
@@ -143,27 +200,28 @@ Returns the current position within an audio file. Also updates the `Media` obj
### Quick Example
- // Audio player
- //
- var my_media = new Media(src, onSuccess, onError);
-
- // Update media position every second
- var mediaTimer = setInterval(function () {
- // get media position
- my_media.getCurrentPosition(
- // success callback
- function (position) {
- if (position > -1) {
- console.log((position) + " sec");
- }
- },
- // error callback
- function (e) {
- console.log("Error getting pos=" + e);
+```js
+// Audio player
+//
+var my_media = new Media(src, onSuccess, onError);
+
+// Update media position every second
+var mediaTimer = setInterval(function () {
+ // get media position
+ my_media.getCurrentPosition(
+ // success callback
+ function (position) {
+ if (position > -1) {
+ console.log((position) + " sec");
}
- );
- }, 1000);
-
+ },
+ // error callback
+ function (e) {
+ console.log("Error getting pos=" + e);
+ }
+ );
+}, 1000);
+```
## media.getDuration
@@ -174,24 +232,25 @@ Returns the duration of an audio file in seconds. If the duration is unknown, it
### Quick Example
- // Audio player
- //
- var my_media = new Media(src, onSuccess, onError);
-
- // Get duration
- var counter = 0;
- var timerDur = setInterval(function() {
- counter = counter + 100;
- if (counter > 2000) {
- clearInterval(timerDur);
- }
- var dur = my_media.getDuration();
- if (dur > 0) {
- clearInterval(timerDur);
- document.getElementById('audio_duration').innerHTML = (dur) + " sec";
- }
- }, 100);
-
+```js
+// Audio player
+//
+var my_media = new Media(src, onSuccess, onError);
+
+// Get duration
+var counter = 0;
+var timerDur = setInterval(function() {
+ counter = counter + 100;
+ if (counter > 2000) {
+ clearInterval(timerDur);
+ }
+ var dur = my_media.getDuration();
+ if (dur > 0) {
+ clearInterval(timerDur);
+ document.getElementById('audio_duration').innerHTML = (dur) + " sec";
+ }
+}, 100);
+```
## media.pause
@@ -202,54 +261,97 @@ Pauses playing an audio file.
### Quick Example
+```js
+// Play audio
+//
+function playAudio(url) {
+ // Play the audio file at url
+ var my_media = new Media(url,
+ // success callback
+ function () { console.log("playAudio():Audio Success"); },
+ // error callback
+ function (err) { console.log("playAudio():Audio Error: " + err); }
+ );
+
// Play audio
- //
- function playAudio(url) {
- // Play the audio file at url
- var my_media = new Media(url,
- // success callback
- function () { console.log("playAudio():Audio Success"); },
- // error callback
- function (err) { console.log("playAudio():Audio Error: " + err); }
- );
-
- // Play audio
- my_media.play();
-
- // Pause after 10 seconds
- setTimeout(function () {
- my_media.pause();
- }, 10000);
- }
+ my_media.play();
+
+ // Pause after 10 seconds
+ setTimeout(function () {
+ my_media.pause();
+ }, 10000);
+}
+```
+
+## media.pauseRecord
+
+Pauses recording an audio file.
+
+ media.pauseRecord();
+
+
+### Supported Platforms
+
+- iOS
+### Quick Example
+
+```js
+// 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.
- media.play();
-
+```js
+media.play();
+```
### Quick Example
+```js
+// Play audio
+//
+function playAudio(url) {
+ // Play the audio file at url
+ var my_media = new Media(url,
+ // success callback
+ function () {
+ console.log("playAudio():Audio Success");
+ },
+ // error callback
+ function (err) {
+ console.log("playAudio():Audio Error: " + err);
+ }
+ );
// Play audio
- //
- function playAudio(url) {
- // Play the audio file at url
- var my_media = new Media(url,
- // success callback
- function () {
- console.log("playAudio():Audio Success");
- },
- // error callback
- function (err) {
- console.log("playAudio():Audio Error: " + err);
- }
- );
- // Play audio
- my_media.play();
- }
-
+ my_media.play();
+}
+```
### iOS Quirks
@@ -286,15 +388,61 @@ function for any `Media` resource that is no longer needed.
### Quick Example
- // Audio player
- //
- var my_media = new Media(src, onSuccess, onError);
+```js
+// Audio player
+//
+var my_media = new Media(src, onSuccess, onError);
- my_media.play();
- my_media.stop();
- my_media.release();
+my_media.play();
+my_media.stop();
+my_media.release();
+```
+
+## media.resumeRecord
+
+Resume recording an audio file.
+
+ media.resumeRecord();
+### Supported Platforms
+
+- iOS
+
+
+### Quick Example
+
+```js
+// 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.
@@ -308,15 +456,16 @@ Sets the current position within an audio file.
### Quick Example
- // Audio player
- //
- var my_media = new Media(src, onSuccess, onError);
- my_media.play();
- // SeekTo to 10 seconds after 5 seconds
- setTimeout(function() {
- my_media.seekTo(10000);
- }, 5000);
-
+```js
+// Audio player
+//
+var my_media = new Media(src, onSuccess, onError);
+ my_media.play();
+// SeekTo to 10 seconds after 5 seconds
+setTimeout(function() {
+ my_media.seekTo(10000);
+}, 5000);
+```
### BlackBerry 10 Quirks
@@ -339,34 +488,35 @@ Set the volume for an audio file.
### Quick Example
- // Play audio
- //
- function playAudio(url) {
- // Play the audio file at url
- var my_media = new Media(url,
- // success callback
- function() {
- console.log("playAudio():Audio Success");
- },
- // error callback
- function(err) {
- console.log("playAudio():Audio Error: "+err);
- });
-
- // Play audio
- my_media.play();
+```js
+// Play audio
+//
+function playAudio(url) {
+ // Play the audio file at url
+ var my_media = new Media(url,
+ // success callback
+ function() {
+ console.log("playAudio():Audio Success");
+ },
+ // error callback
+ function(err) {
+ console.log("playAudio():Audio Error: "+err);
+ });
- // Mute volume after 2 seconds
- setTimeout(function() {
- my_media.setVolume('0.0');
- }, 2000);
+ // Play audio
+ my_media.play();
- // Set volume to 1.0 after 5 seconds
- setTimeout(function() {
- my_media.setVolume('1.0');
- }, 5000);
- }
+ // Mute volume after 2 seconds
+ setTimeout(function() {
+ my_media.setVolume('0.0');
+ }, 2000);
+ // Set volume to 1.0 after 5 seconds
+ setTimeout(function() {
+ my_media.setVolume('1.0');
+ }, 5000);
+}
+```
## media.startRecord
@@ -383,25 +533,26 @@ Starts recording an audio file.
### 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();
- }
+```js
+// 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();
+}
+```
### Android Quirks
@@ -438,30 +589,31 @@ Stops playing an audio file.
### Quick Example
- // Play audio
- //
- function playAudio(url) {
- // Play the audio file at url
- var my_media = new Media(url,
- // success callback
- function() {
- console.log("playAudio():Audio Success");
- },
- // error callback
- function(err) {
- console.log("playAudio():Audio Error: "+err);
- }
- );
-
- // Play audio
- my_media.play();
+```js
+// Play audio
+//
+function playAudio(url) {
+ // Play the audio file at url
+ var my_media = new Media(url,
+ // success callback
+ function() {
+ console.log("playAudio():Audio Success");
+ },
+ // error callback
+ function(err) {
+ console.log("playAudio():Audio Error: "+err);
+ }
+ );
- // Pause after 10 seconds
- setTimeout(function() {
- my_media.stop();
- }, 10000);
- }
+ // Play audio
+ my_media.play();
+ // Pause after 10 seconds
+ setTimeout(function() {
+ my_media.stop();
+ }, 10000);
+}
+```
## media.stopRecord
@@ -478,31 +630,32 @@ Stops recording an audio file.
### 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();
+```js
+// 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);
+ }
+ );
- // Stop recording after 10 seconds
- setTimeout(function() {
- mediaRec.stopRecord();
- }, 10000);
- }
+ // Record audio
+ mediaRec.startRecord();
+ // Stop recording after 10 seconds
+ setTimeout(function() {
+ mediaRec.stopRecord();
+ }, 10000);
+}
+```
### Tizen Quirks
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5280960d/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 0e9a5f2..816912e 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
@@ -1,8 +1,10 @@
---
-edit_link: 'https://github.com/apache/cordova-plugin-network-information/blob/master/README.md'
-title: cordova-plugin-network-information
+edit_link: >-
+ https://github.com/apache/cordova-plugin-network-information/blob/master/README.md
+title: Network Information
plugin_name: cordova-plugin-network-information
plugin_version: master
+description: Get information about wireless connectivity.
---
<!-- WARNING: This file is generated. See fetch_docs.js. -->
@@ -26,7 +28,9 @@ plugin_version: master
# under the License.
-->
-[](https://travis-ci.org/apache/cordova-plugin-network-information)
+|Android|iOS| Windows 8.1 Store | Windows 8.1 Phone | Windows 10 Store | Travis CI |
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-network-information/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-network-information/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-store,PLUGIN=cordova-plugin-network-information/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-phone,PLUGIN=cordova-plugin-network-information/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-network-information/)|[](https://travis-ci.org/apache/cordova-plugin-network-information)|
# cordova-plugin-network-information
@@ -36,8 +40,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
@@ -80,24 +88,25 @@ connection state, and type of connection.
### Quick Example
- function checkConnection() {
- var networkState = navigator.connection.type;
+```js
+function checkConnection() {
+ var networkState = navigator.connection.type;
- var states = {};
- states[Connection.UNKNOWN] = 'Unknown connection';
- states[Connection.ETHERNET] = 'Ethernet connection';
- states[Connection.WIFI] = 'WiFi connection';
- states[Connection.CELL_2G] = 'Cell 2G connection';
- states[Connection.CELL_3G] = 'Cell 3G connection';
- states[Connection.CELL_4G] = 'Cell 4G connection';
- states[Connection.CELL] = 'Cell generic connection';
- states[Connection.NONE] = 'No network connection';
+ var states = {};
+ states[Connection.UNKNOWN] = 'Unknown connection';
+ states[Connection.ETHERNET] = 'Ethernet connection';
+ states[Connection.WIFI] = 'WiFi connection';
+ states[Connection.CELL_2G] = 'Cell 2G connection';
+ states[Connection.CELL_3G] = 'Cell 3G connection';
+ states[Connection.CELL_4G] = 'Cell 4G connection';
+ states[Connection.CELL] = 'Cell generic connection';
+ states[Connection.NONE] = 'No network connection';
- alert('Connection type: ' + states[networkState]);
- }
-
- checkConnection();
+ alert('Connection type: ' + states[networkState]);
+}
+checkConnection();
+```
### API Change
@@ -159,12 +168,13 @@ attach an event listener once the `deviceready` event fires.
### Quick Example
- document.addEventListener("offline", onOffline, false);
-
- function onOffline() {
- // Handle the offline event
- }
+```js
+document.addEventListener("offline", onOffline, false);
+function onOffline() {
+ // Handle the offline event
+}
+```
### iOS Quirks
@@ -198,12 +208,13 @@ attach an event listener once the `deviceready` event fires.
### Quick Example
- document.addEventListener("online", onOnline, false);
-
- function onOnline() {
- // Handle the online event
- }
+```js
+document.addEventListener("online", onOnline, false);
+function onOnline() {
+ // Handle the online event
+}
+```
### iOS Quirks
@@ -219,4 +230,119 @@ 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
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org