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-unsubscr...@cordova.apache.org For additional commands, e-mail: commits-h...@cordova.apache.org
