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