You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by ra...@apache.org on 2016/03/08 01:05:07 UTC
[08/11] docs commit: Moving dev to 6.x. This closes #537
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova-plugin-file.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/gen/cordova-plugin-file.md b/www/docs/en/6.x/gen/cordova-plugin-file.md
new file mode 100644
index 0000000..ad78498
--- /dev/null
+++ b/www/docs/en/6.x/gen/cordova-plugin-file.md
@@ -0,0 +1,547 @@
+---
+edit_link: 'https://github.com/apache/cordova-plugin-file/blob/master/README.md'
+permalink: /docs/en/6.x/cordova-plugin-file/index.html
+plugin_name: cordova-plugin-file
+plugin_version: master
+---
+
+<!--
+# license: Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+-->
+
+[](https://travis-ci.org/apache/cordova-plugin-file)
+
+# cordova-plugin-file
+
+This plugin implements a File API allowing read/write access to files residing on the device.
+
+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
+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:
+[http://www.w3.org/TR/2011/WD-file-system-api-20110419/](http://www.w3.org/TR/2011/WD-file-system-api-20110419/)
+
+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/)
+
+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).
+
+This plugin defines global `cordova.file` object.
+
+Although in the global scope, it is not available until after the `deviceready` event.
+
+ document.addEventListener("deviceready", onDeviceReady, false);
+ function onDeviceReady() {
+ console.log(cordova.file);
+ }
+
+Report issues on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20File%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC)
+
+## Installation
+
+ cordova plugin add cordova-plugin-file
+
+## Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- Firefox OS
+- iOS
+- OS X
+- Windows Phone 7 and 8*
+- Windows 8*
+- Windows*
+- Browser
+
+\* _These platforms do not support `FileReader.readAsArrayBuffer` nor `FileWriter.write(blob)`._
+
+## Where to Store Files
+
+As of v1.2.0, URLs to important file-system directories are provided.
+Each URL is in the form _file:///path/to/spot/_, and can be converted to a
+`DirectoryEntry` using `window.resolveLocalFileSystemURL()`.
+
+* `cordova.file.applicationDirectory` - Read-only directory where the application
+ is installed. (_iOS_, _Android_, _BlackBerry 10_, _OSX_, _windows_)
+
+* `cordova.file.applicationStorageDirectory` - Root directory of the application's
+ sandbox; on iOS & windows this location is read-only (but specific subdirectories [like
+ `/Documents` on iOS or `/localState` on windows] are read-write). All data contained within
+ is private to the app. (_iOS_, _Android_, _BlackBerry 10_, _OSX_)
+
+* `cordova.file.dataDirectory` - Persistent and private data storage within the
+ application's sandbox using internal memory (on Android, if you need to use
+ external memory, use `.externalDataDirectory`). On iOS, this directory is not
+ synced with iCloud (use `.syncedDataDirectory`). (_iOS_, _Android_, _BlackBerry 10_, _windows_)
+
+* `cordova.file.cacheDirectory` - Directory for cached data files or any files
+ that your app can re-create easily. The OS may delete these files when the device
+ runs low on storage, nevertheless, apps should not rely on the OS to delete files
+ in here. (_iOS_, _Android_, _BlackBerry 10_, _OSX_, _windows_)
+
+* `cordova.file.externalApplicationStorageDirectory` - Application space on
+ external storage. (_Android_)
+
+* `cordova.file.externalDataDirectory` - Where to put app-specific data files on
+ external storage. (_Android_)
+
+* `cordova.file.externalCacheDirectory` - Application cache on external storage.
+ (_Android_)
+
+* `cordova.file.externalRootDirectory` - External storage (SD card) root. (_Android_, _BlackBerry 10_)
+
+* `cordova.file.tempDirectory` - Temp directory that the OS can clear at will. Do not
+ rely on the OS to clear this directory; your app should always remove files as
+ applicable. (_iOS_, _OSX_, _windows_)
+
+* `cordova.file.syncedDataDirectory` - Holds app-specific files that should be synced
+ (e.g. to iCloud). (_iOS_, _windows_)
+
+* `cordova.file.documentsDirectory` - Files private to the app, but that are meaningful
+ to other application (e.g. Office files). Note that for _OSX_ this is the user's `~/Documents` directory. (_iOS_, _OSX_)
+
+* `cordova.file.sharedDirectory` - Files globally available to all applications (_BlackBerry 10_)
+
+## File System Layouts
+
+Although technically an implementation detail, it can be very useful to know how
+the `cordova.file.*` properties map to physical paths on a real device.
+
+### iOS File System Layout
+
+| Device Path | `cordova.file.*` | `iosExtraFileSystems` | r/w? | persistent? | OS clears | sync | private |
+|:-----------------------------------------------|:----------------------------|:----------------------|:----:|:-----------:|:---------:|:----:|:-------:|
+| `/var/mobile/Applications/<UUID>/` | applicationStorageDirectory | - | r | N/A | N/A | N/A | Yes |
+| `appname.app/` | applicationDirectory | bundle | r | N/A | N/A | N/A | Yes |
+| `www/` | - | - | r | N/A | N/A | N/A | Yes |
+| `Documents/` | documentsDirectory | documents | r/w | Yes | No | Yes | Yes |
+| `NoCloud/` | - | documents-nosync | r/w | Yes | No | No | Yes |
+| `Library` | - | library | r/w | Yes | No | Yes? | Yes |
+| `NoCloud/` | dataDirectory | library-nosync | r/w | Yes | No | No | Yes |
+| `Cloud/` | syncedDataDirectory | - | r/w | Yes | No | Yes | Yes |
+| `Caches/` | cacheDirectory | cache | r/w | Yes* | Yes\*\*\*| No | Yes |
+| `tmp/` | tempDirectory | - | r/w | No\*\* | Yes\*\*\*| No | Yes |
+
+
+ \* Files persist across app restarts and upgrades, but this directory can
+ be cleared whenever the OS desires. Your app should be able to recreate any
+ content that might be deleted.
+
+\*\* Files may persist across app restarts, but do not rely on this behavior. Files
+ are not guaranteed to persist across updates. Your app should remove files from
+ this directory when it is applicable, as the OS does not guarantee when (or even
+ if) these files are removed.
+
+\*\*\* The OS may clear the contents of this directory whenever it feels it is
+ necessary, but do not rely on this. You should clear this directory as
+ appropriate for your application.
+
+### Android File System Layout
+
+| Device Path | `cordova.file.*` | `AndroidExtraFileSystems` | r/w? | persistent? | OS clears | private |
+|:------------------------------------------------|:----------------------------|:--------------------------|:----:|:-----------:|:---------:|:-------:|
+| `file:///android_asset/` | applicationDirectory | | r | N/A | N/A | Yes |
+| `/data/data/<app-id>/` | applicationStorageDirectory | - | r/w | N/A | N/A | Yes |
+| `cache` | cacheDirectory | cache | r/w | Yes | Yes\* | Yes |
+| `files` | dataDirectory | files | r/w | Yes | No | Yes |
+| `Documents` | | documents | r/w | Yes | No | Yes |
+| `<sdcard>/` | externalRootDirectory | sdcard | r/w | Yes | No | No |
+| `Android/data/<app-id>/` | externalApplicationStorageDirectory | - | r/w | Yes | No | No |
+| `cache` | externalCacheDirectry | cache-external | r/w | Yes | No\*\*| No |
+| `files` | externalDataDirectory | files-external | r/w | Yes | No | No |
+
+\* The OS may periodically clear this directory, but do not rely on this behavior. Clear
+ the contents of this directory as appropriate for your application. Should a user
+ purge the cache manually, the contents of this directory are removed.
+
+\*\* The OS does not clear this directory automatically; you are responsible for managing
+ the contents yourself. Should the user purge the cache manually, the contents of the
+ directory are removed.
+
+**Note**: If external storage can't be mounted, the `cordova.file.external*`
+properties are `null`.
+
+### BlackBerry 10 File System Layout
+
+| Device Path | `cordova.file.*` | r/w? | persistent? | OS clears | private |
+|:-------------------------------------------------------------|:----------------------------|:----:|:-----------:|:---------:|:-------:|
+| `file:///accounts/1000/appdata/<app id>/` | applicationStorageDirectory | r | N/A | N/A | Yes |
+| `app/native` | applicationDirectory | r | N/A | N/A | Yes |
+| `data/webviews/webfs/temporary/local__0` | cacheDirectory | r/w | No | Yes | Yes |
+| `data/webviews/webfs/persistent/local__0` | dataDirectory | r/w | Yes | No | Yes |
+| `file:///accounts/1000/removable/sdcard` | externalRemovableDirectory | r/w | Yes | No | No |
+| `file:///accounts/1000/shared` | sharedDirectory | r/w | Yes | No | No |
+
+*Note*: When application is deployed to work perimeter, all paths are relative to /accounts/1000-enterprise.
+
+### OS X File System Layout
+
+| Device Path | `cordova.file.*` | `iosExtraFileSystems` | r/w? | OS clears | private |
+|:-------------------------------------------------|:----------------------------|:----------------------|:----:|:---------:|:-------:|
+| `/Applications/<appname>.app/` | - | bundle | r | N/A | Yes |
+| `Content/Resources/` | applicationDirectory | - | r | N/A | Yes |
+| `~/Library/Application Support/<bundle-id>/` | applicationStorageDirectory | - | r/w | No | Yes |
+| `files/` | dataDirectory | - | r/w | No | Yes |
+| `~/Documents/` | documentsDirectory | documents | r/w | No | No |
+| `~/Library/Caches/<bundle-id>/` | cacheDirectory | cache | r/w | No | Yes |
+| `/tmp/` | tempDirectory | - | r/w | Yes\* | Yes |
+| `/` | rootDirectory | root | r/w | No\*\* | No |
+
+**Note**: This is the layout for non sandboxed applications. I you enable sandboxing, the `applicationStorageDirectory` will be below ` ~/Library/Containers/<bundle-id>/Data/Library/Application Support`.
+
+\* Files persist across app restarts and upgrades, but this directory can
+ be cleared whenever the OS desires. Your app should be able to recreate any
+ content that might be deleted. You should clear this directory as
+ appropriate for your application.
+
+\*\* Allows access to the entire file system. This is only available for non sandboxed apps.
+
+### Windows File System Layout
+
+| Device Path | `cordova.file.*` | r/w? | persistent? | OS clears | private |
+|:------------------------------------------------------|:----------------------------|:----:|:-----------:|:---------:|:-------:|
+| `ms-appdata:///` | applicationDirectory | r | N/A | N/A | Yes |
+| `local/` | dataDirectory | r/w | Yes | No | Yes |
+| `temp/` | cacheDirectory | r/w | No | Yes\* | Yes |
+| `temp/` | tempDirectory | r/w | No | Yes\* | Yes |
+| `roaming/` | syncedDataDirectory | r/w | Yes | No | Yes |
+
+\* The OS may periodically clear this directory
+
+
+## Android Quirks
+
+### Android Persistent storage location
+
+There are multiple valid locations to store persistent files on an Android
+device. See [this page](http://developer.android.com/guide/topics/data/data-storage.html)
+for an extensive discussion of the various possibilities.
+
+Previous versions of the plugin would choose the location of the temporary and
+persistent files on startup, based on whether the device claimed that the SD
+Card (or equivalent storage partition) was mounted. If the SD Card was mounted,
+or if a large internal storage partition was available (such as on Nexus
+devices,) then the persistent files would be stored in the root of that space.
+This meant that all Cordova apps could see all of the files available on the
+card.
+
+If the SD card was not available, then previous versions would store data under
+`/data/data/<packageId>`, which isolates apps from each other, but may still
+cause data to be shared between users.
+
+It is now possible to choose whether to store files in the internal file
+storage location, or using the previous logic, with a preference in your
+application's `config.xml` file. To do this, add one of these two lines to
+`config.xml`:
+
+ <preference name="AndroidPersistentFileLocation" value="Internal" />
+
+ <preference name="AndroidPersistentFileLocation" value="Compatibility" />
+
+Without this line, the File plugin will use `Internal` as the default. If
+a preference tag is present, and is not one of these values, the application
+will not start.
+
+If your application has previously been shipped to users, using an older (pre-
+3.0.0) version of this plugin, and has stored files in the persistent filesystem,
+then you should set the preference to `Compatibility` if your config.xml does not specify a location for the persistent filesystem. Switching the location to
+"Internal" would mean that existing users who upgrade their application may be
+unable to access their previously-stored files, depending on their device.
+
+If your application is new, or has never previously stored files in the
+persistent filesystem, then the `Internal` setting is generally recommended.
+
+### Slow recursive operations for /android_asset
+
+Listing asset directories is really slow on Android. You can speed it up though, by
+adding `src/android/build-extras.gradle` to the root of your android project (also
+requires cordova-android@4.0.0 or greater).
+
+## iOS Quirks
+
+- `cordova.file.applicationStorageDirectory` is read-only; attempting to store
+ files within the root directory will fail. Use one of the other `cordova.file.*`
+ properties defined for iOS (only `applicationDirectory` and `applicationStorageDirectory` are
+ read-only).
+- `FileReader.readAsText(blob, encoding)`
+ - The `encoding` parameter is not supported, and UTF-8 encoding is always in effect.
+
+### iOS Persistent storage location
+
+There are two valid locations to store persistent files on an iOS device: the
+Documents directory and the Library directory. Previous versions of the plugin
+only ever stored persistent files in the Documents directory. This had the
+side-effect of making all of an application's files visible in iTunes, which
+was often unintended, especially for applications which handle lots of small
+files, rather than producing complete documents for export, which is the
+intended purpose of the directory.
+
+It is now possible to choose whether to store files in the documents or library
+directory, with a preference in your application's `config.xml` file. To do this,
+add one of these two lines to `config.xml`:
+
+ <preference name="iosPersistentFileLocation" value="Library" />
+
+ <preference name="iosPersistentFileLocation" value="Compatibility" />
+
+Without this line, the File plugin will use `Compatibility` as the default. If
+a preference tag is present, and is not one of these values, the application
+will not start.
+
+If your application has previously been shipped to users, using an older (pre-
+1.0) version of this plugin, and has stored files in the persistent filesystem,
+then you should set the preference to `Compatibility`. Switching the location to
+`Library` would mean that existing users who upgrade their application would be
+unable to access their previously-stored files.
+
+If your application is new, or has never previously stored files in the
+persistent filesystem, then the `Library` setting is generally recommended.
+
+## Firefox OS Quirks
+
+The File System API is not natively supported by Firefox OS and is implemented
+as a shim on top of indexedDB.
+
+* Does not fail when removing non-empty directories
+* Does not support metadata for directories
+* Methods `copyTo` and `moveTo` do not support directories
+
+The following data paths are supported:
+* `applicationDirectory` - Uses `xhr` to get local files that are packaged with the app.
+* `dataDirectory` - For persistent app-specific data files.
+* `cacheDirectory` - Cached files that should survive app restarts (Apps should not rely
+on the OS to delete files in here).
+
+## Browser Quirks
+
+### Common quirks and remarks
+- Each browser uses its own sandboxed filesystem. IE and Firefox use IndexedDB as a base.
+All browsers use forward slash as directory separator in a path.
+- Directory entries have to be created successively.
+For example, the call `fs.root.getDirectory('dir1/dir2', {create:true}, successCallback, errorCallback)`
+will fail if dir1 did not exist.
+- The plugin requests user permission to use persistent storage at the application first start.
+- Plugin supports `cdvfile://localhost` (local resources) only. I.e. external resources are not supported via `cdvfile`.
+- The plugin does not follow ["File System API 8.3 Naming restrictions"](http://www.w3.org/TR/2011/WD-file-system-api-20110419/#naming-restrictions).
+- Blob and File' `close` function is not supported.
+- `FileSaver` and `BlobBuilder` are not supported by this plugin and don't have stubs.
+- The plugin does not support `requestAllFileSystems`. This function is also missing in the specifications.
+- Entries in directory will not be removed if you use `create: true` flag for existing directory.
+- Files created via constructor are not supported. You should use entry.file method instead.
+- Each browser uses its own form for blob URL references.
+- `readAsDataURL` function is supported, but the mediatype in Chrome depends on entry name extension,
+mediatype in IE is always empty (which is the same as `text-plain` according the specification),
+the mediatype in Firefox is always `application/octet-stream`.
+For example, if the content is `abcdefg` then Firefox returns `data:application/octet-stream;base64,YWJjZGVmZw==`,
+IE returns `data:;base64,YWJjZGVmZw==`, Chrome returns `data:<mediatype depending on extension of entry name>;base64,YWJjZGVmZw==`.
+- `toInternalURL` returns the path in the form `file:///persistent/path/to/entry` (Firefox, IE).
+Chrome returns the path in the form `cdvfile://localhost/persistent/file`.
+
+### Chrome quirks
+- Chrome filesystem is not immediately ready after device ready event. As a workaround you can subscribe to `filePluginIsReady` event.
+Example:
+```javascript
+window.addEventListener('filePluginIsReady', function(){ console.log('File plugin is ready');}, false);
+```
+You can use `window.isFilePluginReadyRaised` function to check whether event was already raised.
+- window.requestFileSystem TEMPORARY and PERSISTENT filesystem quotas are not limited in Chrome.
+- To increase persistent storage in Chrome you need to call `window.initPersistentFileSystem` method. Persistent storage quota is 5 MB by default.
+- Chrome requires `--allow-file-access-from-files` run argument to support API via `file:///` protocol.
+- `File` object will be not changed if you use flag `{create:true}` when getting an existing `Entry`.
+- events `cancelable` property is set to true in Chrome. This is contrary to the [specification](http://dev.w3.org/2009/dap/file-system/file-writer.html).
+- `toURL` function in Chrome returns `filesystem:`-prefixed path depending on application host.
+For example, `filesystem:file:///persistent/somefile.txt`, `filesystem:http://localhost:8080/persistent/somefile.txt`.
+- `toURL` function result does not contain trailing slash in case of directory entry.
+Chrome resolves directories with slash-trailed urls correctly though.
+- `resolveLocalFileSystemURL` method requires the inbound `url` to have `filesystem` prefix. For example, `url` parameter for `resolveLocalFileSystemURL`
+should be in the form `filesystem:file:///persistent/somefile.txt` as opposed to the form `file:///persistent/somefile.txt` in Android.
+- Deprecated `toNativeURL` function is not supported and does not have a stub.
+- `setMetadata` function is not stated in the specifications and not supported.
+- INVALID_MODIFICATION_ERR (code: 9) is thrown instead of SYNTAX_ERR(code: 8) on requesting of a non-existant filesystem.
+- INVALID_MODIFICATION_ERR (code: 9) is thrown instead of PATH_EXISTS_ERR(code: 12) on trying to exclusively create a file or directory, which already exists.
+- INVALID_MODIFICATION_ERR (code: 9) is thrown instead of NO_MODIFICATION_ALLOWED_ERR(code: 6) on trying to call removeRecursively on the root file system.
+- INVALID_MODIFICATION_ERR (code: 9) is thrown instead of NOT_FOUND_ERR(code: 1) on trying to moveTo directory that does not exist.
+
+### IndexedDB-based impl quirks (Firefox and IE)
+- `.` and `..` are not supported.
+- IE does not support `file:///`-mode; only hosted mode is supported (http://localhost:xxxx).
+- Firefox filesystem size is not limited but each 50MB extension will request a user permission.
+IE10 allows up to 10mb of combined AppCache and IndexedDB used in implementation of filesystem without prompting,
+once you hit that level you will be asked if you want to allow it to be increased up to a max of 250mb per site.
+So `size` parameter for `requestFileSystem` function does not affect filesystem in Firefox and IE.
+- `readAsBinaryString` function is not stated in the Specs and not supported in IE and does not have a stub.
+- `file.type` is always null.
+- You should not create entry using DirectoryEntry instance callback result which was deleted.
+Otherwise, you will get a 'hanging entry'.
+- Before you can read a file, which was just written you need to get a new instance of this file.
+- `setMetadata` function, which is not stated in the Specs supports `modificationTime` field change only.
+- `copyTo` and `moveTo` functions do not support directories.
+- Directories metadata is not supported.
+- Both Entry.remove and directoryEntry.removeRecursively don't fail when removing
+non-empty directories - directories being removed are cleaned along with contents instead.
+- `abort` and `truncate` functions are not supported.
+- progress events are not fired. For example, this handler will be not executed:
+```javascript
+writer.onprogress = function() { /*commands*/ };
+```
+
+## Upgrading Notes
+
+In v1.0.0 of this plugin, the `FileEntry` and `DirectoryEntry` structures have changed,
+to be more in line with the published specification.
+
+Previous (pre-1.0.0) versions of the plugin stored the device-absolute-file-location
+in the `fullPath` property of `Entry` objects. These paths would typically look like
+
+ /var/mobile/Applications/<application UUID>/Documents/path/to/file (iOS)
+ /storage/emulated/0/path/to/file (Android)
+
+These paths were also returned by the `toURL()` method of the `Entry` objects.
+
+With v1.0.0, the `fullPath` attribute is the path to the file, _relative to the root of
+the HTML filesystem_. So, the above paths would now both be represented by a `FileEntry`
+object with a `fullPath` of
+
+ /path/to/file
+
+If your application works with device-absolute-paths, and you previously retrieved those
+paths through the `fullPath` property of `Entry` objects, then you should update your code
+to use `entry.toURL()` instead.
+
+For backwards compatibility, the `resolveLocalFileSystemURL()` method will accept a
+device-absolute-path, and will return an `Entry` object corresponding to it, as long as that
+file exists within either the `TEMPORARY` or `PERSISTENT` filesystems.
+
+This has particularly been an issue with the File-Transfer plugin, which previously used
+device-absolute-paths (and can still accept them). It has been updated to work correctly
+with FileSystem URLs, so replacing `entry.fullPath` with `entry.toURL()` should resolve any
+issues getting that plugin to work with files on the device.
+
+In v1.1.0 the return value of `toURL()` was changed (see [CB-6394](https://issues.apache.org/jira/browse/CB-6394))
+to return an absolute 'file://' URL. wherever possible. To ensure a 'cdvfile:'-URL you can use `toInternalURL()` now.
+This method will now return filesystem URLs of the form
+
+ cdvfile://localhost/persistent/path/to/file
+
+which can be used to identify the file uniquely.
+
+## cdvfile protocol
+**Purpose**
+
+`cdvfile://localhost/persistent|temporary|another-fs-root*/path/to/file` can be used for platform-independent file paths.
+cdvfile paths are supported by core plugins - for example you can download an mp3 file to cdvfile-path via `cordova-plugin-file-transfer` and play it via `cordova-plugin-media`.
+
+__*Note__: See [Where to Store Files](#where-to-store-files), [File System Layouts](#file-system-layouts) and [Configuring the Plugin](#configuring-the-plugin-optional) for more details about available fs roots.
+
+To use `cdvfile` as a tag' `src` you can convert it to native path via `toURL()` method of the resolved fileEntry, which you can get via `resolveLocalFileSystemURL` - see examples below.
+
+You can also use `cdvfile://` paths directly in the DOM, for example:
+```HTML
+<img src="cdvfile://localhost/persistent/img/logo.png" />
+```
+
+__Note__: This method requires following Content Security rules updates:
+* Add `cdvfile:` scheme to `Content-Security-Policy` meta tag of the index page, e.g.:
+ - `<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: `**cdvfile:**` https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">`
+* Add `<access origin="cdvfile://*" />` to `config.xml`.
+
+**Converting cdvfile:// to native path**
+
+```javascript
+resolveLocalFileSystemURL('cdvfile://localhost/temporary/path/to/file.mp4', function(entry) {
+ var nativePath = entry.toURL();
+ console.log('Native URI: ' + nativePath);
+ document.getElementById('video').src = nativePath;
+```
+
+**Converting native path to cdvfile://**
+
+```javascript
+resolveLocalFileSystemURL(nativePath, function(entry) {
+ console.log('cdvfile URI: ' + entry.toInternalURL());
+```
+
+**Using cdvfile in core plugins**
+
+```javascript
+fileTransfer.download(uri, 'cdvfile://localhost/temporary/path/to/file.mp3', function (entry) { ...
+```
+```javascript
+var my_media = new Media('cdvfile://localhost/temporary/path/to/file.mp3', ...);
+my_media.play();
+```
+
+#### cdvfile quirks
+- Using `cdvfile://` paths in the DOM is not supported on Windows platform (a path can be converted to native instead).
+
+
+## List of Error Codes and Meanings
+When an error is thrown, one of the following codes will be used.
+
+| Code | Constant |
+|-----:|:------------------------------|
+| 1 | `NOT_FOUND_ERR` |
+| 2 | `SECURITY_ERR` |
+| 3 | `ABORT_ERR` |
+| 4 | `NOT_READABLE_ERR` |
+| 5 | `ENCODING_ERR` |
+| 6 | `NO_MODIFICATION_ALLOWED_ERR` |
+| 7 | `INVALID_STATE_ERR` |
+| 8 | `SYNTAX_ERR` |
+| 9 | `INVALID_MODIFICATION_ERR` |
+| 10 | `QUOTA_EXCEEDED_ERR` |
+| 11 | `TYPE_MISMATCH_ERR` |
+| 12 | `PATH_EXISTS_ERR` |
+
+## Configuring the Plugin (Optional)
+
+The set of available filesystems can be configured per-platform. Both iOS and
+Android recognize a <preference> tag in `config.xml` which names the
+filesystems to be installed. By default, all file-system roots are enabled.
+
+ <preference name="iosExtraFilesystems" value="library,library-nosync,documents,documents-nosync,cache,bundle,root" />
+ <preference name="AndroidExtraFilesystems" value="files,files-external,documents,sdcard,cache,cache-external,root" />
+
+### Android
+
+* `files`: The application's internal file storage directory
+* `files-external`: The application's external file storage directory
+* `sdcard`: The global external file storage directory (this is the root of the SD card, if one is installed). You must have the `android.permission.WRITE_EXTERNAL_STORAGE` permission to use this.
+* `cache`: The application's internal cache directory
+* `cache-external`: The application's external cache directory
+* `root`: The entire device filesystem
+
+Android also supports a special filesystem named "documents", which represents a "/Documents/" subdirectory within the "files" filesystem.
+
+### iOS
+
+* `library`: The application's Library directory
+* `documents`: The application's Documents directory
+* `cache`: The application's Cache directory
+* `bundle`: The application's bundle; the location of the app itself on disk (read-only)
+* `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.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova-plugin-geolocation.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/gen/cordova-plugin-geolocation.md b/www/docs/en/6.x/gen/cordova-plugin-geolocation.md
new file mode 100644
index 0000000..c8fbdb4
--- /dev/null
+++ b/www/docs/en/6.x/gen/cordova-plugin-geolocation.md
@@ -0,0 +1,305 @@
+---
+edit_link: 'https://github.com/apache/cordova-plugin-geolocation/blob/master/README.md'
+permalink: /docs/en/6.x/cordova-plugin-geolocation/index.html
+plugin_name: cordova-plugin-geolocation
+plugin_version: master
+---
+
+<!--
+# license: Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+-->
+
+[](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
+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.
+
+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.
+
+__WARNING__: Collection and use of geolocation data
+raises important privacy issues. Your app's privacy policy should
+discuss how the app uses geolocation data, whether it is shared with
+any other parties, and the level of precision of the data (for
+example, coarse, fine, ZIP code level, etc.). Geolocation data is
+generally considered sensitive because it can reveal user's
+whereabouts and, if stored, the history of their travels.
+Therefore, in addition to the app's privacy policy, you should
+strongly consider providing a just-in-time notice before the app
+accesses geolocation data (if the device operating system doesn't do
+so already). That notice should provide the same information noted
+above, as well as obtaining the user's permission (e.g., by presenting
+choices for __OK__ and __No Thanks__). For more information, please
+see the [Privacy Guide](http://cordova.apache.org/docs/en/latest/guide/appdev/privacy/index.html).
+
+This plugin defines a global `navigator.geolocation` object (for platforms
+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.
+
+ document.addEventListener("deviceready", onDeviceReady, false);
+ function onDeviceReady() {
+ console.log("navigator.geolocation works well");
+ }
+
+## Installation
+
+This requires cordova 5.0+ ( current stable 1.0.0 )
+
+ cordova plugin add cordova-plugin-geolocation
+
+Older versions of cordova can still install via the deprecated id ( stale 0.3.12 )
+
+ cordova plugin add org.apache.cordova.geolocation
+
+It is also possible to install via repo url directly ( unstable )
+
+ cordova plugin add https://github.com/apache/cordova-plugin-geolocation.git
+
+## Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- Firefox OS
+- iOS
+- Tizen
+- Windows Phone 7 and 8
+- Windows
+
+## Methods
+
+- navigator.geolocation.getCurrentPosition
+- navigator.geolocation.watchPosition
+- navigator.geolocation.clearWatch
+
+## Objects (Read-Only)
+
+- Position
+- PositionError
+- Coordinates
+
+## navigator.geolocation.getCurrentPosition
+
+Returns the device's current position to the `geolocationSuccess`
+callback with a `Position` object as the parameter. If there is an
+error, the `geolocationError` callback is passed a
+`PositionError` object.
+
+ navigator.geolocation.getCurrentPosition(geolocationSuccess,
+ [geolocationError],
+ [geolocationOptions]);
+
+### Parameters
+
+- __geolocationSuccess__: The callback that is passed the current position.
+
+- __geolocationError__: _(Optional)_ The callback that executes if an error occurs.
+
+- __geolocationOptions__: _(Optional)_ The geolocation options.
+
+
+### Example
+
+ // onSuccess Callback
+ // This method accepts a Position object, which contains the
+ // current GPS coordinates
+ //
+ var onSuccess = function(position) {
+ alert('Latitude: ' + position.coords.latitude + '\n' +
+ 'Longitude: ' + position.coords.longitude + '\n' +
+ 'Altitude: ' + position.coords.altitude + '\n' +
+ 'Accuracy: ' + position.coords.accuracy + '\n' +
+ 'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '\n' +
+ 'Heading: ' + position.coords.heading + '\n' +
+ 'Speed: ' + position.coords.speed + '\n' +
+ 'Timestamp: ' + position.timestamp + '\n');
+ };
+
+ // onError Callback receives a PositionError object
+ //
+ function onError(error) {
+ alert('code: ' + error.code + '\n' +
+ 'message: ' + error.message + '\n');
+ }
+
+ navigator.geolocation.getCurrentPosition(onSuccess, onError);
+
+### Android Quirks
+
+If Geolocation service is turned off the `onError` callback is invoked after `timeout` interval (if specified).
+If `timeout` parameter is not specified then no callback is called.
+
+## navigator.geolocation.watchPosition
+
+Returns the device's current position when a change in position is detected.
+When the device retrieves a new location, the `geolocationSuccess`
+callback executes with a `Position` object as the parameter. If
+there is an error, the `geolocationError` callback executes with a
+`PositionError` object as the parameter.
+
+ var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
+ [geolocationError],
+ [geolocationOptions]);
+
+### Parameters
+
+- __geolocationSuccess__: The callback that is passed the current position.
+
+- __geolocationError__: (Optional) The callback that executes if an error occurs.
+
+- __geolocationOptions__: (Optional) The geolocation options.
+
+### Returns
+
+- __String__: returns a watch id that references the watch position interval. The watch id should be used with `navigator.geolocation.clearWatch` to stop watching for changes in position.
+
+### Example
+
+ // onSuccess Callback
+ // This method accepts a `Position` object, which contains
+ // the current GPS coordinates
+ //
+ function onSuccess(position) {
+ var element = document.getElementById('geolocation');
+ element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
+ 'Longitude: ' + position.coords.longitude + '<br />' +
+ '<hr />' + element.innerHTML;
+ }
+
+ // onError Callback receives a PositionError object
+ //
+ function onError(error) {
+ alert('code: ' + error.code + '\n' +
+ 'message: ' + error.message + '\n');
+ }
+
+ // Options: throw an error if no update is received every 30 seconds.
+ //
+ var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { timeout: 30000 });
+
+
+## geolocationOptions
+
+Optional parameters to customize the retrieval of the geolocation
+`Position`.
+
+ { maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };
+
+### Options
+
+- __enableHighAccuracy__: Provides a hint that the application needs the best possible results. By default, the device attempts to retrieve a `Position` using network-based methods. Setting this property to `true` tells the framework to use more accurate methods, such as satellite positioning. _(Boolean)_
+
+- __timeout__: The maximum length of time (milliseconds) that is allowed to pass from the call to `navigator.geolocation.getCurrentPosition` or `geolocation.watchPosition` until the corresponding `geolocationSuccess` callback executes. If the `geolocationSuccess` callback is not invoked within this time, the `geolocationError` callback is passed a `PositionError.TIMEOUT` error code. (Note that when used in conjunction with `geolocation.watchPosition`, the `geolocationError` callback could be called on an interval every `timeout` milliseconds!) _(Number)_
+
+- __maximumAge__: Accept a cached position whose age is no greater than the specified time in milliseconds. _(Number)_
+
+### Android Quirks
+
+If Geolocation service is turned off the `onError` callback is invoked after `timeout` interval (if specified).
+If `timeout` parameter is not specified then no callback is called.
+
+## navigator.geolocation.clearWatch
+
+Stop watching for changes to the device's location referenced by the
+`watchID` parameter.
+
+ navigator.geolocation.clearWatch(watchID);
+
+### Parameters
+
+- __watchID__: The id of the `watchPosition` interval to clear. (String)
+
+### Example
+
+ // Options: watch for changes in position, and use the most
+ // accurate position acquisition method available.
+ //
+ var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { enableHighAccuracy: true });
+
+ // ...later on...
+
+ navigator.geolocation.clearWatch(watchID);
+
+## Position
+
+Contains `Position` coordinates and timestamp, created by the geolocation API.
+
+### Properties
+
+- __coords__: A set of geographic coordinates. _(Coordinates)_
+
+- __timestamp__: Creation timestamp for `coords`. _(DOMTimeStamp)_
+
+## Coordinates
+
+A `Coordinates` object is attached to a `Position` object that is
+available to callback functions in requests for the current position.
+It contains a set of properties that describe the geographic coordinates of a position.
+
+### Properties
+
+* __latitude__: Latitude in decimal degrees. _(Number)_
+
+* __longitude__: Longitude in decimal degrees. _(Number)_
+
+* __altitude__: Height of the position in meters above the ellipsoid. _(Number)_
+
+* __accuracy__: Accuracy level of the latitude and longitude coordinates in meters. _(Number)_
+
+* __altitudeAccuracy__: Accuracy level of the altitude coordinate in meters. _(Number)_
+
+* __heading__: Direction of travel, specified in degrees counting clockwise relative to the true north. _(Number)_
+
+* __speed__: Current ground speed of the device, specified in meters per second. _(Number)_
+
+### Amazon Fire OS Quirks
+
+__altitudeAccuracy__: Not supported by Android devices, returning `null`.
+
+### Android Quirks
+
+__altitudeAccuracy__: Not supported by Android devices, returning `null`.
+
+## PositionError
+
+The `PositionError` object is passed to the `geolocationError`
+callback function when an error occurs with navigator.geolocation.
+
+### Properties
+
+- __code__: One of the predefined error codes listed below.
+
+- __message__: Error message describing the details of the error encountered.
+
+### Constants
+
+- `PositionError.PERMISSION_DENIED`
+ - Returned when users do not allow the app to retrieve position information. This is dependent on the platform.
+- `PositionError.POSITION_UNAVAILABLE`
+ - 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.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova-plugin-globalization.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/gen/cordova-plugin-globalization.md b/www/docs/en/6.x/gen/cordova-plugin-globalization.md
new file mode 100644
index 0000000..1500cf8
--- /dev/null
+++ b/www/docs/en/6.x/gen/cordova-plugin-globalization.md
@@ -0,0 +1,941 @@
+---
+edit_link: 'https://github.com/apache/cordova-plugin-globalization/blob/master/README.md'
+permalink: /docs/en/6.x/cordova-plugin-globalization/index.html
+plugin_name: cordova-plugin-globalization
+plugin_version: master
+---
+
+<!--
+# license: Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+-->
+
+[](https://travis-ci.org/apache/cordova-plugin-globalization)
+
+# cordova-plugin-globalization
+
+This plugin obtains information and performs operations specific to the user's
+locale, language, and timezone. Note the difference between locale and language:
+locale controls how numbers, dates, and times are displayed for a region, while
+language determines what language text appears as, independently of locale settings.
+Often developers use locale to set both settings, but there is no reason a user
+couldn't set her language to "English" but locale to "French", so that text is
+displayed in English but dates, times, etc., are displayed as they are in France.
+Unfortunately, most mobile platforms currently do not make a distinction between
+these settings.
+
+This plugin defines global `navigator.globalization` object.
+
+Although in the global scope, it is not available until after the `deviceready` event.
+
+ document.addEventListener("deviceready", onDeviceReady, false);
+ function onDeviceReady() {
+ console.log(navigator.globalization);
+ }
+
+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%20Globalization%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC)
+
+
+## Installation
+
+ cordova plugin add cordova-plugin-globalization
+
+## Objects
+
+- GlobalizationError
+
+## Methods
+
+- navigator.globalization.getPreferredLanguage
+- navigator.globalization.getLocaleName
+- navigator.globalization.dateToString
+- navigator.globalization.stringToDate
+- navigator.globalization.getDatePattern
+- navigator.globalization.getDateNames
+- navigator.globalization.isDayLightSavingsTime
+- navigator.globalization.getFirstDayOfWeek
+- navigator.globalization.numberToString
+- navigator.globalization.stringToNumber
+- navigator.globalization.getNumberPattern
+- navigator.globalization.getCurrencyPattern
+
+## navigator.globalization.getPreferredLanguage
+
+Get the BCP 47 language tag for the client's current language.
+
+ navigator.globalization.getPreferredLanguage(successCallback, errorCallback);
+
+### Description
+
+Returns the BCP-47 compliant language identifier tag to the `successCallback`
+with a `properties` object as a parameter. That object should have a `value`
+property with a `String` value.
+
+If there is an error getting the language, then the `errorCallback`
+executes with a `GlobalizationError` object as a parameter. The
+error's expected code is `GlobalizationError.UNKNOWN_ERROR`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- Firefox OS
+- iOS
+- Windows Phone 8
+- Windows
+- Browser
+
+### Example
+
+When the browser is set to the `en-US` language, this should display a
+popup dialog with the text `language: en-US`:
+
+ navigator.globalization.getPreferredLanguage(
+ function (language) {alert('language: ' + language.value + '\n');},
+ function () {alert('Error getting language\n');}
+ );
+
+### Android Quirks
+
+- Returns the ISO 639-1 two-letter language code, upper case ISO 3166-1
+country code and variant separated by hyphens. Examples: "en", "en-US", "US"
+
+### Windows Phone 8 Quirks
+
+- Returns the ISO 639-1 two-letter language code and ISO 3166-1 country code
+of the regional variant corresponding to the "Language" setting, separated by
+a hyphen.
+- Note that the regional variant is a property of the "Language" setting and
+not determined by the unrelated "Country/Region" setting on Windows Phone.
+
+### Windows Quirks
+
+- Returns the ISO 639-1 two-letter language code and ISO 3166-1 country code
+of the regional variant corresponding to the "Language" setting, separated by
+a hyphen.
+
+### Browser Quirks
+
+- Falls back on getLocaleName
+
+## navigator.globalization.getLocaleName
+
+Returns the BCP 47 compliant tag for the client's current locale setting.
+
+ navigator.globalization.getLocaleName(successCallback, errorCallback);
+
+### Description
+
+Returns the BCP 47 compliant locale identifier string to the `successCallback`
+with a `properties` object as a parameter. That object should have a `value`
+property with a `String` value. The locale tag will consist of a two-letter lower
+case language code, two-letter upper case country code, and (unspecified) variant
+code, separated by a hyphen.
+
+If there is an error getting the locale, then the `errorCallback`
+executes with a `GlobalizationError` object as a parameter. The
+error's expected code is `GlobalizationError.UNKNOWN_ERROR`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- Firefox OS
+- iOS
+- Windows Phone 8
+- Windows
+- Browser
+
+### Example
+
+When the browser is set to the `en-US` locale, this displays a popup
+dialog with the text `locale: en-US`.
+
+ navigator.globalization.getLocaleName(
+ function (locale) {alert('locale: ' + locale.value + '\n');},
+ function () {alert('Error getting locale\n');}
+ );
+
+### Android Quirks
+
+- Java does not distinguish between a set "langauge" and set "locale," so this
+method is essentially the same as `navigator.globalization.getPreferredLanguage()`.
+
+### Windows Phone 8 Quirks
+
+- Returns the ISO 639-1 two-letter language code and ISO 3166-1 country code
+of the regional variant corresponding to the "Regional Format" setting, separated
+by a hyphen.
+
+### Windows Quirks
+
+- Locale setting can be changed in Control Panel -> Clock, Language and Region
+-> Region -> Formats -> Format,
+and in Settings -> Region -> Regional Format on Windows Phone 8.1.
+
+### Browser Quirks
+
+- IE returns the locale of operating system. Chrome and Firefox return browser language tag.
+
+## navigator.globalization.dateToString
+
+Returns a date formatted as a string according to the client's locale and timezone.
+
+ navigator.globalization.dateToString(date, successCallback, errorCallback, options);
+
+### Description
+
+Returns the formatted date `String` via a `value` property accessible
+from the object passed as a parameter to the `successCallback`.
+
+The inbound `date` parameter should be of type `Date`.
+
+If there is an error formatting the date, then the `errorCallback`
+executes with a `GlobalizationError` object as a parameter. The
+error's expected code is `GlobalizationError.FORMATTING_ERROR`.
+
+The `options` parameter is optional, and its default values are:
+
+ {formatLength:'short', selector:'date and time'}
+
+The `options.formatLength` can be `short`, `medium`, `long`, or `full`.
+
+The `options.selector` can be `date`, `time` or `date and time`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- Firefox OS
+- iOS
+- Windows Phone 8
+- Windows
+- Browser
+
+### Example
+
+If the browser is set to the `en_US` locale, this displays a popup
+dialog with text similar to `date: 9/25/2012 4:21PM` using the default
+options:
+
+ navigator.globalization.dateToString(
+ new Date(),
+ function (date) { alert('date: ' + date.value + '\n'); },
+ function () { alert('Error getting dateString\n'); },
+ { formatLength: 'short', selector: 'date and time' }
+ );
+### Android Quirks
+- `formatLength` options are a subset of Unicode
+ [UTS #35](http://unicode.org/reports/tr35/tr35-4.html). The default option
+ `short` depends on a user selected date format within
+ `Settings -> System -> Date & time -> Choose date format`,
+ which provide a `year` pattern only with 4 digits, not 2 digits.
+ This means that it is not completely aligned with
+ [ICU](http://demo.icu-project.org/icu-bin/locexp?d_=en_US&_=en_US).
+
+### Windows Phone 8 Quirks
+
+- The `formatLength` option supports only `short` and `full` values.
+
+- The pattern for 'date and time' selector is always a full datetime format.
+
+- The returned value may be not completely aligned with ICU depending on a user locale.
+
+### Windows Quirks
+
+- The `formatLength` option supports only `short` and `full` values.
+
+- The pattern for 'date and time' selector is always a full datetime format.
+
+- The returned value may be not completely aligned with ICU depending on a user locale.
+
+### Browser Quirks
+
+- Only 79 locales are supported because moment.js is used in this method.
+
+- The returned value may be not completely aligned with ICU depending on a user locale.
+
+- `time` selector supports `full` and `short` formatLength only.
+
+### Firefox OS Quirks
+
+- `formatLength` is not distinguishing `long` and `full`
+- only one method of displaying date (no `long` or `full` version)
+
+## navigator.globalization.getCurrencyPattern
+
+Returns a pattern string to format and parse currency values according
+to the client's user preferences and ISO 4217 currency code.
+
+ navigator.globalization.getCurrencyPattern(currencyCode, successCallback, errorCallback);
+
+### Description
+
+Returns the pattern to the `successCallback` with a `properties` object
+as a parameter. That object should contain the following properties:
+
+- __pattern__: The currency pattern to format and parse currency values. The patterns follow [Unicode Technical Standard #35](http://unicode.org/reports/tr35/tr35-4.html). _(String)_
+
+- __code__: The ISO 4217 currency code for the pattern. _(String)_
+
+- __fraction__: The number of fractional digits to use when parsing and formatting currency. _(Number)_
+
+- __rounding__: The rounding increment to use when parsing and formatting. _(Number)_
+
+- __decimal__: The decimal symbol to use for parsing and formatting. _(String)_
+
+- __grouping__: The grouping symbol to use for parsing and formatting. _(String)_
+
+The inbound `currencyCode` parameter should be a `String` of one of
+the ISO 4217 currency codes, for example 'USD'.
+
+If there is an error obtaining the pattern, then the `errorCallback`
+executes with a `GlobalizationError` object as a parameter. The
+error's expected code is `GlobalizationError.FORMATTING_ERROR`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- iOS
+- Windows
+
+### Example
+
+When the browser is set to the `en_US` locale and the selected
+currency is United States Dollars, this example displays a popup
+dialog with text similar to the results that follow:
+
+ navigator.globalization.getCurrencyPattern(
+ 'USD',
+ function (pattern) {
+ alert('pattern: ' + pattern.pattern + '\n' +
+ 'code: ' + pattern.code + '\n' +
+ 'fraction: ' + pattern.fraction + '\n' +
+ 'rounding: ' + pattern.rounding + '\n' +
+ 'decimal: ' + pattern.decimal + '\n' +
+ 'grouping: ' + pattern.grouping);
+ },
+ function () { alert('Error getting pattern\n'); }
+ );
+
+Expected result:
+
+ pattern: $#,##0.##;($#,##0.##)
+ code: USD
+ fraction: 2
+ rounding: 0
+ decimal: .
+ grouping: ,
+
+### Windows Quirks
+
+- Only 'code' and 'fraction' properties are supported
+
+
+## navigator.globalization.getDateNames
+
+Returns an array of the names of the months or days of the week,
+depending on the client's user preferences and calendar.
+
+ navigator.globalization.getDateNames(successCallback, errorCallback, options);
+
+### Description
+
+Returns the array of names to the `successCallback` with a
+`properties` object as a parameter. That object contains a `value`
+property with an `Array` of `String` values. The array features names
+starting from either the first month in the year or the first day of
+the week, depending on the option selected.
+
+If there is an error obtaining the names, then the `errorCallback`
+executes with a `GlobalizationError` object as a parameter. The
+error's expected code is `GlobalizationError.UNKNOWN_ERROR`.
+
+The `options` parameter is optional, and its default values are:
+
+ {type:'wide', item:'months'}
+
+The value of `options.type` can be `narrow` or `wide`.
+
+The value of `options.item` can be `months` or `days`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- Firefox OS
+- iOS
+- Windows Phone 8
+- Windows
+- Browser
+
+### Example
+
+When the browser is set to the `en_US` locale, this example displays
+a series of twelve popup dialogs, one per month, with text similar to
+`month: January`:
+
+ navigator.globalization.getDateNames(
+ function (names) {
+ for (var i = 0; i < names.value.length; i++) {
+ alert('month: ' + names.value[i] + '\n');
+ }
+ },
+ function () { alert('Error getting names\n'); },
+ { type: 'wide', item: 'months' }
+ );
+
+### Firefox OS Quirks
+
+- `options.type` supports a `genitive` value, important for some languages.
+
+### Windows Phone 8 Quirks
+
+- The array of months contains 13 elements.
+- The returned array may be not completely aligned with ICU depending on a user locale.
+
+### Windows Quirks
+
+- The array of months contains 12 elements.
+- The returned array may be not completely aligned with ICU depending on a user locale.
+
+### Browser Quirks
+
+- Date names are not completely aligned with ICU.
+- The array of months contains 12 elements.
+
+## navigator.globalization.getDatePattern
+
+Returns a pattern string to format and parse dates according to the
+client's user preferences.
+
+ navigator.globalization.getDatePattern(successCallback, errorCallback, options);
+
+### Description
+
+Returns the pattern to the `successCallback`. The object passed in as
+a parameter contains the following properties:
+
+- __pattern__: The date and time pattern to format and parse dates. The patterns follow [Unicode Technical Standard #35](http://unicode.org/reports/tr35/tr35-4.html). _(String)_
+
+- __timezone__: The abbreviated name of the time zone on the client. _(String)_
+
+- __utc_offset__: The current difference in seconds between the client's time zone and coordinated universal time. _(Number)_
+
+- __dst_offset__: The current daylight saving time offset in seconds between the client's non-daylight saving's time zone and the client's daylight saving's time zone. _(Number)_
+
+If there is an error obtaining the pattern, the `errorCallback`
+executes with a `GlobalizationError` object as a parameter. The
+error's expected code is `GlobalizationError.PATTERN_ERROR`.
+
+The `options` parameter is optional, and defaults to the following values:
+
+ {formatLength:'short', selector:'date and time'}
+
+The `options.formatLength` can be `short`, `medium`, `long`, or
+`full`. The `options.selector` can be `date`, `time` or `date and
+time`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- iOS
+- Windows Phone 8
+- Windows
+- Browser
+
+### Example
+
+When the browser is set to the `en_US` locale, this example displays
+a popup dialog with text such as `pattern: M/d/yyyy h:mm a`:
+
+ function checkDatePattern() {
+ navigator.globalization.getDatePattern(
+ function (date) { alert('pattern: ' + date.pattern + '\n'); },
+ function () { alert('Error getting pattern\n'); },
+ { formatLength: 'short', selector: 'date and time' }
+ );
+ }
+
+### Windows Phone 8 Quirks
+
+- The `formatLength` supports only `short` and `full` values.
+
+- The `pattern` for `date and time` pattern returns only full datetime format.
+
+- The `timezone` returns the full time zone name.
+
+- The `dst_offset` property is not supported, and always returns zero.
+
+- The pattern may be not completely aligned with ICU depending on a user locale.
+
+### Windows Quirks
+
+- The `formatLength` supports only `short` and `full` values.
+
+- The `pattern` for `date and time` pattern returns only full datetime format.
+
+- The `timezone` returns the full time zone name.
+
+- The `dst_offset` property is not supported, and always returns zero.
+
+- The pattern may be not completely aligned with ICU depending on a user locale.
+
+### Browser Quirks
+
+- The 'pattern' property is not supported and returns empty string.
+
+- Only Chrome returns 'timezone' property. Its format is "Part of the world/{City}".
+Other browsers return empty string.
+
+## navigator.globalization.getFirstDayOfWeek
+
+Returns the first day of the week according to the client's user
+preferences and calendar.
+
+ navigator.globalization.getFirstDayOfWeek(successCallback, errorCallback);
+
+### Description
+
+The days of the week are numbered starting from 1, where 1 is assumed
+to be Sunday. Returns the day to the `successCallback` with a
+`properties` object as a parameter. That object should have a `value`
+property with a `Number` value.
+
+If there is an error obtaining the pattern, then the `errorCallback`
+executes with a `GlobalizationError` object as a parameter. The
+error's expected code is `GlobalizationError.UNKNOWN_ERROR`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- Firefox OS
+- iOS
+- Windows Phone 8
+- Windows
+- Browser
+
+### Example
+
+When the browser is set to the `en_US` locale, this displays a
+popup dialog with text similar to `day: 1`.
+
+ navigator.globalization.getFirstDayOfWeek(
+ function (day) {alert('day: ' + day.value + '\n');},
+ function () {alert('Error getting day\n');}
+ );
+
+### Windows Quirks
+
+- On Windows 8.0/8.1 the value depends on user' calendar preferences. On Windows Phone 8.1
+the value depends on current locale.
+
+### Browser Quirks
+
+- Only 79 locales are supported because moment.js is used in this method.
+
+## navigator.globalization.getNumberPattern
+
+Returns a pattern string to format and parse numbers according to the client's user preferences.
+
+ navigator.globalization.getNumberPattern(successCallback, errorCallback, options);
+
+### Description
+
+Returns the pattern to the `successCallback` with a `properties` object
+as a parameter. That object contains the following properties:
+
+- __pattern__: The number pattern to format and parse numbers. The patterns follow [Unicode Technical Standard #35](http://unicode.org/reports/tr35/tr35-4.html). _(String)_
+
+- __symbol__: The symbol to use when formatting and parsing, such as a percent or currency symbol. _(String)_
+
+- __fraction__: The number of fractional digits to use when parsing and formatting numbers. _(Number)_
+
+- __rounding__: The rounding increment to use when parsing and formatting. _(Number)_
+
+- __positive__: The symbol to use for positive numbers when parsing and formatting. _(String)_
+
+- __negative__: The symbol to use for negative numbers when parsing and formatting. _(String)_
+
+- __decimal__: The decimal symbol to use for parsing and formatting. _(String)_
+
+- __grouping__: The grouping symbol to use for parsing and formatting. _(String)_
+
+If there is an error obtaining the pattern, then the `errorCallback`
+executes with a `GlobalizationError` object as a parameter. The
+error's expected code is `GlobalizationError.PATTERN_ERROR`.
+
+The `options` parameter is optional, and default values are:
+
+ {type:'decimal'}
+
+The `options.type` can be `decimal`, `percent`, or `currency`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- iOS
+- Windows Phone 8
+- Windows
+- Browser
+
+### Example
+
+When the browser is set to the `en_US` locale, this should display a
+popup dialog with text similar to the results that follow:
+
+ navigator.globalization.getNumberPattern(
+ function (pattern) {alert('pattern: ' + pattern.pattern + '\n' +
+ 'symbol: ' + pattern.symbol + '\n' +
+ 'fraction: ' + pattern.fraction + '\n' +
+ 'rounding: ' + pattern.rounding + '\n' +
+ 'positive: ' + pattern.positive + '\n' +
+ 'negative: ' + pattern.negative + '\n' +
+ 'decimal: ' + pattern.decimal + '\n' +
+ 'grouping: ' + pattern.grouping);},
+ function () {alert('Error getting pattern\n');},
+ {type:'decimal'}
+ );
+
+Results:
+
+ pattern: #,##0.###
+ symbol: .
+ fraction: 0
+ rounding: 0
+ positive:
+ negative: -
+ decimal: .
+ grouping: ,
+
+
+### Windows Phone 8 Quirks
+
+- The `pattern` property is not supported, and returns an empty string.
+
+- The `fraction` property is not supported, and returns zero.
+
+### Windows Quirks
+
+- The `pattern` property is not supported, and returns an empty string.
+
+
+### Browser Quirks
+
+- getNumberPattern is supported in Chrome only; the only defined property is `pattern`.
+
+## navigator.globalization.isDayLightSavingsTime
+
+Indicates whether daylight savings time is in effect for a given date
+using the client's time zone and calendar.
+
+ navigator.globalization.isDayLightSavingsTime(date, successCallback, errorCallback);
+
+### Description
+
+Indicates whether or not daylight savings time is in effect to the
+`successCallback` with a `properties` object as a parameter. That object
+should have a `dst` property with a `Boolean` value. A `true` value
+indicates that daylight savings time is in effect for the given date,
+and `false` indicates that it is not.
+
+The inbound parameter `date` should be of type `Date`.
+
+If there is an error reading the date, then the `errorCallback`
+executes. The error's expected code is `GlobalizationError.UNKNOWN_ERROR`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- Firefox OS
+- iOS
+- Windows Phone 8
+- Windows
+- Browser
+
+### Example
+
+During the summer, and if the browser is set to a DST-enabled
+timezone, this should display a popup dialog with text similar to
+`dst: true`:
+
+ navigator.globalization.isDayLightSavingsTime(
+ new Date(),
+ function (date) {alert('dst: ' + date.dst + '\n');},
+ function () {alert('Error getting names\n');}
+ );
+
+
+
+## navigator.globalization.numberToString
+
+Returns a number formatted as a string according to the client's user preferences.
+
+ navigator.globalization.numberToString(number, successCallback, errorCallback, options);
+
+### Description
+
+Returns the formatted number string to the `successCallback` with a
+`properties` object as a parameter. That object should have a `value`
+property with a `String` value.
+
+If there is an error formatting the number, then the `errorCallback`
+executes with a `GlobalizationError` object as a parameter. The
+error's expected code is `GlobalizationError.FORMATTING_ERROR`.
+
+The `options` parameter is optional, and its default values are:
+
+ {type:'decimal'}
+
+The `options.type` can be `decimal`, `percent`, or `currency`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- iOS
+- Windows Phone 8
+- Windows
+- Browser
+
+### Example
+
+When the browser is set to the `en_US` locale, this displays a popup
+dialog with text similar to `number: 3.142`:
+
+ navigator.globalization.numberToString(
+ 3.1415926,
+ function (number) {alert('number: ' + number.value + '\n');},
+ function () {alert('Error getting number\n');},
+ {type:'decimal'}
+ );
+
+### Windows Quirks
+
+- Windows 8.0 does not support number rounding, therefore values will not be rounded automatically.
+
+- On Windows 8.1 and Windows Phone 8.1 fractional part is being truncated instead of rounded in case of `percent` number type therefore fractional digits count is set to 0.
+
+- `percent` numbers are not grouped as they can't be parsed in stringToNumber if grouped.
+
+### Browser Quirks
+
+- `currency` type is not supported.
+
+## navigator.globalization.stringToDate
+
+Parses a date formatted as a string, according to the client's user
+preferences and calendar using the time zone of the client, and
+returns the corresponding date object.
+
+ navigator.globalization.stringToDate(dateString, successCallback, errorCallback, options);
+
+### Description
+
+Returns the date to the success callback with a `properties` object as
+a parameter. That object should have the following properties:
+
+- __year__: The four digit year. _(Number)_
+
+- __month__: The month from (0-11). _(Number)_
+
+- __day__: The day from (1-31). _(Number)_
+
+- __hour__: The hour from (0-23). _(Number)_
+
+- __minute__: The minute from (0-59). _(Number)_
+
+- __second__: The second from (0-59). _(Number)_
+
+- __millisecond__: The milliseconds (from 0-999), not available on all platforms. _(Number)_
+
+The inbound `dateString` parameter should be of type `String`.
+
+The `options` parameter is optional, and defaults to the following
+values:
+
+ {formatLength:'short', selector:'date and time'}
+
+The `options.formatLength` can be `short`, `medium`, `long`, or
+`full`. The `options.selector` can be `date`, `time` or `date and
+time`.
+
+If there is an error parsing the date string, then the `errorCallback`
+executes with a `GlobalizationError` object as a parameter. The
+error's expected code is `GlobalizationError.PARSING_ERROR`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- Firefox OS
+- iOS
+- Windows Phone 8
+- Windows
+- Browser
+
+### Example
+
+When the browser is set to the `en_US` locale, this displays a
+popup dialog with text similar to `month:8 day:25 year:2012`. Note
+that the month integer is one less than the string, as the month
+integer represents an array index.
+
+ navigator.globalization.stringToDate(
+ '9/25/2012',
+ function (date) {alert('month:' + date.month +
+ ' day:' + date.day +
+ ' year:' + date.year + '\n');},
+ function () {alert('Error getting date\n');},
+ {selector: 'date'}
+ );
+
+### Windows Phone 8 Quirks
+
+- The `formatLength` option supports only `short` and `full` values.
+
+- The pattern for 'date and time' selector is always a full datetime format.
+
+- The inbound `dateString` parameter should be formed in compliance with a pattern returned by getDatePattern.
+This pattern may be not completely aligned with ICU depending on a user locale.
+
+### Windows Quirks
+
+- The `formatLength` option supports only `short` and `full` values.
+
+- The pattern for 'date and time' selector is always a full datetime format.
+
+- The inbound `dateString` parameter should be formed in compliance with a pattern returned by getDatePattern.
+This pattern may be not completely aligned with ICU depending on a user locale.
+
+### Browser Quirks
+
+- Only 79 locales are supported because moment.js is used in this method.
+
+- Inbound string should be aligned with `dateToString` output format and may not completely aligned with ICU depending on a user locale.
+
+- `time` selector supports `full` and `short` formatLength only.
+
+## navigator.globalization.stringToNumber
+
+Parses a number formatted as a string according to the client's user
+preferences and returns the corresponding number.
+
+ navigator.globalization.stringToNumber(string, successCallback, errorCallback, options);
+
+### Description
+
+Returns the number to the `successCallback` with a `properties` object
+as a parameter. That object should have a `value` property with a
+`Number` value.
+
+If there is an error parsing the number string, then the
+`errorCallback` executes with a `GlobalizationError` object as a
+parameter. The error's expected code is
+`GlobalizationError.PARSING_ERROR`.
+
+The `options` parameter is optional, and defaults to the following
+values:
+
+ {type:'decimal'}
+
+The `options.type` can be `decimal`, `percent`, or `currency`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- iOS
+- Windows Phone 8
+- Windows
+
+### Example
+
+When the browser is set to the `en_US` locale, this should display a
+popup dialog with text similar to `number: 1234.56`:
+
+ navigator.globalization.stringToNumber(
+ '1234.56',
+ function (number) {alert('number: ' + number.value + '\n');},
+ function () {alert('Error getting number\n');},
+ {type:'decimal'}
+ );
+
+### Windows Phone 8 Quirks
+
+- In case of `percent` type the returned value is not divided by 100.
+
+### Windows Quirks
+
+- The string must strictly conform to the locale format. For example, percent symbol should be
+separated by space for 'en-US' locale if the type parameter is 'percent'.
+
+- `percent` numbers must not be grouped to be parsed correctly.
+
+## GlobalizationError
+
+An object representing a error from the Globalization API.
+
+### Properties
+
+- __code__: One of the following codes representing the error type _(Number)_
+ - `GlobalizationError.UNKNOWN_ERROR`: 0
+ - `GlobalizationError.FORMATTING_ERROR`: 1
+ - `GlobalizationError.PARSING_ERROR`: 2
+ - `GlobalizationError.PATTERN_ERROR`: 3
+- __message__: A text message that includes the error's explanation and/or details. _(String)_
+
+### Description
+
+This object is created and populated by Cordova, and returned to a callback in the case of an error.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- Firefox OS
+- iOS
+- Windows Phone 8
+- Windows
+
+### Example
+
+When the following error callback executes, it displays a
+popup dialog with the text similar to `code: 3` and `message:`
+
+ function errorCallback(error) {
+ alert('code: ' + error.code + '\n' +
+ 'message: ' + error.message + '\n');
+ };
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org