http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/plugin_ref/spec.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/plugin_ref/spec.md b/www/docs/en/6.x/plugin_ref/spec.md index 2fc4b02..c70d48f 100644 --- a/www/docs/en/6.x/plugin_ref/spec.md +++ b/www/docs/en/6.x/plugin_ref/spec.md @@ -30,7 +30,7 @@ Plugin.xml file defines the structure and settings required for your plugin. It The `plugin` element is the plugin manifest's top-level element. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ xmlns(string) | *Required* <br/> The plugin namespace, `http://apache.org/cordova/ns/plugins/1.0`. If the document contains XML from other namespaces, such as tags to be added to the `AndroidManifest.xml` file in the case of Android, those namespaces should also be included in the <plugin> element. id(string) | *Required* <br/> A npm-style identifier for the plugin. @@ -53,7 +53,7 @@ The child elements of the `<engines>` element specify versions of Apache Cordova >is in a plugin's `package.json`. See [specifying Cordova >dependencies](../guide/hybrid/plugins/index.html#specifying-cordova-dependencies) >for more information -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ name(string) | *Required* <br/> Name of the engine. Here are the default engines that are supported : <ul><li> `cordova` </li> <li> `cordova-plugman` </li> <li> `cordova-android` </li> <li> `cordova-ios` </li> <li> `cordova-blackberry10` </li> <li> `cordova-wp8` </li> <li> `cordova-windows` </li> <li> `cordova-osx` </li> <li> `windows-os` </li> <li> `android-sdk` (returns the highest Android api level installed) </li> <li> `windows-sdk` (returns the native windows SDK version) </li> <li> `apple-xcode` (returns the xcode version) </li> <li> `apple-ios` (returns the highest iOS version installed) </li> <li> `apple-osx` (returns the OSX version) </li> <li> `blackberry-ndk` (returns the native blackberry SDK version) </li> You can also specify a custom framework apart from the default ones. version(string) | *Required* <br/> The version that your framework must have in order to install. Semver syntax is supported. @@ -70,16 +70,16 @@ Examples: Engine elements may also specify fuzzy matches using '>', '>=' etc. to avoid repetition, and to reduce maintenance when the underlying platform is updated. ```xml <engines> - <engine name="cordova-android" version=">=1.8.0" /> + <engine name="cordova-android" version=">=1.8.0" /> </engines> ``` The `<engine>` tags also has default support for all of the main platforms Cordova exists on. Specifying the cordova engine tag means that all versions of Cordova on any platform must satisfy the engine version attribute. You may also list specific platforms and their versions in order to override the catch-all cordova engine: ```xml <engines> - <engine name="cordova" version=">=1.7.0" /> - <engine name="cordova-android" version=">=1.8.0" /> - <engine name="cordova-ios" version=">=1.7.1" /> + <engine name="cordova" version=">=1.7.0" /> + <engine name="cordova-android" version=">=1.8.0" /> + <engine name="cordova-ios" version=">=1.7.1" /> </engines> ``` @@ -87,8 +87,8 @@ Custom frameworks example: ```xml <engines> <engine name="my_custom_framework" version="1.0.0" platform="android" scriptSrc="path_to_my_custom_framework_version"/> - <engine name="another_framework" version=">0.2.0" platform="ios|android" scriptSrc="path_to_another_framework_version"/> - <engine name="even_more_framework" version=">=2.2.0" platform="*" scriptSrc="path_to_even_more_framework_version"/> + <engine name="another_framework" version=">0.2.0" platform="ios|android" scriptSrc="path_to_another_framework_version"/> + <engine name="even_more_framework" version=">=2.2.0" platform="*" scriptSrc="path_to_even_more_framework_version"/> </engines> ``` @@ -141,7 +141,7 @@ Example: This element is used to list the files or directories to be copied into a Cordova app's `www` directory. Any `<asset>` elements that are nested within `<platform>` elements specify platform-specific web assets. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ src(string) | *Required* <br/> Where the file or directory is located in the plugin package, relative to the `plugin.xml` document. If a file does not exist at the specified src location, the CLI stops and reverses the installation process, issues a notification about the conflict, and exits with a non-zero code. target(string) | *Required* <br/> Where the file or directory should be located in the Cordova app, relative to the `www` directory. If a file already exists at the target location, the CLI stops and reverses the installation process, issues a notification about the conflict, and exits with a non-zero code. @@ -163,7 +163,7 @@ Assets can be targeted to subdirectories as well. This will create the `js/exper Most plugins include one or more JavaScript files. Each `<js-module>` tag corresponds to a JavaScript file, and prevents the plugin's users from having to add a `<script>` tag for each file. Do not wrap the file with cordova.define, as it is added automatically. The module is wrapped in a closure, with module, exports, and require in scope, as is normal for AMD modules. Nesting `<js-module>` elements within `<platform>` declares platform-specific JavaScript module bindings. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ src(string) | References a file in the plugin directory relative to the `plugin.xml` file. If src does not resolve to an existing file, the CLI stops and reverses the installation, issues a notification of the problem, and exits with a non-zero code. name(string) | Provides the last part of the module name. It can generally be whatever you like, and it only matters if you want to use cordova.require to import other parts of your plugins in your JavaScript code. The module name for a `<js-module>` is your plugin's id followed by the value of name. @@ -182,7 +182,7 @@ Also for this example, with a plugin id of `chrome-socket`, the module name will Allowed within `<js-module>` element. Used to specify the namespace under `window` object where module.exports gets inserted. You can have as many `<clobbers>` as you like. Any object not available on `window` is created. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ target(string) | The namespace where module.exports gets inserted to. @@ -198,7 +198,7 @@ Here module.exports gets inserted into the `window` object as `window.chrome.soc Allowed within `<js-module>` element. Used to specify the namespace under `window` object where module.exports gets merged with any existing value. If any key already exists, the module's version overrides the original. You can have as many `<merges>` as you like. Any object not available on `window` is created. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ target(string) | The namespace which module.exports gets merged to. @@ -225,7 +225,7 @@ Example: The `<dependency>` tag allows you to specify other plugins on which the current plugin depends. The plugins are referenced by their unique npm ids or by github url. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ id(string) | Provides the ID of the plugin. url(string) | A URL for the plugin. This should reference a git repository, which the CLI attempts to clone. @@ -243,7 +243,7 @@ Examples: Identifies platforms that have associated native code or require modifications to their configuration files. Tools using this specification can identify supported platforms and install the code into Cordova projects. Plugins without `<platform>` tags are assumed to be JavaScript-only, and therefore installable on any and all platforms. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ name(string) | *Required* <br/> Allowed values: ios, android, blackberry10, amazon-fireos, wp8, windows <br/> Identifies a platform as supported, associating the element's children with that platform. @@ -258,12 +258,12 @@ Example: Identifies executable source code that should be installed into a project. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ src(string) | *Required* <br/> Location of the file relative to `plugin.xml`. If the src file can't be found, the CLI stops and reverses the installation, issues a notification about the problem, and exits with a non-zero code. target-dir(string) | A directory into which the files should be copied, relative to the root of the Cordova project. In practice, this is most important for Java-based platforms, where a file in the `com.alunny.foo` package must be located within the `com/alunny/foo` directory. For platforms where the source directory is not important, this attribute should be omitted. -framework(boolean) | *Default: false* <br/> ==iOS== <br/> If set to true, also adds the specified file as a framework to the project. -compiler-flags(string) | ==iOS== <br/> If set, assigns the specified compiler flags for the particular source file. +framework(boolean) <br/> ==iOS== | *Default: false* <br/> If set to true, also adds the specified file as a framework to the project. +compiler-flags(string) <br/> ==iOS== | If set, assigns the specified compiler flags for the particular source file. Examples: ```xml @@ -279,7 +279,7 @@ Examples: This is like `<source-file>` element but specifically for platforms such as iOS and Android that distinguish between source files, headers, and resources. This is not supported by Windows. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ src(string) | *Required* <br/> Location of the file relative to `plugin.xml`. If the src file can't be found, the CLI stops and reverses the installation, issues a notification about the problem, and exits with a non-zero code. target(string) | Path to where the file will be copied in your directory. @@ -295,13 +295,13 @@ For iOS: This is like `<source-file>` element, but specifically for platforms such as iOS and Android that distinguish between source files, headers, and resources. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ src(string) | *Required* <br/> Location of the file relative to `plugin.xml`. If the src file can't be found, the CLI stops and reverses the installation, issues a notification about the problem, and exits with a non-zero code. target(string) | Path to where the file will be copied in your directory. -arch(string) | ==windows== <br/> Allowed values: `x86`, `x64` or `ARM`. <br/> Indicates that the file should only be included when building for the specified architecture. -device-target | ==windows== <br/> Allowed values: `win` (or `windows`), `phone` or `all`. <br/> Indicates that the file should only be included when building for the specified target device type. -versions | ==windows== <br/> Indicates that the file should only be included when building for versions that match the specified version string. Value can be any valid node semantic version range string. +arch(string) <br/> ==windows== | Allowed values: `x86`, `x64` or `ARM`. <br/> Indicates that the file should only be included when building for the specified architecture. +device-target <br/> ==windows== | Allowed values: `win` (or `windows`), `phone` or `all`. <br/> Indicates that the file should only be included when building for the specified target device type. +versions <br/> ==windows== | Indicates that the file should only be included when building for versions that match the specified version string. Value can be any valid node semantic version range string. Examples: @@ -321,13 +321,13 @@ Identifies an XML-based configuration file to be modified, where in that documen Two file types that have been tested for modification with this element are `xml` and `plist` files. The `config-file` element only allows you to append new children to an XML document tree. The children are XML literals to be inserted in the target document. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ target(string) | The file to be modified, and the path relative to the root of the Cordova project. If the specified file does not exist, the tool ignores the configuration change and continues installation. <br/> The target can include wildcard (`*`) elements. In this case, the CLI recursively searches through the project directory structure and uses the first match. <br/> On iOS, the location of configuration files relative to the project directory root is not known, so specifying a target of `config.xml` resolves to `cordova-ios-project/MyAppName/config.xml`. parent(string) | An XPath selector referencing the parent of the elements to be added to the config file. If you use absolute selectors, you can use a wildcard (`*`) to specify the root element, e.g., `/*/plugins`. If the selector does not resolve to a child of the specified document, the tool stops and reverses the installation process, issues a warning, and exits with a non-zero code. <br/> For `plist` files, the `parent` determines under what parent key the specified XML should be inserted. after(string) | A prioritized list of accepted siblings after which to add the XML snippet. Useful for specifying changes in files which require strict ordering of XML elements like [this](http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff769509%28v=vs.105%29.aspx#BKMK_EXTENSIONSelement). -device-target(string) | ==windows== <br/> Allowed values: `win`, `phone`, `all`. <br/> Applicable when affecting the meta-name `package.appxmanifest`, this attribute indicates that the file should only be modified when building for the specified target device type. -versions(string) | ==windows== <br/> Applicable when affecting the meta-name `package.appxmanifest`, this attribute indicates that app manifests for specific Windows versions should only be altered for versions that match the specified version string. Value can be any valid node semantic version range string. +device-target(string) <br/> ==windows== | Allowed values: `win`, `phone`, `all`. <br/> Applicable when affecting the meta-name `package.appxmanifest`, this attribute indicates that the file should only be modified when building for the specified target device type. +versions(string) <br/> ==windows== | Applicable when affecting the meta-name `package.appxmanifest`, this attribute indicates that app manifests for specific Windows versions should only be altered for versions that match the specified version string. Value can be any valid node semantic version range string. Examples: @@ -355,11 +355,11 @@ For `plist`: For windows-specific attributes: ```xml -<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions="<8.1.0"> +<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions="<8.1.0"> <Capability Name="picturesLibrary" /> <DeviceCapability Name="webcam" /> </config-file> -<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions=">=8.1.0" device-target="phone"> +<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions=">=8.1.0" device-target="phone"> <DeviceCapability Name="webcam" /> </config-file> ``` @@ -378,12 +378,12 @@ Example: Like source, resource, and header files, but specifically for platforms such as BlackBerry 10 that use user-generated libraries. For the Windows platform, the `<lib-file>` element allows the inclusion of an `<SDKReference>` in the generated Windows project files. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ src(string) | *Required* <br/> The location of the file relative to `plugin.xml`. If `src` can't be found, the CLI stops and reverses the installation, issues a warning about the problem, and exits with a non-zero code. <br/> For Windows, it indicates the name of the SDK to include (which will be used as value of the `Include` attribute of the generated `<SDKReference>` element). arch(string) | The architecture for which the `.so` file has been built, either `device` or `simulator`. <br/> For Windows, it indicates that the `<SDKReference>` should only be included when building for the specified architecture. Supported values are `x86`, `x64` or `ARM`. -device-target(string) | ==windows== <br/> Allowed values: `win` (or `windows`), `phone` or `all`. <br/> Indicates that the `<SDKReference>` should only be included when building for the specified target device type. -versions(string) | ==windows== <br/> Indicates that the `<SDKReference>` should only be included when building for versions that match the specified version string. Value can be any valid node semantic version range string. +device-target(string) <br/> ==windows== | Allowed values: `win` (or `windows`), `phone` or `all`. <br/> Indicates that the `<SDKReference>` should only be included when building for the specified target device type. +versions(string) <br/> ==windows== | Indicates that the `<SDKReference>` should only be included when building for versions that match the specified version string. Value can be any valid node semantic version range string. Examples: ```xml @@ -394,7 +394,7 @@ Examples: For Windows: ```xml <lib-file src="Microsoft.WinJS.2.0, Version=1.0" arch="x86" /> -<lib-file src="Microsoft.WinJS.2.0, Version=1.0" versions=">=8.1" /> +<lib-file src="Microsoft.WinJS.2.0, Version=1.0" versions=">=8.1" /> <lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="phone" /> <lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="win" versions="8.0" arch="x86" /> ``` @@ -403,17 +403,17 @@ For Windows: Identifies a framework (usually part of the OS/platform) on which the plugin depends. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ src(string) | *Required* <br/> The name of the system framework or the relative path to one which is included as part of your plugin files. custom(boolean) | Indicates whether the framework is included as part of your plugin files. weak(boolean) | *Default: false* <br/> Indicates whether the framework should be weakly linked. type(string) | Indicates the type of framework to add. parent(string) | *Default: .* <br/> Sets the relative path to the directory containing the sub-project to which to add the reference. The default, `.`, implies the application project. -arch(string) | ==windows== <br/> Allowed values: `x86`, `x64` or `ARM`. <br/> Indicates that the framework should only be included when building for the specified architecture. -device-target(string) | ==windows== <br/> Allowed values: `win` (or `windows`), `phone` or `all`. <br/> Indicates that the framework should only be included when building for the specified target device type. -versions(string) | ==windows== <br/> Indicates that the framework should only be included when building for versions that match the specified version string. Value can be any valid node semantic version range string. -target-dir(string) | ==windows== <br/> Indicates a subdirectory into which the framework should be copied. In practice, this is most important when plugin contains different framework versions for different chip architectures or device targets, but which have the same name. This allows you to specify different subfolders for each framework version so that they don't overlap each other. +arch(string) <br/> ==windows== | Allowed values: `x86`, `x64` or `ARM`. <br/> Indicates that the framework should only be included when building for the specified architecture. +device-target(string) <br/> ==windows== | Allowed values: `win` (or `windows`), `phone` or `all`. <br/> Indicates that the framework should only be included when building for the specified target device type. +versions(string) <br/> ==windows== | Indicates that the framework should only be included when building for versions that match the specified version string. Value can be any valid node semantic version range string. +target-dir(string) <br/> ==windows== | Indicates a subdirectory into which the framework should be copied. In practice, this is most important when plugin contains different framework versions for different chip architectures or device targets, but which have the same name. This allows you to specify different subfolders for each framework version so that they don't overlap each other. Examples: @@ -447,7 +447,7 @@ On Windows, using `custom='true'` and `type='projectReference'` will add a refer Examples of using these Windows specific attributes: ```xml <framework src="src/windows/example.dll" arch="x64" /> -<framework src="src/windows/example.dll" versions=">=8.0" /> +<framework src="src/windows/example.dll" versions=">=8.0" /> <framework src="src/windows/example.vcxproj" type="projectReference" target="win" /> <framework src="src/windows/example.vcxproj" type="projectReference" target="all" versions="8.1" arch="x86" /> <framework src="src/windows/example.dll" target-dir="bin/x64" arch="x64" custom="true"/> @@ -506,13 +506,21 @@ Certain variable names should be reserved, like `$PACKAGE_NAME`. This is the rev As seen in the previous section, sometimes plugin might require user to specify values for their variables. To make those variable mandatory, the `<platform>` tag needs to contain a `<preference>` tag. The CLI checks that these required preferences are passed in. If not, it should warn the user how to pass the variable in and exit with a non-zero code. +Preferences can be referenced elsewhere in `plugin.xml` using the syntax `$PREFERENCE_NAME`. -Attributes(type) | Description +Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description ---------------- | ------------ -name(string) | *Required* <br/> Name of the variable. +name(string) | *Required* <br/> Name of the variable. Can only contain capital letters, digits, and underscores. default(string) | Default value of the variable. If present, its value will be used and no error will be emitted in case user does not enter any value. Example: ```xml -<preference name="API_KEY" default="default-value" /> +<preference name="MY_CUSTOM_STRING" default="default-value" /> + +<!-- + The preference may be referenced elsewhere in plugin.xml like so: +--> +<config-file target="./res/values/strings.xml" parent="/resources"> + <string name="custom">$MY_CUSTOM_STRING</string> +</config-file> ```
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-cli/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/reference/cordova-cli/index.md b/www/docs/en/6.x/reference/cordova-cli/index.md index 2c42629..e118d05 100644 --- a/www/docs/en/6.x/reference/cordova-cli/index.md +++ b/www/docs/en/6.x/reference/cordova-cli/index.md @@ -43,6 +43,7 @@ These commands are available at all times. |----------|-------------- | create | Create a project | help <command> | Get help for a command +| telemetry | Turn telemetry collection on or off ## Project Command List @@ -70,6 +71,7 @@ These options apply to all cordova-cli commands. | -v or --version | Print out the version of your `cordova-cli` install. | --no-update-notifier | Will disable updates check. Alternatively set `"optOut": true` in `~/.config/configstore/update-notifier-cordova.json` or set `NO_UPDATE_NOTIFIER` environment variable with any value (see details in [update-notifier docs](https://www.npmjs.com/package/update-notifier#user-settings)). |--nohooks | Suppress executing hooks (taking RegExp hook patterns as parameters) +| --no-telemetry | Disable telemetry collection for the current command. ## Platform-specific options @@ -83,8 +85,12 @@ Certain commands have options (`platformOpts`) that are specific to a particular cd myApp # Add camera plugin to the project and remember that in config.xml cordova plugin add cordova-plugin-camera --save + # Add camera plugin to the project and remember that in config.xml. Use npm install to fetch. + cordova plugin add cordova-plugin-camera --save --fetch # Add android platform to the project and remember that in config.xml cordova platform add android --save + # Add android platform to the project and remember that in config.xml. Use npm install to fetch. + cordova platform add android --save --fetch # Check to see if your system is configured for building android platform. cordova requirements android # Build the android and emit verbose logs. @@ -123,7 +129,7 @@ cordova create path [id [name [config]]] [options] ### Directory structure -A Cordova application created with `cordova-cli` will have the following directory structure: +Cordova CLI works with the following directory structure: ``` myapp/ @@ -207,11 +213,12 @@ Manage cordova platforms - allowing you to add, remove, update, list and check f ```bash cordova {platform | platforms} [ - add <platform-spec> [...] {--save | link=<path> } | - {remove | rm} platform [...] | + add <platform-spec> [...] {--save | link=<path> | --fetch } | + {remove | rm} platform [...] {--save | --fetch}| {list | ls} | check | - save ] + save | + update ] ``` | Sub-command | Option | Description | @@ -219,10 +226,13 @@ cordova {platform | platforms} [ | add `<platform-spec>` [...] | | Add specified platforms | | | --save | Save `<platform-spec>` into `config.xml` after installing them using `<engine>` tag | | | --link=`<path>` | When `<platform-spec>` is a local path, links the platform library directly instead of making a copy of it (support varies by platform; useful for platform development) +| | --fetch | Fetches the platform using `npm install` and stores it into the apps `node_modules` directory | | remove `<platform>` [...] | | Remove specified platforms | | | --save | Delete specified platforms from `config.xml` after removing them | +| | --fetch | Removes the platform using `npm uninstall` and removes it from the apps `node_modules` directory | | update `platform` [...] | | Update specified platforms | | | --save | Updates the version specified in `config.xml` | +| | --fetch | Fetches the platform using `npm install` and stores it into the apps `node_modules` directory | | list | | List all installed and available platforms | | check | | List platforms which can be updated by `cordova-cli platform update` | | save | | Save `<platform-spec>` of all platforms added to config.xml | @@ -265,6 +275,11 @@ There are a number of ways to specify a platform: cordova platform add android ios --save +- Add pinned version of the `android` and `ios` platform and save the downloaded version to `config.xml`. Install +to the project using `npm install` and store it in the apps `node_modules` directory: + + cordova platform add android ios --save --fetch + - Add `android` platform with [semver](http://semver.org/) version ^5.0.0 and save it to `config.xml`: cordova platform add android@^5.0.0 --save @@ -285,6 +300,11 @@ There are a number of ways to specify a platform: cordova platform rm android --save +- Remove `android` platform from the project and from `config.xml`. Run `npm uninstall` to remove it +from the `node_modules` directory. + + cordova platform rm android --save --fetch + - List available and installed platforms with version numbers. This is useful to find version numbers when reporting issues: cordova platform ls @@ -303,8 +323,8 @@ Manage project plugins ```bash cordova {plugin | plugins} [ - add <plugin-spec> [..] {--searchpath=<directory> | --noregistry | --link | --save | --browserify | --force} | - {remove | rm} {<pluginid> | <name>} --save | + add <plugin-spec> [..] {--searchpath=<directory> | --noregistry | --link | --save | --browserify | --force | --fetch} | + {remove | rm} {<pluginid> | <name>} --save --fetch | {list | ls} | search [<keyword>] | save | @@ -314,14 +334,16 @@ cordova {plugin | plugins} [ | Sub-command | Option | Description |------------------------|-------------|------ | add `<plugin-spec>` [...] | | Add specified plugins -| |--searchpath `<directory>` | When looking up plugins by ID, look in this directory and each of its subdirectories before hitting the registry. Multiple search paths can be specified. Use ':' as a separator in *nix based systems and ';' for Windows. +| |--searchpath `<directory>` | When looking up plugins by ID, look in this directory and each of its subdirectories before hitting the registry. Multiple search paths can be specified. Use ':' as a separator in `*nix` based systems and ';' for Windows. | |--noregistry | Don't search the registry for plugins. | |--link | When installing from a local path, creates a symbolic link instead of copying files. The extent to which files are linked varies by platform. Useful for plugin development. | |--save | Save the `<plugin-spec>` as part of the `plugin` element into `config.xml`. | |--browserify | Compile plugin JS at build time using browserify instead of runtime. | |--force | _Introduced in version 6.1._ Forces copying source files from the plugin even if the same file already exists in the target directory. +| |--fetch | Fetches the plugin using `npm install` and stores it into the apps `node_modules` directory | | remove `<pluginid>|<name>` [...]| | Remove plugins with the given IDs/name. | |--save | Remove the specified plugin from config.xml +| |--fetch | Removes the plugin using `npm uninstall` and removes it from the apps `node_modules` directory | |list | | List currently installed plugins |search `[<keyword>]` [...] | | Search http://plugins.cordova.io for plugins matching the keywords |save | | Save `<plugin-spec>` of all plugins currently added to the project @@ -330,16 +352,17 @@ cordova {plugin | plugins} [ There are a number of ways to specify a plugin: - <plugin-spec> : pluginID[@version]|directory|url[#commit-ish][:subdir] + <plugin-spec> : [@scope/]pluginID[@version]|directory|url[#commit-ish][:subdir] | Value | Description |-------------|-------------------- +| scope | Scope of plugin published as a [scoped npm package] | plugin | Plugin id (id of plugin in npm registry or in --searchPath) | version | Major.minor.patch version specifier using semver | directory | Directory containing plugin.xml | url | Url to a git repository containing a plugin.xml | commit-ish | Commit/tag/branch reference. If none is specified, 'master' is used -| subdir | Sub-directory to find plugin.xml for the specified plugin. +| subdir | Sub-directory to find plugin.xml for the specified plugin. (Doesn't work with `--fetch` option) ### Algorithm for resolving plugins @@ -361,6 +384,10 @@ based on the following criteria (listed in order of precedence): cordova plugin add cordova-plugin-camera@^2.0.0 --save +- Add `cordova-plugin-camera` with [semver](http://semver.org/) version ^2.0.0 and `npm install` it. It will be stored in the `node_modules` directory: + + cordova plugin add cordova-plugin-camera@^2.0.0 --fetch + - Clone the specified git repo, checkout to tag `2.1.0`, look for plugin.xml in the `plugin` directory, and add it to the project. Save the `plugin-spec` to `config.xml`: cordova plugin add https://github.com/apache/cordova-plugin-camera.git#2.1.0:plugin --save @@ -377,6 +404,10 @@ based on the following criteria (listed in order of precedence): cordova plugin rm camera --save +- Remove the plugin from the project and `npm uninstall` it. Removes it from the `node_modules` directory: + + cordova plugin rm camera --fetch + - List all plugins installed in the project: cordova plugin ls @@ -392,7 +423,7 @@ copies plugin files for specified platforms so that the project is ready to buil ``` cordova prepare [<platform> [..]] - [--browserify] + [--browserify | --fetch] ``` ###Options @@ -401,6 +432,8 @@ cordova prepare [<platform> [..]] |------------|------------------ | `<platform> [..]` | Platform name(s) to prepare. If not specified, all platforms are built. |--browserify | Compile plugin JS at build time using browserify instead of runtime. +|--fetch | When restoring plugins or platforms, fetch will `npm install` the missing modules. + ## cordova compile command @@ -583,6 +616,38 @@ Run a local web server for www/ assets using specified `port` or default of 8000 cordova serve [port] ``` +## cordova telemetry command + +### Synopsis + +Turns telemetry collection on or off. + +### Syntax + +``` +cordova telemetry [STATE] +``` + +| Option | Description +|-------------|------------------ +| on | Turn telemetry collection on. +| off | Turn telemetry collection off. + +### Details + A timed prompt asking the user to opt-in or out is displayed the first time cordova is run. + It lasts for 30 seconds, after which the user is automatically opted-out if he doesn't provide any answer. + In CI environments, the `CI` environment variable can be set, which will prevent the prompt from showing up. + Telemetry collection can also be turned off on a single command by using the `--no-telemetry` flag. + +### Examples +``` +cordova telemetry on +cordova telemetry off +cordova build --no-telemetry +``` + +For details, see our privacy notice: https://cordova.apache.org/privacy + ## cordova help command ### Synopsis @@ -600,3 +665,4 @@ cordova -h [command] [Hooks guide]: http://cordova.apache.org/docs/en/latest/guide_appdev_hooks_index.md.html [config.xml ref]: http://cordova.apache.org/docs/en/latest/config_ref/index.html [Cordova dependencies]: http://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html#specifying-project-requirements +[scoped npm package]: https://docs.npmjs.com/misc/scope http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-camera/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/reference/cordova-plugin-camera/index.md b/www/docs/en/6.x/reference/cordova-plugin-camera/index.md index 3ecf438..a9181c1 100644 --- a/www/docs/en/6.x/reference/cordova-plugin-camera/index.md +++ b/www/docs/en/6.x/reference/cordova-plugin-camera/index.md @@ -104,8 +104,10 @@ Documentation consists of template and API docs produced from the plugin JS code --- <a name="module_camera"></a> + ## camera <a name="module_camera.getPicture"></a> + ### camera.getPicture(successCallback, errorCallback, options) Takes a photo using the camera, or retrieves a photo from the device's image gallery. The image is passed to the success callback as a @@ -173,6 +175,7 @@ More examples [here](#camera-getPicture-examples). Quirks [here](#camera-getPict navigator.camera.getPicture(cameraSuccess, cameraError, cameraOptions); ``` <a name="module_camera.cleanup"></a> + ### camera.cleanup() Removes intermediate image files that are kept in temporary storage after calling [`camera.getPicture`](#module_camera.getPicture). Applies only when the value of @@ -197,6 +200,7 @@ function onFail(message) { } ``` <a name="module_camera.onError"></a> + ### camera.onError : <code>function</code> Callback function that provides an error message. @@ -207,6 +211,7 @@ Callback function that provides an error message. | message | <code>string</code> | The message is provided by the device's native code. | <a name="module_camera.onSuccess"></a> + ### camera.onSuccess : <code>function</code> Callback function that provides the image data. @@ -226,6 +231,7 @@ function cameraCallback(imageData) { } ``` <a name="module_camera.CameraOptions"></a> + ### camera.CameraOptions : <code>Object</code> Optional parameters to customize the camera settings. * [Quirks](#CameraOptions-quirks) @@ -251,8 +257,10 @@ Optional parameters to customize the camera settings. --- <a name="module_Camera"></a> + ## Camera <a name="module_Camera.DestinationType"></a> + ### Camera.DestinationType : <code>enum</code> **Kind**: static enum property of <code>[Camera](#module_Camera)</code> **Properties** @@ -264,6 +272,7 @@ Optional parameters to customize the camera settings. | NATIVE_URI | <code>number</code> | <code>2</code> | Return native uri (eg. asset-library://... for iOS) | <a name="module_Camera.EncodingType"></a> + ### Camera.EncodingType : <code>enum</code> **Kind**: static enum property of <code>[Camera](#module_Camera)</code> **Properties** @@ -274,6 +283,7 @@ Optional parameters to customize the camera settings. | PNG | <code>number</code> | <code>1</code> | Return PNG encoded image | <a name="module_Camera.MediaType"></a> + ### Camera.MediaType : <code>enum</code> **Kind**: static enum property of <code>[Camera](#module_Camera)</code> **Properties** @@ -285,6 +295,7 @@ Optional parameters to customize the camera settings. | ALLMEDIA | <code>number</code> | <code>2</code> | Allow selection from all media types | <a name="module_Camera.PictureSourceType"></a> + ### Camera.PictureSourceType : <code>enum</code> **Kind**: static enum property of <code>[Camera](#module_Camera)</code> **Properties** @@ -296,6 +307,7 @@ Optional parameters to customize the camera settings. | SAVEDPHOTOALBUM | <code>number</code> | <code>2</code> | Choose image from picture library (same as PHOTOLIBRARY for Android) | <a name="module_Camera.PopoverArrowDirection"></a> + ### Camera.PopoverArrowDirection : <code>enum</code> Matches iOS UIPopoverArrowDirection constants to specify arrow location on popover. @@ -311,6 +323,7 @@ Matches iOS UIPopoverArrowDirection constants to specify arrow location on popov | ARROW_ANY | <code>number</code> | <code>15</code> | <a name="module_Camera.Direction"></a> + ### Camera.Direction : <code>enum</code> **Kind**: static enum property of <code>[Camera](#module_Camera)</code> **Properties** @@ -323,6 +336,7 @@ Matches iOS UIPopoverArrowDirection constants to specify arrow location on popov --- <a name="module_CameraPopoverOptions"></a> + ## CameraPopoverOptions iOS-only parameters that specify the anchor element location and arrow direction of the popover when selecting images from an iPad's library @@ -344,6 +358,7 @@ location. --- <a name="module_CameraPopoverHandle"></a> + ## CameraPopoverHandle A handle to an image picker popover. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-contacts/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/reference/cordova-plugin-contacts/index.md b/www/docs/en/6.x/reference/cordova-plugin-contacts/index.md index 5890058..9bd4f6c 100644 --- a/www/docs/en/6.x/reference/cordova-plugin-contacts/index.md +++ b/www/docs/en/6.x/reference/cordova-plugin-contacts/index.md @@ -34,11 +34,12 @@ description: Manage the contacts on the device. This plugin defines a global `navigator.contacts` object, which provides access to the device contacts database. Although the object is attached to the global scoped `navigator`, it is not available until after the `deviceready` event. - - document.addEventListener("deviceready", onDeviceReady, false); - function onDeviceReady() { - console.log(navigator.contacts); - } +```js +document.addEventListener("deviceready", onDeviceReady, false); +function onDeviceReady() { +console.log(navigator.contacts); +} +``` __WARNING__: Collection and use of contact data raises important privacy issues. Your app's privacy policy should discuss @@ -80,14 +81,15 @@ Add relevant permisions. There is also a need to change the webapp type to "privileged" - [Manifest Docs](https://developer.mozilla.org/en-US/Apps/Developing/Manifest#type). __WARNING__: All privileged apps enforce [Content Security Policy](https://developer.mozilla.org/en-US/Apps/CSP) which forbids inline script. Initialize your application in another way. - "type": "privileged", - "permissions": { - "contacts": { - "access": "readwrite", - "description": "Describe why there is a need for such permission" - } +```json +"type": "privileged", +"permissions": { + "contacts": { + "access": "readwrite", + "description": "Describe why there is a need for such permission" } - +} +``` ### Windows Quirks **Prior to Windows 10:** Any contacts returned from `find` and `pickContact` methods are readonly, so your application cannot modify them. @@ -136,7 +138,9 @@ database, for which you need to invoke the `Contact.save` method. ### Example +```js var myContact = navigator.contacts.create({"displayName": "Test User"}); +``` ## navigator.contacts.find @@ -190,22 +194,24 @@ Supported values for both __contactFields__ and __contactFindOptions.desiredFiel ### Example - function onSuccess(contacts) { - alert('Found ' + contacts.length + ' contacts.'); - }; - - function onError(contactError) { - alert('onError!'); - }; - - // find all contacts with 'Bob' in any name field - var options = new ContactFindOptions(); - options.filter = "Bob"; - options.multiple = true; - options.desiredFields = [navigator.contacts.fieldType.id]; - options.hasPhoneNumber = true; - var fields = [navigator.contacts.fieldType.displayName, navigator.contacts.fieldType.name]; - navigator.contacts.find(fields, onSuccess, onError, options); +```js +function onSuccess(contacts) { + alert('Found ' + contacts.length + ' contacts.'); +}; + +function onError(contactError) { + alert('onError!'); +}; + +// find all contacts with 'Bob' in any name field +var options = new ContactFindOptions(); +options.filter = "Bob"; +options.multiple = true; +options.desiredFields = [navigator.contacts.fieldType.id]; +options.hasPhoneNumber = true; +var fields = [navigator.contacts.fieldType.displayName, navigator.contacts.fieldType.name]; +navigator.contacts.find(fields, onSuccess, onError, options); +``` ### Windows Quirks @@ -232,11 +238,13 @@ function specified by the __contactSuccess__ parameter. ### Example - navigator.contacts.pickContact(function(contact){ - console.log('The following contact has been selected:' + JSON.stringify(contact)); - },function(err){ - console.log('Error: ' + err); - }); +```js +navigator.contacts.pickContact(function(contact){ + console.log('The following contact has been selected:' + JSON.stringify(contact)); + },function(err){ + console.log('Error: ' + err); + }); +``` ### Android Quirks @@ -321,75 +329,82 @@ for details. ### Save Example - function onSuccess(contact) { - alert("Save Success"); - }; +```js +function onSuccess(contact) { + alert("Save Success"); +}; - function onError(contactError) { - alert("Error = " + contactError.code); - }; +function onError(contactError) { + alert("Error = " + contactError.code); +}; - // create a new contact object - var contact = navigator.contacts.create(); - contact.displayName = "Plumber"; - contact.nickname = "Plumber"; // specify both to support all devices +// create a new contact object +var contact = navigator.contacts.create(); +contact.displayName = "Plumber"; +contact.nickname = "Plumber"; // specify both to support all devices - // populate some fields - var name = new ContactName(); - name.givenName = "Jane"; - name.familyName = "Doe"; - contact.name = name; +// populate some fields +var name = new ContactName(); +name.givenName = "Jane"; +name.familyName = "Doe"; +contact.name = name; - // save to device - contact.save(onSuccess,onError); +// save to device +contact.save(onSuccess,onError); +``` ### Clone Example - // clone the contact object - var clone = contact.clone(); - clone.name.givenName = "John"; - console.log("Original contact name = " + contact.name.givenName); - console.log("Cloned contact name = " + clone.name.givenName); +```js +// clone the contact object +var clone = contact.clone(); +clone.name.givenName = "John"; +console.log("Original contact name = " + contact.name.givenName); +console.log("Cloned contact name = " + clone.name.givenName); +``` ### Remove Example - function onSuccess() { - alert("Removal Success"); - }; - - function onError(contactError) { - alert("Error = " + contactError.code); - }; +```js +function onSuccess() { + alert("Removal Success"); +}; - // remove the contact from the device - contact.remove(onSuccess,onError); +function onError(contactError) { + alert("Error = " + contactError.code); +}; +// remove the contact from the device +contact.remove(onSuccess,onError); +``` ### Removing phone number(s) from a saved contact - // Example to create a contact with 3 phone numbers and then remove - // 2 phone numbers. This example is for illustrative purpose only - var myContact = navigator.contacts.create({"displayName": "Test User"}); - var phoneNumbers = []; - - phoneNumbers[0] = new ContactField('work', '768-555-1234', false); - phoneNumbers[1] = new ContactField('mobile', '999-555-5432', true); // preferred number - phoneNumbers[2] = new ContactField('home', '203-555-7890', false); - - myContact.phoneNumbers = phoneNumbers; - myContact.save(function (contact_obj) { - var contactObjToModify = contact_obj.clone(); - contact_obj.remove(function(){ - var phoneNumbers = [contactObjToModify.phoneNumbers[0]]; - contactObjToModify.phoneNumbers = phoneNumbers; - contactObjToModify.save(function(c_obj){ - console.log("All Done"); - }, function(error){ - console.log("Not able to save the cloned object: " + error); - }); - }, function(contactError) { - console.log("Contact Remove Operation failed: " + contactError); +```js +// Example to create a contact with 3 phone numbers and then remove +// 2 phone numbers. This example is for illustrative purpose only +var myContact = navigator.contacts.create({"displayName": "Test User"}); +var phoneNumbers = []; + +phoneNumbers[0] = new ContactField('work', '768-555-1234', false); +phoneNumbers[1] = new ContactField('mobile', '999-555-5432', true); // preferred number +phoneNumbers[2] = new ContactField('home', '203-555-7890', false); + +myContact.phoneNumbers = phoneNumbers; +myContact.save(function (contact_obj) { + var contactObjToModify = contact_obj.clone(); + contact_obj.remove(function(){ + var phoneNumbers = [contactObjToModify.phoneNumbers[0]]; + contactObjToModify.phoneNumbers = phoneNumbers; + contactObjToModify.save(function(c_obj){ + console.log("All Done"); + }, function(error){ + console.log("Not able to save the cloned object: " + error); }); + }, function(contactError) { + console.log("Contact Remove Operation failed: " + contactError); }); +}); +``` ### Android 2.X Quirks @@ -489,33 +504,35 @@ a `ContactAddress[]` array. ### Example - // display the address information for all contacts - - function onSuccess(contacts) { - for (var i = 0; i < contacts.length; i++) { - for (var j = 0; j < contacts[i].addresses.length; j++) { - alert("Pref: " + contacts[i].addresses[j].pref + "\n" + - "Type: " + contacts[i].addresses[j].type + "\n" + - "Formatted: " + contacts[i].addresses[j].formatted + "\n" + - "Street Address: " + contacts[i].addresses[j].streetAddress + "\n" + - "Locality: " + contacts[i].addresses[j].locality + "\n" + - "Region: " + contacts[i].addresses[j].region + "\n" + - "Postal Code: " + contacts[i].addresses[j].postalCode + "\n" + - "Country: " + contacts[i].addresses[j].country); - } +```js +// display the address information for all contacts + +function onSuccess(contacts) { + for (var i = 0; i < contacts.length; i++) { + for (var j = 0; j < contacts[i].addresses.length; j++) { + alert("Pref: " + contacts[i].addresses[j].pref + "\n" + + "Type: " + contacts[i].addresses[j].type + "\n" + + "Formatted: " + contacts[i].addresses[j].formatted + "\n" + + "Street Address: " + contacts[i].addresses[j].streetAddress + "\n" + + "Locality: " + contacts[i].addresses[j].locality + "\n" + + "Region: " + contacts[i].addresses[j].region + "\n" + + "Postal Code: " + contacts[i].addresses[j].postalCode + "\n" + + "Country: " + contacts[i].addresses[j].country); } - }; - - function onError(contactError) { - alert('onError!'); - }; - - // find all contacts - var options = new ContactFindOptions(); - options.filter = ""; - options.multiple = true; - var filter = ["displayName", "addresses"]; - navigator.contacts.find(filter, onSuccess, onError, options); + } +}; + +function onError(contactError) { + alert('onError!'); +}; + +// find all contacts +var options = new ContactFindOptions(); +options.filter = ""; +options.multiple = true; +var filter = ["displayName", "addresses"]; +navigator.contacts.find(filter, onSuccess, onError, options); +``` ### Android 2.X Quirks @@ -613,18 +630,20 @@ string. ### Example - // create a new contact - var contact = navigator.contacts.create(); +```js +// create a new contact +var contact = navigator.contacts.create(); - // store contact phone numbers in ContactField[] - var phoneNumbers = []; - phoneNumbers[0] = new ContactField('work', '212-555-1234', false); - phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number - phoneNumbers[2] = new ContactField('home', '203-555-7890', false); - contact.phoneNumbers = phoneNumbers; +// store contact phone numbers in ContactField[] +var phoneNumbers = []; +phoneNumbers[0] = new ContactField('work', '212-555-1234', false); +phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number +phoneNumbers[2] = new ContactField('home', '203-555-7890', false); +contact.phoneNumbers = phoneNumbers; - // save the contact - contact.save(); +// save the contact +contact.save(); +``` ### Android Quirks @@ -677,26 +696,28 @@ Contains different kinds of information about a `Contact` object's name. ### Example - function onSuccess(contacts) { - for (var i = 0; i < contacts.length; i++) { - alert("Formatted: " + contacts[i].name.formatted + "\n" + - "Family Name: " + contacts[i].name.familyName + "\n" + - "Given Name: " + contacts[i].name.givenName + "\n" + - "Middle Name: " + contacts[i].name.middleName + "\n" + - "Suffix: " + contacts[i].name.honorificSuffix + "\n" + - "Prefix: " + contacts[i].name.honorificSuffix); - } - }; +```js +function onSuccess(contacts) { + for (var i = 0; i < contacts.length; i++) { + alert("Formatted: " + contacts[i].name.formatted + "\n" + + "Family Name: " + contacts[i].name.familyName + "\n" + + "Given Name: " + contacts[i].name.givenName + "\n" + + "Middle Name: " + contacts[i].name.middleName + "\n" + + "Suffix: " + contacts[i].name.honorificSuffix + "\n" + + "Prefix: " + contacts[i].name.honorificSuffix); + } +}; - function onError(contactError) { - alert('onError!'); - }; +function onError(contactError) { + alert('onError!'); +}; - var options = new ContactFindOptions(); - options.filter = ""; - options.multiple = true; - filter = ["displayName", "name"]; - navigator.contacts.find(filter, onSuccess, onError, options); +var options = new ContactFindOptions(); +options.filter = ""; +options.multiple = true; +filter = ["displayName", "name"]; +navigator.contacts.find(filter, onSuccess, onError, options); +``` ### Android Quirks @@ -770,27 +791,29 @@ properties. A `Contact` object stores one or more ### Example - function onSuccess(contacts) { - for (var i = 0; i < contacts.length; i++) { - for (var j = 0; j < contacts[i].organizations.length; j++) { - alert("Pref: " + contacts[i].organizations[j].pref + "\n" + - "Type: " + contacts[i].organizations[j].type + "\n" + - "Name: " + contacts[i].organizations[j].name + "\n" + - "Department: " + contacts[i].organizations[j].department + "\n" + - "Title: " + contacts[i].organizations[j].title); - } +```js +function onSuccess(contacts) { + for (var i = 0; i < contacts.length; i++) { + for (var j = 0; j < contacts[i].organizations.length; j++) { + alert("Pref: " + contacts[i].organizations[j].pref + "\n" + + "Type: " + contacts[i].organizations[j].type + "\n" + + "Name: " + contacts[i].organizations[j].name + "\n" + + "Department: " + contacts[i].organizations[j].department + "\n" + + "Title: " + contacts[i].organizations[j].title); } - }; + } +}; - function onError(contactError) { - alert('onError!'); - }; +function onError(contactError) { + alert('onError!'); +}; - var options = new ContactFindOptions(); - options.filter = ""; - options.multiple = true; - filter = ["displayName", "organizations"]; - navigator.contacts.find(filter, onSuccess, onError, options); +var options = new ContactFindOptions(); +options.filter = ""; +options.multiple = true; +filter = ["displayName", "organizations"]; +navigator.contacts.find(filter, onSuccess, onError, options); +``` ### Android 2.X Quirks http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-dialogs/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/reference/cordova-plugin-dialogs/index.md b/www/docs/en/6.x/reference/cordova-plugin-dialogs/index.md index a487600..cb566b0 100644 --- a/www/docs/en/6.x/reference/cordova-plugin-dialogs/index.md +++ b/www/docs/en/6.x/reference/cordova-plugin-dialogs/index.md @@ -89,6 +89,7 @@ function, which is typically less customizable. - Amazon Fire OS - Android - BlackBerry 10 +- Browser - Firefox OS - iOS - Tizen @@ -153,6 +154,7 @@ indexing, so the value is `1`, `2`, `3`, etc. - Amazon Fire OS - Android - BlackBerry 10 +- Browser - Firefox OS - iOS - Tizen @@ -224,6 +226,7 @@ contains the following properties: - Amazon Fire OS - Android +- Browser - Firefox OS - iOS - Windows Phone 7 and 8 @@ -262,6 +265,7 @@ The device plays a beep sound. - Amazon Fire OS - Android - BlackBerry 10 +- Browser - iOS - Tizen - Windows Phone 7 and 8 http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1360af4b/www/docs/en/6.x/reference/cordova-plugin-file-transfer/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/reference/cordova-plugin-file-transfer/index.md b/www/docs/en/6.x/reference/cordova-plugin-file-transfer/index.md index 623bee5..454bbb3 100644 --- a/www/docs/en/6.x/reference/cordova-plugin-file-transfer/index.md +++ b/www/docs/en/6.x/reference/cordova-plugin-file-transfer/index.md @@ -35,16 +35,20 @@ This plugin allows you to upload and download files. This plugin defines global `FileTransfer`, `FileUploadOptions` constructors. Although in the global scope, they are not available until after the `deviceready` event. - document.addEventListener("deviceready", onDeviceReady, false); - function onDeviceReady() { - console.log(FileTransfer); - } +```js +document.addEventListener("deviceready", onDeviceReady, false); +function onDeviceReady() { + console.log(FileTransfer); +} +``` Report issues with this plugin on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20File%20Transfer%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC) ## Installation - cordova plugin add cordova-plugin-file-transfer +```bash +cordova plugin add cordova-plugin-file-transfer +``` ## Supported Platforms @@ -104,70 +108,74 @@ __Parameters__: ### Example - // !! Assumes variable fileURL contains a valid URL to a text file on the device, - // for example, cdvfile://localhost/persistent/path/to/file.txt +```js +// !! Assumes variable fileURL contains a valid URL to a text file on the device, +// for example, cdvfile://localhost/persistent/path/to/file.txt - var win = function (r) { - console.log("Code = " + r.responseCode); - console.log("Response = " + r.response); - console.log("Sent = " + r.bytesSent); - } +var win = function (r) { + console.log("Code = " + r.responseCode); + console.log("Response = " + r.response); + console.log("Sent = " + r.bytesSent); +} - var fail = function (error) { - alert("An error has occurred: Code = " + error.code); - console.log("upload error source " + error.source); - console.log("upload error target " + error.target); - } +var fail = function (error) { + alert("An error has occurred: Code = " + error.code); + console.log("upload error source " + error.source); + console.log("upload error target " + error.target); +} - var options = new FileUploadOptions(); - options.fileKey = "file"; - options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1); - options.mimeType = "text/plain"; +var options = new FileUploadOptions(); +options.fileKey = "file"; +options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1); +options.mimeType = "text/plain"; - var params = {}; - params.value1 = "test"; - params.value2 = "param"; +var params = {}; +params.value1 = "test"; +params.value2 = "param"; - options.params = params; +options.params = params; - var ft = new FileTransfer(); - ft.upload(fileURL, encodeURI("http://some.server.com/upload.php";), win, fail, options); +var ft = new FileTransfer(); +ft.upload(fileURL, encodeURI("http://some.server.com/upload.php";), win, fail, options); +``` ### Example with Upload Headers and Progress Events (Android and iOS only) - function win(r) { - console.log("Code = " + r.responseCode); - console.log("Response = " + r.response); - console.log("Sent = " + r.bytesSent); - } +```js +function win(r) { + console.log("Code = " + r.responseCode); + console.log("Response = " + r.response); + console.log("Sent = " + r.bytesSent); +} - function fail(error) { - alert("An error has occurred: Code = " + error.code); - console.log("upload error source " + error.source); - console.log("upload error target " + error.target); - } +function fail(error) { + alert("An error has occurred: Code = " + error.code); + console.log("upload error source " + error.source); + console.log("upload error target " + error.target); +} - var uri = encodeURI("http://some.server.com/upload.php";); +var uri = encodeURI("http://some.server.com/upload.php";); - var options = new FileUploadOptions(); - options.fileKey="file"; - options.fileName=fileURL.substr(fileURL.lastIndexOf('/')+1); - options.mimeType="text/plain"; +var options = new FileUploadOptions(); +options.fileKey="file"; +options.fileName=fileURL.substr(fileURL.lastIndexOf('/')+1); +options.mimeType="text/plain"; - var headers={'headerParam':'headerValue'}; +var headers={'headerParam':'headerValue'}; - options.headers = headers; - - var ft = new FileTransfer(); - ft.onprogress = function(progressEvent) { - if (progressEvent.lengthComputable) { - loadingStatus.setPercentage(progressEvent.loaded / progressEvent.total); - } else { - loadingStatus.increment(); - } - }; - ft.upload(fileURL, uri, win, fail, options); +options.headers = headers; +var ft = new FileTransfer(); +ft.onprogress = function(progressEvent) { + if (progressEvent.lengthComputable) { + loadingStatus.setPercentage(progressEvent.loaded / progressEvent.total); + } else { + loadingStatus.increment(); + } +}; +ft.upload(fileURL, uri, win, fail, options); +``` + ## FileUploadResult A `FileUploadResult` object is passed to the success callback of the @@ -214,30 +222,32 @@ __Parameters__: ### Example - // !! Assumes variable fileURL contains a valid URL to a path on the device, - // for example, cdvfile://localhost/persistent/path/to/downloads/ - - var fileTransfer = new FileTransfer(); - var uri = encodeURI("http://some.server.com/download.php";); - - fileTransfer.download( - uri, - fileURL, - function(entry) { - console.log("download complete: " + entry.toURL()); - }, - function(error) { - console.log("download error source " + error.source); - console.log("download error target " + error.target); - console.log("upload error code" + error.code); - }, - false, - { - headers: { - "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA==" - } +```js +// !! Assumes variable fileURL contains a valid URL to a path on the device, +// for example, cdvfile://localhost/persistent/path/to/downloads/ + +var fileTransfer = new FileTransfer(); +var uri = encodeURI("http://some.server.com/download.php";); + +fileTransfer.download( + uri, + fileURL, + function(entry) { + console.log("download complete: " + entry.toURL()); + }, + function(error) { + console.log("download error source " + error.source); + console.log("download error target " + error.target); + console.log("upload error code" + error.code); + }, + false, + { + headers: { + "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA==" } - ); + } +); +``` ### WP8 Quirks @@ -253,29 +263,30 @@ Aborts an in-progress transfer. The onerror callback is passed a FileTransferErr ### Example - // !! Assumes variable fileURL contains a valid URL to a text file on the device, - // for example, cdvfile://localhost/persistent/path/to/file.txt - - var win = function(r) { - console.log("Should not be called."); - } +```js +// !! Assumes variable fileURL contains a valid URL to a text file on the device, +// for example, cdvfile://localhost/persistent/path/to/file.txt - var fail = function(error) { - // error.code == FileTransferError.ABORT_ERR - alert("An error has occurred: Code = " + error.code); - console.log("upload error source " + error.source); - console.log("upload error target " + error.target); - } +var win = function(r) { + console.log("Should not be called."); +} - var options = new FileUploadOptions(); - options.fileKey="file"; - options.fileName="myphoto.jpg"; - options.mimeType="image/jpeg"; +var fail = function(error) { + // error.code == FileTransferError.ABORT_ERR + alert("An error has occurred: Code = " + error.code); + console.log("upload error source " + error.source); + console.log("upload error target " + error.target); +} - var ft = new FileTransfer(); - ft.upload(fileURL, encodeURI("http://some.server.com/upload.php";), win, fail, options); - ft.abort(); +var options = new FileUploadOptions(); +options.fileKey="file"; +options.fileName="myphoto.jpg"; +options.mimeType="image/jpeg"; +var ft = new FileTransfer(); +ft.upload(fileURL, encodeURI("http://some.server.com/upload.php";), win, fail, options); +ft.abort(); +``` ## FileTransferError @@ -325,3 +336,253 @@ If you are upgrading to a new (1.0.0 or newer) version of File, and you have pre cdvfile://localhost/persistent/path/to/file which can be used in place of the absolute file path in both `download()` and `upload()` methods. + +## Sample: Download and Upload Files <a name="sample"></a> + +Use the File-Transfer plugin to upload and download files. In these examples, we demonstrate several tasks like: + +* [Downloading a binary file to the application cache](#binaryFile) +* [Uploading a file created in your application's root](#uploadFile) +* [Downloading the uploaded file](#downloadFile) + +## Download a Binary File to the application cache <a name="binaryFile"></a> + +Use the File plugin with the File-Transfer plugin to provide a target for the files that you download (the target must be a FileEntry object). Before you download the file, create a DirectoryEntry object by using `resolveLocalFileSystemURL` and calling `fs.root` in the success callback. Use the `getFile` method of DirectoryEntry to create the target file. + +```js +window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) { + + console.log('file system open: ' + fs.name); + + // Make sure you add the domain name to the Content-Security-Policy <meta> element. + var url = 'http://cordova.apache.org/static/img/cordova_bot.png'; + // Parameters passed to getFile create a new file or return the file if it already exists. + fs.root.getFile('downloaded-image.png', { create: true, exclusive: false }, function (fileEntry) { + download(fileEntry, url, true); + + }, onErrorCreateFile); + +}, onErrorLoadFs); +``` + +>*Note* For persistent storage, pass LocalFileSystem.PERSISTENT to requestFileSystem. + +When you have the FileEntry object, download the file using the `download` method of the FileTransfer object. The 3rd argument to the `download` function of FileTransfer is the success callback, which you can use to call the app's `readBinaryFile` function. In this code example, the `entry` variable is a new FileEntry object that receives the result of the download operation. + +```js +function download(fileEntry, uri, readBinaryData) { + + var fileTransfer = new FileTransfer(); + var fileURL = fileEntry.toURL(); + + fileTransfer.download( + uri, + fileURL, + function (entry) { + console.log("Successful download..."); + console.log("download complete: " + entry.toURL()); + if (readBinaryData) { + // Read the file... + readBinaryFile(entry); + } + else { + // Or just display it. + displayImageByFileURL(entry); + } + }, + function (error) { + console.log("download error source " + error.source); + console.log("download error target " + error.target); + console.log("upload error code" + error.code); + }, + null, // or, pass false + { + //headers: { + // "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA==" + //} + } + ); +} +``` + +If you just need to display the image, take the FileEntry to call its toURL() function. + +```js +function displayImageByFileURL(fileEntry) { + var elem = document.getElementById('imageFile'); + elem.src = fileEntry.toURL(); +} +``` + +Depending on your app requirements, you may want to read the file. To support operations with binary files, FileReader supports two methods, `readAsBinaryString` and `readAsArrayBuffer`. In this example, use `readAsArrayBuffer` and pass the FileEntry object to the method. Once you read the file successfully, construct a Blob object using the result of the read. + +```js +function readBinaryFile(fileEntry) { + fileEntry.file(function (file) { + var reader = new FileReader(); + + reader.onloadend = function() { + + console.log("Successful file read: " + this.result); + // displayFileData(fileEntry.fullPath + ": " + this.result); + + var blob = new Blob([new Uint8Array(this.result)], { type: "image/png" }); + displayImage(blob); + }; + + reader.readAsArrayBuffer(file); + + }, onErrorReadFile); +} +``` + +Once you read the file successfully, you can create a DOM URL string using `createObjectURL`, and then display the image. + +```js +function displayImage(blob) { + + // Note: Use window.URL.revokeObjectURL when finished with image. + var objURL = window.URL.createObjectURL(blob); + + // Displays image if result is a valid DOM string for an image. + var elem = document.getElementById('imageFile'); + elem.src = objURL; +} +``` + +As you saw previously, you can call FileEntry.toURL() instead to just display the downloaded image (skip the file read). + +## Upload a File <a name="uploadFile"></a> + +When you upload a File using the File-Transfer plugin, use the File plugin to provide files for upload (again, they must be FileEntry objects). Before you can upload anything, create a file for upload using the `getFile` method of DirectoryEntry. In this example, create the file in the application's cache (fs.root). Then call the app's writeFile function so you have some content to upload. + +```js +function onUploadFile() { + window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) { + + console.log('file system open: ' + fs.name); + var fileName = "uploadSource.txt"; + var dirEntry = fs.root; + dirEntry.getFile(fileName, { create: true, exclusive: false }, function (fileEntry) { + + // Write something to the file before uploading it. + writeFile(fileEntry); + + }, onErrorCreateFile); + + }, onErrorLoadFs); +} +``` + +In this example, create some simple content, and then call the app's upload function. + +```js +function writeFile(fileEntry, dataObj) { + // Create a FileWriter object for our FileEntry (log.txt). + fileEntry.createWriter(function (fileWriter) { + + fileWriter.onwriteend = function () { + console.log("Successful file write..."); + upload(fileEntry); + }; + + fileWriter.onerror = function (e) { + console.log("Failed file write: " + e.toString()); + }; + + if (!dataObj) { + dataObj = new Blob(['file data to upload'], { type: 'text/plain' }); + } + + fileWriter.write(dataObj); + }); +} +``` + +Forward the FileEntry object to the upload function. To perform the actual upload, use the upload function of the FileTransfer object. + +```js +function upload(fileEntry) { + // !! Assumes variable fileURL contains a valid URL to a text file on the device, + var fileURL = fileEntry.toURL(); + + var success = function (r) { + console.log("Successful upload..."); + console.log("Code = " + r.responseCode); + displayFileData(fileEntry.fullPath + " (content uploaded to server)"); + } + + var fail = function (error) { + alert("An error has occurred: Code = " + error.code); + } + + var options = new FileUploadOptions(); + options.fileKey = "file"; + options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1); + options.mimeType = "text/plain"; + + var params = {}; + params.value1 = "test"; + params.value2 = "param"; + + options.params = params; + + var ft = new FileTransfer(); + // SERVER must be a URL that can handle the request, like + // http://some.server.com/upload.php + ft.upload(fileURL, encodeURI(SERVER), success, fail, options); +}; +``` + +## Download the uploaded file <a name="downloadFile"></a> + +To download the image you just uploaded, you will need a valid URL that can handle the request, for example, http://some.server.com/download.php. Again, the success handler for the FileTransfer.download method receives a FileEntry object. The main difference here from previous examples is that we call FileReader.readAsText to read the result of the download operation, because we uploaded a file with text content. + +```js +function download(fileEntry, uri) { + + var fileTransfer = new FileTransfer(); + var fileURL = fileEntry.toURL(); + + fileTransfer.download( + uri, + fileURL, + function (entry) { + console.log("Successful download..."); + console.log("download complete: " + entry.toURL()); + readFile(entry); + }, + function (error) { + console.log("download error source " + error.source); + console.log("download error target " + error.target); + console.log("upload error code" + error.code); + }, + null, // or, pass false + { + //headers: { + // "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA==" + //} + } + ); +} +``` + +In the readFile function, call the `readAsText` method of the FileReader object. + +```js +function readFile(fileEntry) { + fileEntry.file(function (file) { + var reader = new FileReader(); + + reader.onloadend = function () { + + console.log("Successful file read: " + this.result); + // displayFileData(fileEntry.fullPath + ": " + this.result); + + }; + + reader.readAsText(file); + + }, onErrorReadFile); +} +``` --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org For additional commands, e-mail: commits-h...@cordova.apache.org
