http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova-plugin-whitelist.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/gen/cordova-plugin-whitelist.md b/www/docs/en/6.x/gen/cordova-plugin-whitelist.md new file mode 100644 index 0000000..9bf6b39 --- /dev/null +++ b/www/docs/en/6.x/gen/cordova-plugin-whitelist.md @@ -0,0 +1,158 @@ +--- +edit_link: 'https://github.com/apache/cordova-plugin-whitelist/blob/master/README.md' +permalink: /docs/en/6.x/cordova-plugin-whitelist/index.html +plugin_name: cordova-plugin-whitelist +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. +--> + +# cordova-plugin-whitelist + +This plugin implements a whitelist policy for navigating the application webview on Cordova 4.0 + +:warning: 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%20Whitelist%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC) + + +## Supported Cordova Platforms + +* Android 4.0.0 or above + +## Navigation Whitelist +Controls which URLs the WebView itself can be navigated to. Applies to +top-level navigations only. + +Quirks: on Android it also applies to iframes for non-http(s) schemes. + +By default, navigations only to `file://` URLs, are allowed. To allow others URLs, you must add `<allow-navigation>` tags to your `config.xml`: + + <!-- Allow links to example.com --> + <allow-navigation href="http://example.com/*"; /> + + <!-- Wildcards are allowed for the protocol, as a prefix + to the host, or as a suffix to the path --> + <allow-navigation href="*://*.example.com/*" /> + + <!-- A wildcard can be used to whitelist the entire network, + over HTTP and HTTPS. + *NOT RECOMMENDED* --> + <allow-navigation href="*" /> + + <!-- The above is equivalent to these three declarations --> + <allow-navigation href="http://*/*"; /> + <allow-navigation href="https://*/*"; /> + <allow-navigation href="data:*" /> + +## Intent Whitelist +Controls which URLs the app is allowed to ask the system to open. +By default, no external URLs are allowed. + +On Android, this equates to sending an intent of type BROWSEABLE. + +This whitelist does not apply to plugins, only hyperlinks and calls to `window.open()`. + +In `config.xml`, add `<allow-intent>` tags, like this: + + <!-- Allow links to web pages to open in a browser --> + <allow-intent href="http://*/*"; /> + <allow-intent href="https://*/*"; /> + + <!-- Allow links to example.com to open in a browser --> + <allow-intent href="http://example.com/*"; /> + + <!-- Wildcards are allowed for the protocol, as a prefix + to the host, or as a suffix to the path --> + <allow-intent href="*://*.example.com/*" /> + + <!-- Allow SMS links to open messaging app --> + <allow-intent href="sms:*" /> + + <!-- Allow tel: links to open the dialer --> + <allow-intent href="tel:*" /> + + <!-- Allow geo: links to open maps --> + <allow-intent href="geo:*" /> + + <!-- Allow all unrecognized URLs to open installed apps + *NOT RECOMMENDED* --> + <allow-intent href="*" /> + +## Network Request Whitelist +Controls which network requests (images, XHRs, etc) are allowed to be made (via cordova native hooks). + +Note: We suggest you use a Content Security Policy (see below), which is more secure. This whitelist is mostly historical for webviews which do not support CSP. + +In `config.xml`, add `<access>` tags, like this: + + <!-- Allow images, xhrs, etc. to google.com --> + <access origin="http://google.com"; /> + <access origin="https://google.com"; /> + + <!-- Access to the subdomain maps.google.com --> + <access origin="http://maps.google.com"; /> + + <!-- Access to all the subdomains on google.com --> + <access origin="http://*.google.com"; /> + + <!-- Enable requests to content: URLs --> + <access origin="content:///*" /> + + <!-- Don't block any requests --> + <access origin="*" /> + +Without any `<access>` tags, only requests to `file://` URLs are allowed. However, the default Cordova application includes `<access origin="*">` by default. + + +Note: Whitelist cannot block network redirects from a whitelisted remote website (i.e. http or https) to a non-whitelisted website. Use CSP rules to mitigate redirects to non-whitelisted websites for webviews that support CSP. + +Quirk: Android also allows requests to https://ssl.gstatic.com/accessibility/javascript/android/ by default, since this is required for TalkBack to function properly. + +### Content Security Policy +Controls which network requests (images, XHRs, etc) are allowed to be made (via webview directly). + +On Android and iOS, the network request whitelist (see above) is not able to filter all types of requests (e.g. `<video>` & WebSockets are not blocked). So, in addition to the whitelist, you should use a [Content Security Policy](http://content-security-policy.com/) `<meta>` tag on all of your pages. + +On Android, support for CSP within the system webview starts with KitKat (but is available on all versions using Crosswalk WebView). + +Here are some example CSP declarations for your `.html` pages: + + <!-- Good default declaration: + * gap: is required only on iOS (when using UIWebView) and is needed for JS->native communication + * https://ssl.gstatic.com is required only on Android and is needed for TalkBack to function properly + * Disables use of eval() and inline scripts in order to mitigate risk of XSS vulnerabilities. To change this: + * Enable inline JS: add 'unsafe-inline' to default-src + * Enable eval(): add 'unsafe-eval' to default-src + --> + <meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com; style-src 'self' 'unsafe-inline'; media-src *"> + + <!-- Allow everything but only from the same origin and foo.com --> + <meta http-equiv="Content-Security-Policy" content="default-src 'self' foo.com"> + + <!-- This policy allows everything (eg CSS, AJAX, object, frame, media, etc) except that + * CSS only from the same origin and inline styles, + * scripts only from the same origin and inline styles, and eval() + --> + <meta http-equiv="Content-Security-Policy" content="default-src *; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'unsafe-eval'"> + + <!-- Allows XHRs only over HTTPS on the same domain. --> + <meta http-equiv="Content-Security-Policy" content="default-src 'self' https:"> + + <!-- Allow iframe to https://cordova.apache.org/ --> + <meta http-equiv="Content-Security-Policy" content="default-src 'self'; frame-src 'self' https://cordova.apache.org";>
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/gen/cordova.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/gen/cordova.md b/www/docs/en/6.x/gen/cordova.md new file mode 100644 index 0000000..7360739 --- /dev/null +++ b/www/docs/en/6.x/gen/cordova.md @@ -0,0 +1,586 @@ +--- +edit_link: 'https://github.com/apache/cordova-cli/blob/master/doc/readme.md' +permalink: /docs/en/6.x/cordova-cli/index.html +title: CLI Reference +description: Learn how to use Cordova CLI commands and their options. +--- + +<!-- +# +# 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. +# +--> + +# Cordova Command-line-interface (CLI) Reference + +## Syntax + +```bash +cordova <command> [options] -- [platformOpts] +``` + +## Global Command List + +These commands are available at all times. + +| Command | Description +|----------|-------------- +| create | Create a project +| help <command> | Get help for a command + +## Project Command List + +These commands are supported when the current working directory is a valid Cordova project. + +| Command | Description +|--------------|-------------- +| info | Generate project information +| requirements | Checks and print out all the installation requirements for platforms specified +| platform | Manage project platforms +| plugin | Manage project plugins +| prepare | Copy files into platform(s) for building +| compile | Build platform(s) +| clean | Cleanup project from build artifacts +| run | Run project (including prepare && compile) +| serve | Run project with a local webserver (including prepare) + +## Common options + +These options apply to all cordova-cli commands. + +| Option | Description +|----------------------|------------------------ +| -d or --verbose | Pipe out more verbose output to your shell. You can also subscribe to `log` and `warn` events if you are consuming `cordova-cli` as a node module by calling `cordova.on('log', function() {})` or `cordova.on('warn', function() {})`. +| -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) + +## Platform-specific options + +Certain commands have options (`platformOpts`) that are specific to a particular platform. They can be provided to the cordova-cli with a '--' separator that stops the command parsing within the cordova-lib module and passes through rest of the options for platforms to parse. + +## Examples +- This example demonstrates how cordova-cli can be used to create a project with the `camera` plugin and run it for `android` platform. In particular, platform specific options like `--keystore` can be provided: + + # Create a cordova project + cordova create myApp com.myCompany.myApp myApp + cd myApp + # Add camera plugin to the project and remember that in config.xml + cordova plugin add cordova-plugin-camera --save + # Add android platform to the project and remember that in config.xml + cordova platform add android --save + # Check to see if your system is configured for building android platform. + cordova requirements android + # Build the android and emit verbose logs. + cordova build android --verbose + # Run the project on the android platform. + cordova run android + # Build for android platform in release mode with specified signing parameters. + cordova build android --release -- --keystore="..\android.keystore" --storePassword=android --alias=mykey + +## cordova create command + +### Synopsis + +Create the directory structure for the Cordova project in the specified path. + +### Syntax + +``` +cordova create path [id [name [config]]] [options] +``` + +| Value | Description | +|-------|---------------| +| path | Directory which should not already exist. Cordova will create this directory. For more details on the directory structure, see below. | +| id | _Default_: `io.cordova.hellocordova` <br/> Reverse domain-style identifier that maps to `id` attirbute of `widget` element in `config.xml`. This can be changed but there may be code generated using this value, such as Java package names. It is recommended that you select an appropriate value. | +| name | _Default_: `HelloCordova` <br/> Application's display title that maps `name` element in `config.xml` file. This can be changed but there may be code generated using this value, such as Java class names. The default value is `HelloCordova`, but it is recommended that you select an appropriate value. | +| config | JSON string whose key/values will be included in `<path>`/.cordova/config.json | + +### Options + +| Option | Description | +|--------|-------------| +| --template | Use a custom template located locally, in NPM, or GitHub. | +| --copy-from\|--src | _Deprecated_ <br/> Use --template instead. Specifies a directory from which to copy the current Cordova project. | +|--link-to | Symlink to specified `www` directory without creating a copy. | + +### Directory structure + +A Cordova application created with `cordova-cli` will have the following directory structure: + +``` +myapp/ +|-- config.xml +|-- hooks/ +|-- merges/ +| | |-- android/ +| | |-- windows/ +| | -- ios/ +|-- www/ +|-- platforms/ +| |-- android/ +| |-- windows/ +| -- ios/ +-- plugins/ +``` + +#### config.xml + +Configures your application and allows you to customize the behavior of your project. See also [config.xml reference documentation][config.xml ref] + +#### www/ + +Contains the project's web artifacts, such as .html, .css and .js files. As a cordova application developer, most of your code and assets will go here. They will be copied on a `cordova prepare` to each platform's www directory. The www source directory is reproduced within each platform's subdirectory, appearing for example in `platforms/ios/www` or `platforms/android/assets/www`. Because the CLI constantly copies over files from the source www folder, you should only edit these files and not the ones located under the platforms subdirectories. If you use version control software, you should add this source www folder, along with the merges folder, to your version control system. + +#### platforms/ + +Contains all the source code and build scripts for the platforms that you add to your project. + +> **WARNING:** When using the CLI to build your application, you should not edit any files in the /platforms/ directory unless you know what you are doing, or if documentation specifies otherwise. The files in this directory are routinely overwritten when preparing applications for building, or when plugins are re-installed. + +#### plugins/ + +Any added plugins will be extracted or copied into this directory. + +#### hooks/ + +This directory may contains scripts used to customize cordova-cli commands. Any scripts you add to these directories will be executed before and after the commands corresponding to the directory name. Useful for integrating your own build systems or integrating with version control systems. + +Refer to [Hooks Guide] for more information. + +#### merges/ + +Platform-specific web assets (HTML, CSS and JavaScript files) are contained within appropriate subfolders in this directory. These are deployed during a `prepare` to the appropriate native directory. Files placed under `merges/` will override matching files in the `www/` folder for the relevant platform. A quick example, assuming a project structure of: + +``` +merges/ +|-- ios/ +| -- app.js +|-- android/ +| -- android.js +www/ +-- app.js +``` + +After building the Android and iOS projects, the Android application will contain both `app.js` and `android.js`. However, the iOS application will only contain an `app.js`, and it will be the one from `merges/ios/app.js`, overriding the "common" `app.js` located inside `www/`. + +#### Version control + +It is recommended not to check in `platforms/` and `plugins/` directories into version control as they are considered a build artifact. Instead, you should save the platform/plugin spec in the `config.xml` and they will be downloaded when on the machine when `cordova prepare` is invoked. + +### Examples + +- Create a Cordova project in `myapp` directory using the specified ID and display name: + + cordova create myapp com.mycompany.myteam.myapp MyApp + +- Create a Cordova project with a symlink to an existing `www` directory. This can be useful if you have a custom build process or existing web assets that you want to use in your Cordova app: + + cordova create myapp --link-to=../www + + +## cordova platform command + +### Synopsis + +Manage cordova platforms - allowing you to add, remove, update, list and check for updates. Running commands to add or remove platforms affects the contents of the project's platforms directory. + +### Syntax + +```bash +cordova {platform | platforms} [ + add <platform-spec> [...] {--save | link=<path> } | + {remove | rm} platform [...] | + {list | ls} | + check | + save ] +``` + +| Sub-command | Option | Description | +------------------------|-------------|------| +| 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) +| remove `<platform>` [...] | | Remove specified platforms | +| | --save | Delete specified platforms from `config.xml` after removing them | +| update `platform` [...] | | Update specified platforms | +| | --save | Updates the version specified in `config.xml` | +| 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 | + +### Platform-spec + +There are a number of ways to specify a platform: + +``` +<platform-spec> : platform[@version] | path | url[#commit-ish] +``` + +| Value | Description | +|-----------|-------------| +| platform | Platform name e.g. android, ios, windows etc. to be added to the project. Every release of cordova CLI pins a version for each platform. When no version is specified this version is used to add the platform. | +| version | Major.minor.patch version specifier using semver | +| path | Path to a directory or tarball containing a platform | +| url | URL to a git repository or tarball containing a platform | +| commit-ish | Commit/tag/branch reference. If none is specified, 'master' is used | + +### Supported Platforms + +- Android +- iOS +- Windows (8.1, Phone 8.1, UWP - Windows 10) +- Blackberry10 +- Ubuntu +- Browser + +### Deprecated Platforms + +- Amazon-fireos (use Android platform instead) +- WP8 (use Windows platform instead) +- Windows 8.0 (use older versions of cordova) +- Firefox OS (use older versions of cordova) + +### Examples + +- Add pinned version of the `android` and `ios` platform and save the downloaded version to `config.xml`: + + cordova platform add android ios --save + +- 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 + +- Add platform by cloning the specified git repo and checkout to the `4.0.0` tag: + + cordova platform add https://github.com/myfork/cordova-android.git#4.0.0 + +- Add platform using a local directory named `android`: + + cordova platform add ../android + +- Add platform using the specified tarball: + + cordova platform add ../cordova-android.tgz + +- Remove `android` platform from the project and from `config.xml`: + + cordova platform rm android --save + +- List available and installed platforms with version numbers. This is useful to find version numbers when reporting issues: + + cordova platform ls + +- Save versions of all platforms currently added to the project to `config.xml`. + + cordova platform save + +## cordova plugin command + +### Synopsis + +Manage project plugins + +### Syntax + +```bash +cordova {plugin | plugins} [ + add <plugin-spec> [..] {--searchpath=<directory> | --noregistry | --link | --save | --browserify} | + {remove | rm} {<pluginid> | <name>} --save | + {list | ls} | + search [<keyword>] | + save | +] +``` + +| 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. +| |--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. +| remove `<pluginid>|<name>` [...]| | Remove plugins with the given IDs/name. +| |--save | Remove the specified plugin from config.xml +|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 + +### Plugin-spec + +There are a number of ways to specify a plugin: + + <plugin-spec> : pluginID[@version]|directory|url[#commit-ish][:subdir] + +| Value | Description +|-------------|-------------------- +| 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. + +### Examples + +- Add `cordova-plugin-camera` and `cordova-plugin-file` to the project and save it to `config.xml`. Use `../plugins` directory to search for the plugins. + + cordova plugin add cordova-plugin-camera cordova-plugin-file --save --searchpath ../plugins + +- Add `cordova-plugin-camera` with [semver](http://semver.org/) version ^2.0.0 and save it to `config.xml`: + + cordova plugin add cordova-plugin-camera@^2.0.0 --save + +- 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 + +- Add the plugin from the specified local directory: + + cordova plugin add ../cordova-plugin-camera + +- Add the plugin from the specified tarball file: + + cordova plugin add ../cordova-plugin-camera.tgz --save + +- Remove the plugin from the project and the `config.xml`: + + cordova plugin rm camera --save + +- List all plugins installed in the project: + + cordova plugin ls + +## cordova prepare command + +### Synopsis + +Transforms config.xml metadata to platform-specific manifest files, copies icons & splashscreens, +copies plugin files for specified platforms so that the project is ready to build with each native SDK. + +### Syntax + +``` +cordova prepare [<platform> [..]] + [--browserify] +``` + +###Options + +| Option | Description +|------------|------------------ +| `<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. + +## cordova compile command + +### Synopsis + +`cordova compile` is a subset of the [cordova build command](#cordova-build-command). +It only performs the compilation step without doing prepare. It's common to invoke `cordova build` instead of this command - however, this stage is useful to allow extending using [hooks][Hooks guide]. + +###Syntax + +```bash +cordova build [<platform> [...]] + [--debug|--release] + [--device|--emulator|--target=<targetName>] + [--buildConfig=<configfile>] + [--browserify] + [-- <platformOpts>] +``` +For detailed documentation see [cordova build command](#cordova-build-command) docs below. + +## cordova build command + +### Synopsis + +Shortcut for `cordova prepare` + `cordova compile` for all/the specified platforms. Allows you to build the app for the specified platform. + +### Syntax + +```bash +cordova build [<platform> [...]] + [--debug|--release] + [--device|--emulator] + [--buildConfig=<configfile>] + [--browserify] + [-- <platformOpts>] +``` + +| Option | Description +|------------|------------------ +| `<platform> [..]` | Platform name(s) to build. If not specified, all platforms are built. +| --debug | Perform a debug build. This typically translates to debug mode for the underlying platform being built. +| --release | Perform a release build. This typically translates to release mode for the underlying platform being built. +| --device | Build it for a device +| --emulator | Build it for an emulator. In particular, the platform architecture might be different for a device Vs emulator. +| --buildConfig=`<configFile>` | Default: build.json in cordova root directory. <br/> Use the specified build configuration file. `build.json` file is used to specify paramaters to customize the app build process esecially related to signing the package. +| --browserify | Compile plugin JS at build time using browserify instead of runtime +| `<platformOpts>` | To provide platform specific options, you must include them after `--` separator. Review platform guide docs for more details. + +### Examples + +- Build for `android` and `windows` platform in `debug` mode for deployment to device: + + cordova build android windows --debug --device + +- Build for `android` platform in `release` mode and use the specified build configuration: + + cordova build android --release --buildConfig=..\myBuildConfig.json + +- Build for `android` platform in release mode and pass custom platform options to android build process: + + cordova build android --release -- --keystore="..\android.keystore" --storePassword=android --alias=mykey + +## cordova run command + +### Synopsis + +Prepares, builds (unless `--nobuild` is specified) and deploys app on specified platform devices/emulators. If a device is connected it will be used, unless an eligible emulator is already running. + +###Syntax + +```bash +cordova run [<platform> [...]] + [--list | --nobuild ] + [--device|--emulator|--target=<targetName>] + [--buildConfig=<configfile>] + [--browserify] + [-- <platformOpts>] +``` + +| Option | Description +|------------|------------------ +| `<platform> [..]` | Platform name(s) to run. If not specified, all platforms are run. +|--nobuild | Skip building +|--debug | Deploy a debug build. This is the default behavior unless `--release` is specified. +|--release | Deploy a release build +|--device | Deploy to a device +|--emulator | Deploy to an emulator +|--target | Deploy to a specific target emulator/device. Use `--list` to display target options +| --list | Lists available targets. Displays both device and emulator deployment targets unless specified +| --buildConfig=`<configFile>` | Default: build.json in cordova root directory. <br/> Use the specified build configuration file. `build.json` file is used to specify paramaters to customize the app build process esecially related to signing the package. +| --browserify | Compile plugin JS at build time using browserify instead of runtime +| `<platformOpts>` | To provide platform specific options, you must include them after `--` separator. Review platform guide docs for more details. + +###Examples + +- Run a release build of current cordova project on `android` platform emulator named `Nexus_5_API_23_x86`. Use the spcified build configuration when running: + + cordova run android --release --buildConfig=..\myBuildConfig.json --target=Nexus_5_API_23_x86 + +- Run a debug build of current cordova project on `android` platform using a device or emulator (if no device is connected). Skip doing the build: + + cordova run android --nobuild + +- Run a debug build of current cordova project on an `ios` device: + + cordova run ios --device + +- Enumerate names of all the connected devices and available emulators that can be used to run this app: + + cordova run ios --list + + +## cordova emulate command + +### Synopsis + +Alias for `cordova run --emulator`. Launches the emulator instead of device. +See [cordova run command docs](#cordova-run-command) for more details. + +## cordova clean command + +### Synopsis + +Cleans the build artifacts for the specified platform, or all platforms by running platform-specific build cleanup. + +### Syntax + +``` +cordova clean [<platform> [...]] +``` + +### Example + +- Clean `android` platform build artifiacts: + + cordova clean android + + +## cordova requirements command + +### Synopsis + +Checks and print out all the requirements for platforms specified (or all platforms added +to project if none specified). If all requirements for each platform are met, exits with code 0 +otherwise exits with non-zero code. + +This can be useful when setting up a machine for building a particular platform. + +### Syntax + +``` +cordova requirements android +``` + +## cordova info command + +### Synopsis + +Print out useful information helpful for submitting bug +reports and getting help. Creates an info.txt file at the +base of your project. + +### Syntax + +``` +cordova info +``` + +## cordova serve command + +### Synopsis + +Run a local web server for www/ assets using specified `port` or default of 8000. Access projects at: `http://HOST_IP:PORT/PLATFORM/www` + +### Syntax + +``` +cordova serve [port] +``` + +## cordova help command + +### Synopsis + +Show syntax summary, or the help for a specific command. + +### Syntax + +``` +cordova help [command] +cordova [command] -h +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 http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/guide/appdev/hooks/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/guide/appdev/hooks/index.md b/www/docs/en/6.x/guide/appdev/hooks/index.md index 4396adb..454f2e5 100644 --- a/www/docs/en/6.x/guide/appdev/hooks/index.md +++ b/www/docs/en/6.x/guide/appdev/hooks/index.md @@ -20,91 +20,194 @@ license: > title: Hooks Guide --- -# Hooks Guide +# Hooks + +## Introduction Cordova Hooks represent special scripts which could be added by application and plugin developers or even by your own build system to customize cordova commands. -Hook scripts could be defined by adding them to the special predefined folder -(`/hooks`) or via configuration files (`config.xml` and `plugin.xml`) and run -serially in the following order: - -* Application hooks from `/hooks`; -* Application hooks from `config.xml`; -* Plugin hooks from `plugins/.../plugin.xml`. - -__Note__: `/hooks` directory is considered deprecated in favor of the hook elements -in config.xml and plugin.xml. -## Supported hook types -The following hook types are supported: - - after_build - after_compile - after_clean - after_docs - after_emulate - after_platform_add - after_platform_rm - after_platform_ls - after_plugin_add - after_plugin_ls - after_plugin_rm - after_plugin_search - after_plugin_install // Plugin hooks in plugin.xml are executed for a plugin being installed only - after_prepare - after_run - after_serve - before_build - before_clean - before_compile - before_docs - before_emulate - before_platform_add - before_platform_rm/ - before_platform_ls - before_plugin_add - before_plugin_ls - before_plugin_rm - before_plugin_search/ - before_plugin_install // Plugin hooks in plugin.xml are executed for a plugin being installed only - before_plugin_uninstall // Plugin hooks in plugin.xml are executed for a plugin being uninstalled only - before_prepare - before_run - before_serve - pre_package // Windows and Windows Phone only +Cordova hooks allow you to perform special activities around cordova commands. For example, +you may have a custom tool that checks for code formatting in your javascript file. And, you +would like to run this tool before every build. In such a case, you could use a +'before_build' hook and instruct the cordova run time to run the custom tool to be invoked +before every build. + +Hooks might be related to your application activities such as such as `before_build`, +`after_build`, etc. Or, they might be related to the plugins of your application. For example, +hooks such as `before_plugin_add`, `after_plugin_add`, etc applies to plugin related +activities. These hooks can be associated with all plugins within your application or +be specific to only one plugin. + +Cordova supports the following hook types: + +<!-- START HTML --> + +<table class="hooks" width="100%"> + <thead> + <tr> + <th>Hook Type</th> + <th>Associated Cordova Commands</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <th data-col="beforeplatformadd">before_platform_add</th> + <td data-col="code" rowspan="2"><code>cordova platform add</code></td> + <td rowspan="2" class="description" data-col="description">To be executed before and after adding a platform.</td> + </tr> + <tr> + <th data-col="afterplatformadd">after_platform_add</th> + </tr> + <tr> + <th data-col="beforeplatformrm">before_platform_rm</th> + <td data-col="code" rowspan="2"><code>cordova platform rm</code></td> + <td rowspan="2" class="description" data-col="description">To be executed before and after removing a platform.</td> + </tr> + <tr> + <th data-col="afterplatformrm">after_platform_rm</th> + </tr> + <tr> + <th data-col="beforeplatformls">before_platform_ls</th> + <td data-col="code" rowspan="2"><code>cordova platform ls</code></td> + <td rowspan="2" class="description" data-col="description">To be executed before and after listing the installed and available platforms.</td> + </tr> + <tr> + <th data-col="afterplatformls">after_platform_ls</th> + </tr> + <tr> + <th data-col="beforeprepare">before_prepare</th> + <td data-col="code" rowspan="2"><code>cordova prepare</code><br/><code>cordova platform add</code><br/><code>cordova run</code></td> + <td rowspan="2" data-col="description">To be executed before and after preparing your application.</td> + </tr> + <tr> + <th data-col="afterprepare">after_prepare</th> + </tr> + <tr> + <th data-col="beforecompile">before_compile</th> + <td data-col="code" rowspan="2"><code>cordova compile</code><br/><code>cordova run</code></td> + <td rowspan="2" data-col="description">To be executed before and after compiling your application.</td> + </tr> + <tr> + <th data-col="aftercompile">after_compile</th> + </tr> + <tr> + <th data-col="beforebuild">before_build</th> + <td data-col="code" rowspan="2"><code>cordova build</code><br/><code>cordova run</code></td> + <td rowspan="2" data-col="description">To be executed before and after building your application.</td> + </tr> + <tr> + <th data-col="afterbuild">after_build</th> + </tr> + <tr> + <th data-col="beforeemulate">before_emulate</th> + <td data-col="code" rowspan="2"><code>cordova emulate</code></td> + <td rowspan="2" data-col="description">To be executed before and after emulating your application.</td> + </tr> + <tr> + <th data-col="afteremulate">after_emulate</th> + </tr> + <tr> + <th data-col="beforerun">before_run</th> + <td data-col="code" rowspan="2"><code>cordova run</code></td> + <td rowspan="2" data-col="description">To be executed before and after running your application.</td> + </tr> + <tr> + <th data-col="afterrun">after_run</th> + </tr> + <tr> + <th data-col="beforeserve">before_serve</th> + <td data-col="code" rowspan="2"><code>cordova serve</code></td> + <td rowspan="2" data-col="description">To be executed before and after serving your application.</td> + </tr> + <tr> + <th data-col="afterserve">after_serve</th> + </tr> + <tr> + <th data-col="beforeclean">before_clean</th> + <td data-col="code" rowspan="2"><code>cordova clean</code></td> + <td rowspan="2" data-col="description">To be executed before and after cleaning your application.</td> + </tr> + <tr> + <th data-col="afterclean">after_clean</th> + </tr> + <tr> + <th data-col="prepackage">pre_package</td> + <td data-col="code">N/A</td> + <td data-col="description">Applicable to Windows 8 and Windows Phone only. This hook is deprecated.</td> + </tr> + <tr> + <th data-col="beforepluginadd">before_plugin_add</th> + <td data-col="code" rowspan="2"><code>cordova plugin add</code></td> + <td rowspan="2" data-col="description">To be executed before and after adding a plugin.</td> + </tr> + <tr> + <th data-col="afterpluginadd">after_plugin_add</th> + </tr> + <tr> + <th data-col="beforepluginrm">before_plugin_rm</th> + <td data-col="code" rowspan="2"><code>cordova plugin rm</code></td> + <td rowspan="2" data-col="description">To be executed before and after removing a plugin.</td> + </tr> + <tr> + <th data-col="afterpluginrm">after_plugin_rm</th> + </tr> + <tr> + <th data-col="beforepluginls">before_plugin_ls</th> + <td data-col="code" rowspan="2"><code>cordova plugin ls</code></td> + <td rowspan="2" data-col="description">To be executed before and after listing the plugins in your application.</td> + </tr> + <tr> + <th data-col="afterpluginls">after_plugin_ls</th> + </tr> + <tr> + <th data-col="beforepluginsearch">before_plugin_search</th> + <td data-col="code" rowspan="2"><code>cordova plugin search</code></td> + <td rowspan="2" data-col="description">To be executed before and after a plugin search.</td> + </tr> + <tr> + <th data-col="afterpluginsearch">after_plugin_search</th> + </tr> + <tr> + <th data-col="beforeplugininstall">before_plugin_install</th> + <td data-col="code" rowspan="2"><code>cordova plugin add</code></td> + <td rowspan="2" data-col="description">To be executed before and after installing a plugin (to the platforms). Plugin hooks in plugin.xml are executed for a plugin being installed only</td> + </tr> + <tr> + <th data-col="afterplugininstall">after_plugin_install</th> + </tr> + <tr> + <th data-col="beforepluginuninstall">before_plugin_uninstall</th> + <td data-col="code" rowspan="2"><code>cordova plugin rm</code></td> + <td data-col="description">To be executed before uninstalling a plugin (from the platforms).Plugin hooks in plugin.xml are executed for a plugin being installed only</td> + </tr> + </tbody> +</table> + +<!-- END HTML --> ## Ways to define hooks -### Via `/hooks` directory - -__Note__: this method is considered deprecated in favor of the hook elements in config.xml and plugin.xml. - -To execute custom action when corresponding hook type is fired, use hook type as a name for a subfolder inside 'hooks' directory and place you script file here, for example: - - # script file will be automatically executed after each build - hooks/after_build/after_build_custom_action.js - -When using these hooks, they will always be run as executable files, not as loadable JavaScript modules. -__Remember__: Make your scripts executable in this case. ### Config.xml -Hooks can be defined in project's `config.xml` using `<hook>` elements, for example: +Hooks could be defined in project's `config.xml` using `<hook>` elements, for example: <hook type="before_build" src="scripts/appBeforeBuild.bat" /> <hook type="before_build" src="scripts/appBeforeBuild.js" /> <hook type="before_plugin_install" src="scripts/appBeforePluginInstall.js" /> - <platform name="wp8"> - <hook type="before_build" src="scripts/wp8/appWP8BeforeBuild.bat" /> - <hook type="before_build" src="scripts/wp8/appWP8BeforeBuild.js" /> + <platform name="android"> + <hook type="before_build" src="scripts/wp8/appAndroidBeforeBuild.bat" /> + <hook type="before_build" src="scripts/wp8/appAndroidBeforeBuild.js" /> <hook type="before_plugin_install" src="scripts/wp8/appWP8BeforePluginInstall.js" /> ... </platform> - <platform name="windows8"> - <hook type="before_build" src="scripts/windows8/appWin8BeforeBuild.bat" /> - <hook type="before_build" src="scripts/windows8/appWin8BeforeBuild.js" /> - <hook type="before_plugin_install" src="scripts/windows8/appWin8BeforePluginInstall.js" /> + <platform name="windows"> + <hook type="before_build" src="scripts/windows/appWinBeforeBuild.bat" /> + <hook type="before_build" src="scripts/windows/appWinBeforeBuild.js" /> + <hook type="before_plugin_install" src="scripts/windows/appWinBeforePluginInstall.js" /> ... </platform> @@ -115,41 +218,86 @@ As a plugin developer you can define hook scripts using `<hook>` elements in a ` <hook type="before_plugin_install" src="scripts/beforeInstall.js" /> <hook type="after_build" src="scripts/afterBuild.js" /> - <platform name="wp8"> - <hook type="before_plugin_install" src="scripts/wp8BeforeInstall.js" /> - <hook type="before_build" src="scripts/wp8BeforeBuild.js" /> + <platform name="android"> + <hook type="before_plugin_install" src="scripts/androidBeforeInstall.js" /> + <hook type="before_build" src="scripts/androidBeforeBuild.js" /> ... </platform> -`before_plugin_install`, `after_plugin_install`, `before_plugin_uninstall` plugin hooks will be fired exclusively for the plugin being installed/uninstalled. +`before_plugin_install`, `after_plugin_install`, `before_plugin_uninstall` plugin hooks will be fired +exclusively for the plugin being installed/uninstalled. + +### Via `/hooks` directory (Deprecated) + +To execute custom action when corresponding hook type is fired, use hook type as a name for a subfolder inside 'hooks' directory and place you script file here, for example: + + # script file will be automatically executed after each build + hooks/after_build/after_build_custom_action.js + +When using these hooks, they will always be run as executable files, not as loadable JavaScript modules. + +__Remember__: Make your scripts executable in this case. + +__Note__: this method is considered deprecated in favor of the hook elements in config.xml and plugin.xml. + +### Order of Hooks execution + +#### Based on Hooks Definition + +Hook scripts could be defined by adding them to the special predefined folder +(`/hooks`) or via configuration files (`config.xml` and `plugin.xml`) and run +serially in the following order: + +* Application hooks from `/hooks`; +* Application hooks from `config.xml`; +* Plugin hooks from `plugins/.../plugin.xml`. + +#### Based on the Internal order of execution + +The internal order of execution of hooks is fixed. + +##### Example 1 (cordova platform add) +If there are hooks associated with `before_platform_add`, `after_platform_add`, `before_prepare`, `after_prepare`, +`before_plugin_install` and `after_plugin_install` (and assuming you have one plugin installed on your project), +adding a new platform will execute the hooks in the following order: + + before_platform_add + before_prepare + after_prepare + before_plugin_install + after_plugin_install + after_platform_add + +##### Example 2 (cordova build) +If there are hooks associated with `before_prepare`, `after_prepare`, `before_compile`, `after_compile`, `before_build` +and `after_build` - running a build command will execute the hooks in the following order: + + before_build + before_prepare + after_prepare + before_compile + after_compile + after_build ## Script Interface +### Windows Quirks + +If you are working on Windows, and in case your hook (Javascript/Non-Javascript)scripts aren't bat files (which is recommended, if you want your scripts to work in non-Windows operating systems) Cordova CLI will expect a shebang line as the first line for it to know the interpreter it needs to use to launch the script. The shebang line should match the following example: + + #!/usr/bin/env [name_of_interpreter_executable] ### Javascript If you are writing hooks using Node.js you should use the following module definition: + ```javascript module.exports = function(context) { ... } ``` -You can make your scipts async using Q: -```javascript -module.exports = function(context) { - var Q = context.requireCordovaModule('q'); - var deferral = new Q.defer(); +`context` object contains hook type, executed script full path, hook options, command-line arguments passed to Cordova and top-level "cordova" object of the following format: - setTimeout(function(){ - console.log('hook.js>> end'); - deferral.resolve(); - }, 1000); - - return deferral.promise; -} -``` - -`context` object contains hook type, executed script full path, hook options, command-line arguments passed to Cordova and top-level "cordova" object: ```json { "hook": "before_plugin_install", @@ -158,17 +306,17 @@ module.exports = function(context) { "opts": { "projectRoot":"C:\\path\\to\\the\\project", "cordova": { - "platforms": ["wp8"], - "plugins": ["com.plugin.withhooks"], + "platforms": ["android"], + "plugins": ["plugin-withhooks"], "version": "0.21.7-dev" }, "plugin": { - "id": "com.plugin.withhooks", + "id": "plugin-withhooks", "pluginInfo": { ... }, - "platform": "wp8", - "dir": "C:\\path\\to\\the\\project\\plugins\\com.plugin.withhooks" + "platform": "android", + "dir": "C:\\path\\to\\the\\project\\plugins\\plugin-withhooks" } }, "cordova": {...} @@ -178,30 +326,44 @@ module.exports = function(context) { `context.opts.plugin` object will only be passed to plugin hooks scripts. You can also require additional Cordova modules in your script using `context.requireCordovaModule` in the following way: + ```javascript var Q = context.requireCordovaModule('q'); ``` -__Note__: new module loader script interface is used for the `.js` files defined via `config.xml` or `plugin.xml` only. +You can make your scipts async using Q: + +```javascript +module.exports = function(context) { + var Q = context.requireCordovaModule('q'); + var deferral = new Q.defer(); + + setTimeout(function(){ + console.log('hook.js>> end'); + deferral.resolve(); + }, 1000); + + return deferral.promise; +} +``` +> __Note__: new module loader script interface is used for the `.js` files defined via `config.xml` or `plugin.xml` only. For compatibility reasons hook files specified via `/hooks` folders are run via Node child_process spawn, see 'Non-javascript' section below. ### Non-javascript -__Note__: we highly recommend writing your hooks using Node.js so that they are cross-platform, see 'Javascript' section above. - Non-javascript scripts are run via Node child_process spawn from the project's root directory and have the root directory passes as the first argument. All other options are passed to the script using environment variables: -* CORDOVA_VERSION - The version of the Cordova-CLI. -* CORDOVA_PLATFORMS - Comma separated list of platforms that the command applies to (e.g.: android, ios). -* CORDOVA_PLUGINS - Comma separated list of plugin IDs that the command applies to (e.g.: org.apache.cordova.file, org.apache.cordova.file-transfer) -* CORDOVA_HOOK - Path to the hook that is being executed. -* CORDOVA_CMDLINE - The exact command-line arguments passed to cordova (e.g.: cordova run ios --emulate) +Environment Variable Name | Description +------------------------------|-------------------------------------------- +CORDOVA_VERSION | The version of the Cordova-CLI. +CORDOVA_PLATFORMS | Comma separated list of platforms that the command applies to (e.g: android, ios). +CORDOVA_PLUGINS | Comma separated list of plugin IDs that the command applies to (e.g: cordova-plugin-file-transfer, cordova-plugin-file). +CORDOVA_HOOK | Path to the hook that is being executed. +CORDOVA_CMDLINE | The exact command-line arguments passed to cordova (e.g: cordova run ios --emulate). If a script returns a non-zero exit code, then the parent cordova command will be aborted. -Also, note that even if you are working on Windows, and in case your hook scripts aren't bat files (which is recommended, if you want your scripts to work in non-Windows operating systems) Cordova CLI will expect a shebang line as the first line for it to know the interpreter it needs to use to launch the script. The shebang line should match the following example: - - #!/usr/bin/env [name_of_interpreter_executable] +> __Note__: we highly recommend writing your hooks using Node.js so that they are cross-platform, see [Javascript](#link-javascript) section above. ## Sample Usage @@ -213,12 +375,12 @@ tell Cordova to run `afterBuild.js` script after each platform build. <hook type="after_build" src="scripts/afterBuild.js" /> -Create `scripts/afterBuild.js` file and add the following implementation. +Create `scripts/afterBuild.js` file and add the following implementation. We use async version of `fs.stat` method to demonstrate how async functionality could be done via hooks. module.exports = function(ctx) { - // make sure android platform is part of build + // make sure android platform is part of build if (ctx.opts.platforms.indexOf('android') < 0) { return; } @@ -254,6 +416,6 @@ You can now add android platform and execute build. .. Size of path\to\app\platforms\android\build\outputs\apk\android-debug.apk is 1821193 bytes -More good usage examples could be found here: +More good usage examples could be found in [Three Hooks Your Cordova Phone Gap Project needs][Devgirl_Hooks_Link] -[http://devgirl.org/2013/11/12/three-hooks-your-cordovaphonegap-project-needs/](http://devgirl.org/2013/11/12/three-hooks-your-cordovaphonegap-project-needs/) +[Devgirl_Hooks_Link]: http://devgirl.org/2013/11/12/three-hooks-your-cordovaphonegap-project-needs/ http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/guide/appdev/whitelist/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/guide/appdev/whitelist/index.md b/www/docs/en/6.x/guide/appdev/whitelist/index.md index 16c65a0..1b4b4b4 100644 --- a/www/docs/en/6.x/guide/appdev/whitelist/index.md +++ b/www/docs/en/6.x/guide/appdev/whitelist/index.md @@ -29,7 +29,7 @@ accessed. By default, new apps are configured to allow access to any site. Before moving your application to production, you should formulate a whitelist and allow access to specific network domains and subdomains. -For Android and iOS (as of their 4.0 releases), Cordova's security policy is extensible via a plugin +For Android (as of its 4.0 release), Cordova's security policy is extensible via a plugin interface. Your app should use the [cordova-plugin-whitelist][wlp], as it provides better security and configurability than earlier versions of Cordova. While it is possible to implement your own whitelist plugin, it is not recommended @@ -42,8 +42,7 @@ enable network access to specific domains. For projects that rely on the CLI workflow described in [The Command-Line Interface](../../cli/index.html), this file is located in the project's top-level directory. Otherwise for platform-specific development paths, locations are listed in the -sections below. (See the various [Platform Guides](../../platforms/index.html) for more information -on each platform.) +sections below. The following examples demonstrate `<access>` whitelist syntax: @@ -73,20 +72,15 @@ The following examples demonstrate `<access>` whitelist syntax: Be aware that some websites may automatically redirect from their home page to a different url, such as using https protocol or to a country-specific -domain. For example http://www.google.com will redirect to use SSL/TLS at -https://www.google.com, and then may further redirect to a geography such as -https://www.google.co.uk. Such scenarios may require modified or additional +domain. For example `http://www.google.com` will redirect to use SSL/TLS at +`https://www.google.com`, and then may further redirect to a geography such as +`https://www.google.co.uk`. Such scenarios may require modified or additional whitelist entries beyond your initial requirement. Please consider this as you are building your whitelist. Note that the whitelist applies only to the main Cordova webview, and does not apply to an InAppBrowser webview or opening links in the system web browser. -## Amazon Fire OS Whitelisting - -Platform-specific whitelisting rules are found in -`res/xml/config.xml`. - ## Android Whitelisting As above, see [cordova-plugin-whitelist][wlp] for details. For cordova-android @@ -94,9 +88,9 @@ prior to 4.0.0, see older versions of this documentation. ## iOS Whitelisting -The `<allow-intent>` and `<allow-navigation>` tags are _new_ for cordova-ios 4.x and greater, see the [cordova-plugin-whitelist][wlp] documentation for details. cordova-ios version 4.0 and greater does **not** require the [cordova-plugin-whitelist][wlp] plugin to be installed. +`Cordova-ios` version 4.0 and greater does **not** require the [cordova-plugin-whitelist][wlp] plugin to be installed, however it's configuration details apply to iOS too. The `<allow-intent>` and `<allow-navigation>` tags are _new_ for cordova-ios 4.x and greater, see the [cordova-plugin-whitelist][wlp] documentation for details on the usage of these tags. -For cordova-ios versions prior to 4.0.0, see the older versions of this documentation. +For cordova-ios versions prior to 4.0.0, see the older versions of this documentation. [Application Transport Security (ATS)](https://developer.apple.com/library/prerelease/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW33) is new in iOS 9 (Xcode 7). This new feature acts as a whitelist for your app. The cordova cli will automatically convert `<access>` and `<allow-navigation>` tags to the appropriate ATS directives. @@ -140,32 +134,12 @@ ways: (For more information on support, see BlackBerry's documentation on the [access element][8].) -## Firefox OS - -In Firefox OS there is no concept of whitelisting a specific domain. Instead -there is a special permission called -[SystemXHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest#Permissions). -There is a need to add this permission to `config.xml`: - - <platform name="firefoxos"> - <permission name="systemXHR" privileged="true" description="load data from server" /> - </platform> - -The `XMLHttpRequest` object needs to be instantiated with two parameters -`mozAnon` and `mozSystem`: - - var request = new XMLHttpRequest({ - mozAnon: true, - mozSystem: true}); - -This solution is transparent so there is no difference for other platforms. - ## Windows Phone Whitelisting The whitelisting rules for Windows Phone 8 are found in the app's `config.xml` file. -[wlp]: https://github.com/apache/cordova-plugin-whitelist +[wlp]: ../../../cordova-plugin-whitelist/ [1]: http://www.w3.org/TR/widgets-access/ [2]: http://google.com [3]: https://google.com @@ -173,4 +147,4 @@ app's `config.xml` file. [5]: http://mail.google.com [6]: http://docs.google.com [7]: http://developer.mozilla.org -[8]: https://developer.blackberry.com/html5/documentation/ww_developing/Access_element_834677_11.html +[8]: https://developer.blackberry.com/html5/documentation/v1_0/access_element_834677_11.html http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/28d8c235/www/docs/en/6.x/guide/cli/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.x/guide/cli/index.md b/www/docs/en/6.x/guide/cli/index.md index a011394..dc69c07 100644 --- a/www/docs/en/6.x/guide/cli/index.md +++ b/www/docs/en/6.x/guide/cli/index.md @@ -17,68 +17,29 @@ license: > specific language governing permissions and limitations under the License. -title: The Command-Line Interface +title: Creating your first Cordova app +description: Learn how to create your first Cordova hybrid app using Cordova CLI. --- -# The Command-Line Interface +# Create your first Cordova app -This guide shows you how to create applications and deploy them to +This guide shows you how to create a JS/HTML Cordova application and deploy them to various native mobile platforms using the `cordova` command-line -interface (CLI). This tool allows you to create new projects, build -them on different platforms, and run on real devices or within -emulators. The CLI is the main tool to use for the cross-platform -workflow described in the [Overview](../overview/index.html). Otherwise you can also use the -CLI to initialize project code, then switch to various platforms' SDKs -and shell tools for continued development. - -## Prerequisites - -Before running any command-line tools, you need to install SDKs for -each platform you wish to target. -(See the [Platform Guides](../platforms/index.html) for more details.) - -To add support or rebuild a project for any platform, you need to run -the command-line interface from the same machine that supports the -platform's SDK. The CLI supports the following combinations: - -* iOS (Mac) -* Amazon Fire OS (Mac, Linux, Windows) -* Android (Mac, Linux, Windows) -* BlackBerry 10 (Mac, Linux, Windows) -* Windows Phone 8 (Windows) -* Windows (Windows) -* Firefox OS (Mac, Linux, Windows) - -On the Mac, the command-line is available via the _Terminal_ -application. On the PC, it's available as _Command Prompt_ under -_Accessories_. - -__NOTE__: For Windows-only platforms, you can still do your -development on Mac hardware by running Windows in a virtual machine -environment or in dual-boot mode. For available options, see the -[Windows Phone 8 Platform Guide](../platforms/wp8/index.html) or the [Windows Platform Guide](../platforms/win8/index.html). - -The more likely it is that you run the CLI from different machines, -the more it makes sense to maintain a remote source code repository, -whose assets you pull down to local working directories. +interface (CLI). For detailed reference on Cordova command-line, review the [CLI reference] ## Installing the Cordova CLI -The Cordova command-line tool is distributed as an npm package in a -ready-to-use format. It is not necessary to compile it from source. +The Cordova command-line tool is distributed as an npm package. To install the `cordova` command-line tool, follow these steps: -1. Download and install [Node.js](http://nodejs.org/). Following - installation, you should be able to invoke `node` and `npm` on your - command line. If desired, you may optionally use a tool such as `nvm` - or `nave` to manage your Node.js installation. +1. Download and install [Node.js](https://nodejs.org/en/download/). On + installation you should be able to invoke `node` and `npm` on your + command line. -1. Download and install a [git client](http://git-scm.com/), if you don't +1. (Optional) Download and install a [git client](http://git-scm.com/downloads), if you don't already have one. Following installation, you should be able to invoke `git` - on your command line. Even though you won't be using `git` manually, - the CLI does use it behind-the-scenes to download some assets when - creating a new project. + on your command line. The CLI uses it to download assets when they are referenced using a url to a git repo. 1. Install the `cordova` module using `npm` utility of Node.js. The `cordova` module will automatically be downloaded by the `npm` utility. @@ -89,7 +50,7 @@ To install the `cordova` command-line tool, follow these steps: On OS X and Linux, prefixing the `npm` command with `sudo` may be necessary to install this development utility in - otherwise restricted directories such as + otherwise restricted directories such as `/usr/local/share`. If you are using the optional nvm/nave tool or have write access to the install directory, you may be able to omit the `sudo` prefix. There are @@ -104,158 +65,91 @@ To install the `cordova` command-line tool, follow these steps: it will be installed in the `node_modules` subdirectory of the current working directory. - You may need to add the `npm` directory to your `PATH` in order to invoke - globally installed `npm` modules. On Windows, `npm` can usually be found at - `C:\Users\username\AppData\Roaming\npm`. On OS X and Linux it can usually - be found at `/usr/local/share/npm`. - - The installation log may produce errors for any uninstalled - platform SDKs. - Following installation, you should be able to run `cordova` on the command line with no arguments and it should print help text. ## Create the App -Go to the directory where you maintain your source code, and run a -command such as the following: - - $ cordova create hello com.example.hello HelloWorld [--template templatePath] - -It may take some time for the command to complete, so be patient. Running -the command with the ` -d` option displays information about its progress. - -The first argument _hello_ specifies a directory to be generated -for your project. This directory should not already exist, Cordova will -create it for you. Its `www` subdirectory houses your application's -home page, along with various resources under `css`, `js`, and `img`, -which follow common web development file-naming conventions. These assets -will be stored on the device's local filesystem, not served remotely. The -`config.xml` file contains important metadata needed to generate and -distribute the application. - -The second argument `com.example.hello` -provides your project with a reverse domain-style identifier. This argument -is optional, but only if you also omit the third argument, since the arguments -are positional. You can edit -this value later in the `config.xml` file, but do be aware that there may -be code generated outside of `config.xml` using this value, such as Java -package names. The default value is `io.cordova.hellocordova`, but it is -recommended that you select an appropriate value. - -The third argument `HelloWorld` provides the application's display title. -This argument is optional. You can edit this value later in the `config.xml` -file, but do be aware that there may be code generated outside of `config.xml` -using this value, such as Java class names. The default value is `HelloCordova`, -but it is recommended that you select an appropriate value. - -The fourth argument `--template templatePath` allows for a template application -to be used to create a project. All files, and folders from the template will -be copied into the new project. Platforms, and plugins may be included in a -template, but are optional. This argument is optional. The path to the -template can be a local path, NPM module, or Git URL. +Go to the directory where you maintain your source code, and create a cordova project: + + $ cordova create hello com.example.hello HelloWorld + +This creates the required directory structure for your cordova app. By default, the `cordova create` script generates a skeletal web-based application whose home page is the project's `www/index.html` file. + +###See Also +- [Cordova create command reference documentation](../../cordova-cli/index.html#cordova-create-command) +- [Cordova project directory structure](../../cordova-cli/index.html#directory-structure) ## Add Platforms All subsequent commands need to be run within the project's directory, -or any subdirectories within its scope: +or any subdirectories: $ cd hello -Before you can build the project, you need to specify a set of target -platforms. Your ability to run these commands depends on whether your -machine supports each SDK, and whether you have already installed each -SDK. Run any of these from a Mac: +Add the platforms that you want to target your app. We will add the 'ios' and 'android' platform and ensure they get saved to `config.xml`: - $ cordova platform add ios - $ cordova platform add amazon-fireos - $ cordova platform add android - $ cordova platform add blackberry10 - $ cordova platform add firefoxos + $ cordova platform add ios --save + $ cordova platform add android --save -Run any of these from a Windows machine, where _wp_ refers to -different versions of the Windows Phone operating system: +To check your current set of platforms: - $ cordova platform add wp8 - $ cordova platform add windows - $ cordova platform add amazon-fireos - $ cordova platform add android - $ cordova platform add blackberry10 - $ cordova platform add firefoxos + $ cordova platform ls -Run this to check your current set of platforms: +Running commands to add or remove platforms affects the contents of +the project's _platforms_ directory, where each specified platform +appears as a subdirectory. - $ cordova platforms ls +> Note: When using the CLI to build your application, you should +_not_ edit any files in the `/platforms/` directory. The files +in this directory are routinely overwritten when preparing +applications for building, or when plugins are re-installed. -(Note the `platform` and `platforms` commands are synonymous.) +###See Also +- [Cordova platform command reference documentation](../../cordova-cli/index.html#cordova-platform-command) -Run either of the following synonymous commands to remove a platform: +##Install pre-requrisites for building +To build and run apps, you need to install SDKs for each platform you wish to target. Alternatively, if you are using browser for development you can use `browser` platform which does not require any platform SDKs. - $ cordova platform remove blackberry10 - $ cordova platform rm amazon-fireos - $ cordova platform rm android +To check if you satisfy requirements for building the platform: -Running commands to add or remove platforms affects the contents of -the project's _platforms_ directory, where each specified platform -appears as a subdirectory. The _www_ source directory is reproduced -within each platform's subdirectory, appearing for example in -`platforms/ios/www` or `platforms/android/assets/www`. Because the CLI -constantly copies over files from the source _www_ folder, you should only -edit these files and not the ones located under the _platforms_ subdirectories. -If you use version control software, you should add this source _www_ folder, -along with the _merges_ folder, to your version control system. (More information -about the _merges_ folder can be found in the Customize Each Platform section below.) - - -__WARNING__: When using the CLI to build your application, you should -_not_ edit any files in the `/platforms/` directory unless you know -what you are doing, or if documentation specifies otherwise. The files -in this directory are routinely overwritten when preparing -applications for building, or when plugins are reinstalled. +``` + $ cordova requirements + Requirements check results for android: + Java JDK: installed . + Android SDK: installed + Android target: installed android-19,android-21,android-22,android-23,Google Inc.:Google APIs:19,Google Inc.:Google APIs (x86 System Image):19,Google Inc.:Google APIs:23 + Gradle: installed + Requirements check results for ios: + Apple OS X: not installed + Cordova tooling for iOS requires Apple OS X + Error: Some of requirements check failed +``` -If you wish at this point, you can use an SDK such as Eclipse or Xcode -to open the project you created. You will need to open the derivative set of assets -from the `/platforms/` directory to develop with an SDK. This is because -the SDK specific metadata files are stored within the appropriate `/platform/` subdirectory. -(See the [Platform Guides](../platforms/index.html) for information on how to develop applications within each IDE.) -Use this approach if you simply want to initialize a project using the CLI and -then switch to an SDK for native work. - -Read on if you wish to use the cross-platform workflow approach (the CLI) for the entire -development cycle. +###See Also +- [Android platform requirements](../../guide/platforms/android/index.html#requirements-and-support) +- [iOS platform requirements](../../guide/platforms/ios/index.html#requirements-and-support) +- [Windows platform requirements](../../guide/platforms/win8/index.html#requirements-and-support) ## Build the App -By default, the `cordova create` script generates a skeletal web-based -application whose home page is the project's `www/index.html` file. -Edit this application however you want, but any initialization should -be specified as part of the `[deviceready](../../cordova/events/events.deviceready.html)` event handler, referenced by -default from `www/js/index.js`. +By default, `cordova create` script generates a skeletal web-based application whose start page is the project's `www/index.html` file. Any +initialization should be specified as part of the [deviceready][DeviceReadyEvent] event handler defined in `www/js/index.js`. -Run the following command to iteratively build the project: +Run the following command to build the project for _all_ platforms: $ cordova build -This generates platform-specific code within the project's `platforms` -subdirectory. You can optionally limit the scope of each build to -specific platforms: +You can optionally limit the scope of each build to specific platforms - 'ios' in this case: $ cordova build ios -The `cordova build` command is a shorthand for the following, which in -this example is also targeted to a single platform: - - $ cordova prepare ios - $ cordova compile ios - -In this case, once you run `prepare`, you can use Apple's Xcode SDK as -an alternative to modify and compile the platform-specific code that -Cordova generates within `platforms/ios`. You can use the same -approach with other platforms' SDKs. +###See Also +- [Cordova build command reference documentation](../../dev/cordova-cli/index.html#cordova-build-command) -## Test the App on an Emulator or Device +##Test the App SDKs for mobile platforms often come bundled with emulators that execute a device image, so that you can launch the app from the home @@ -265,16 +159,6 @@ specific platform's emulator: $ cordova emulate android -Some mobile platforms emulate a particular device by default, such as -the iPhone for iOS projects. For other platforms, you may need to -first associate a device with an emulator. - -__NOTE__: Emulator support is currently not available for Amazon Fire OS. - -(See the [Platform Guides](../platforms/index.html) for details.) -For example, you may first run the `android` command to launch the -Android SDK, then run a particular device image, which launches it -according to its default behavior:  @@ -290,104 +174,33 @@ app directly: $ cordova run android Before running this command, you need to set up the device for -testing, following procedures that vary for each platform. In -Android and Amazon Fire OS devices, you would have to enable a __USB debugging__ option on -the device, and perhaps add a USB driver depending on your development -environmnent. -See [Platform Guides](../platforms/index.html) for details on each platform's requirements. - -## Add Plugin Features - -When you build and view a new project, the default application that -appears doesn't do very much. You can modify the app in many ways to -take advantage of standard web technologies, but for the app to -communicate closely with various device-level features, you need to -add plugins that provide access to core Cordova APIs. - -A _plugin_ is a bit of add-on code that provides an interface to -native components. You can design your own plugin interface, for -example when designing a hybrid app that mixes a Cordova WebView with -native components. (See [Embedding WebViews](../hybrid/webviews/index.html) and [Plugin Development -Guide](guide_hybrid_plugins_index.md.html#Plugin%20Development%20Guide) for details.) More commonly, you would add a plugin to enable -one of Cordova's basic device-level features -detailed in the API Reference. - -As of version 3.0, when you create a Cordova project it does not have any -plugins present. This is the new default behavior. Any plugins you desire, -even the core plugins, must be explicitly added. - -A list of these plugins, including -additional third-party plugins provided by the community, can be found -in the registry at -[plugins.cordova.io](http://plugins.cordova.io/). You can use -the CLI to search for plugins from this registry. For example, -searching for `bar` and `code` produces a single result that matches -both terms as case-insensitive substrings: - - $ cordova plugin search bar code - - com.phonegap.plugins.barcodescanner - Scans Barcodes - -Searching for only the `bar` term yields and additional result: - - cordova-plugin-statusbar - Cordova StatusBar Plugin - -The `cordova plugin add` command requires you to specify the -repository for the plugin code. Here are examples of how you might -use the CLI to add features to the app: - -* Basic device information (Device API): - - $ cordova plugin add cordova-plugin-device - -* Network Connection and Battery [Events](../../cordova/events/events.html): - - $ cordova plugin add cordova-plugin-network-information - $ cordova plugin add cordova-plugin-battery-status - -* Accelerometer, Compass, and Geolocation: - - $ cordova plugin add cordova-plugin-device-motion - $ cordova plugin add cordova-plugin-device-orientation - $ cordova plugin add cordova-plugin-geolocation - -* Camera, Media playback and Capture: - - $ cordova plugin add cordova-plugin-camera - $ cordova plugin add cordova-plugin-media-capture - $ cordova plugin add cordova-plugin-media - -* Access files on device or network (File API): - - $ cordova plugin add cordova-plugin-file - $ cordova plugin add cordova-plugin-file-transfer - -* Notification via dialog box or vibration: - - $ cordova plugin add cordova-plugin-dialogs - $ cordova plugin add cordova-plugin-vibration +testing, following procedures that vary for each platform. -* Contacts: +###See Also +- [Setting up Android emulator](../../guide/platforms/android/index.html#setting-up-an-emulator) +- [Cordova run command reference documentation](../../cordova-cli/index.html#cordova-run-command) +- [Cordova emulate command reference documentation](../../cordova-cli/index.html#cordova-emulate-command) - $ cordova plugin add cordova-plugin-contacts +## Add Plugins -* Globalization: +You can modify the default generated app to take advantage of standard web technologies, +but for the app to access device-level features, you need to add plugins. - $ cordova plugin add cordova-plugin-globalization +A _plugin_ exposes a Javascript API for native SDK functionality. Plugins are typically hosted on +npm and you can search for them on the [plugin search page](/plugins/). Some key APIs are provided by the Apache Cordova open source project and these are referred to as [Core Plugin APIs]. You can also use the CLI to launch the search page: -* Splashscreen: + $ cordova plugin search camera + +To add the camera plugin, we will specify the npm package name for the camera plugin: - $ cordova plugin add cordova-plugin-splashscreen + $ cordova pluign add cordova-plugin-camera + Fetching plugin "cordova-plugin-camera@~2.1.0" via npm + Installing "cordova-plugin-camera" for android + Installing "cordova-plugin-camera" for ios -* Open new browser windows (InAppBrowser): +Plugins can also be added using a directory or a git repo. - $ cordova plugin add cordova-plugin-inappbrowser - -* Debug console: - - $ cordova plugin add cordova-plugin-console - -__NOTE__: The CLI adds plugin code as appropriate for each platform. +> __NOTE__: The CLI adds plugin code as appropriate for each platform. If you want to develop with lower-level shell tools or platform SDKs as discussed in the [Overview](../overview/index.html), you need to run the Plugman utility to add plugins separately for each platform. (For more information, see @@ -396,72 +209,14 @@ add plugins separately for each platform. (For more information, see Use `plugin ls` (or `plugin list`, or `plugin` by itself) to view currently installed plugins. Each displays by its identifier: - $ cordova plugin ls # or 'plugin list' - [ 'cordova-plugin-console' ] - -To remove a plugin, refer to it by the same identifier that appears in -the listing. For example, here is how you would remove support for a -debug console from a release version: - - $ cordova plugin rm cordova-plugin-console - $ cordova plugin remove cordova-plugin-console # same - -You can batch-remove or add plugins by specifying more than one -argument for each command: - - $ cordova plugin add cordova-plugin-console cordova-plugin-device - -## Advanced Plugin Options - -When adding a plugin, several options allow you to specify from where -to fetch the plugin. The examples above use a well-known -`registry.cordova.io` registry, and the plugin is specified by the -`id`: - - $ cordova plugin add cordova-plugin-console - -The `id` may also include the plugin's version number, appended after -an `@` character. The `latest` version is an alias for the most recent -version. For example: - - $ cordova plugin add cordova-plugin-console@latest - $ cordova plugin add cordova-plugin-console@0.2.1 - -If the plugin is not registered at `registry.cordova.io` but is located in -another git repository, you can specify an alternate URL: - - $ cordova plugin add https://github.com/apache/cordova-plugin-console.git - -The git example above fetches the plugin from the end of the master -branch, but an alternate git-ref such as a tag or branch can be -appended after a `#` character: - -Install from a tag: - - $ cordova plugin add https://github.com/apache/cordova-plugin-console.git#r0.2.0 - -or a branch: - - $ cordova plugin add https://github.com/apache/cordova-plugin-console.git#CB-8438cordova-plugin-console + $ cordova plugin ls + cordova-plugin-camera 2.1.0 "Camera" + cordova-plugin-whitelist 1.2.1 "Whitelist" -or git-ref could also be a particular commit: - - $ cordova plugin add https://github.com/apache/cordova-plugin-console.git#f055daec45575bf08538f885e09c85a0eba363ff - -If the plugin (and its `plugin.xml` file) is in a subdirectory within -the git repo, you can specify it with a `:` character. Note that the -`#` character is still needed: - - $ cordova plugin add https://github.com/someone/aplugin.git#:/my/sub/dir - -You can also combine both the git-ref and the subdirectory: - - $ cordova plugin add https://github.com/someone/aplugin.git#r0.0.1:/my/sub/dir - -Alternately, specify a local path to the plugin directory that -contains the `plugin.xml` file: - - $ cordova plugin add ../my_plugin_dir +###See Also +- [Cordova plugin command reference documentation](../../cordova-cli/index.html#cordova-plugin-command) +- [Cordova plugin search page](/plugins/) +- [Core Plugin APIs] ## Using _merges_ to Customize Each Platform @@ -476,12 +231,14 @@ assets to deploy on specific platforms. Each platform-specific subdirectory within `merges` mirrors the directory structure of the `www` source tree, allowing you to override or add files as needed. For example, here is how you might uses `merges` to boost the default -font size for Android and Amazon Fire OS devices: +font size for Android devices: * Edit the `www/index.html` file, adding a link to an additional CSS file, `overrides.css` in this case: - <link rel="stylesheet" type="text/css" href="css/overrides.css" /> +```html + <link rel="stylesheet" type="text/css" href="css/overrides.css" /> +``` * Optionally create an empty `www/css/overrides.css` file, which would apply for all non-Android builds, preventing a missing-file error. @@ -491,7 +248,9 @@ font size for Android and Amazon Fire OS devices: 12-point default font size specified within `www/css/index.css`, for example: - body { font-size:14px; } +```css + body { font-size:14px; } +``` When you rebuild the project, the Android version features the custom font size, while others remain unchanged. @@ -500,34 +259,9 @@ You can also use `merges` to add files not present in the original `www` directory. For example, an app can incorporate a _back button_ graphic into the iOS interface, stored in `merges/ios/img/back_button.png`, while the Android version can -instead capture `[backbutton](../../cordova/events/events.backbutton.html)` events from the corresponding hardware +instead capture [backbutton][BackButtonEvent] events from the corresponding hardware button. -## Help Commands - -Cordova features a couple of global commands, which may help you if -you get stuck or experience a problem. The `help` command displays -all available Cordova commands and their syntax: - - $ cordova help - $ cordova # same - -Additionally, you can get more detailed help on a specific command. -For example: - - $ cordova run --help - -The `info` command produces a listing of potentially useful details, -such as currently installed platforms and plugins, SDK versions for -each platform, and versions of the CLI and `node.js`: - - $ cordova info - -It both presents the information to screen and captures the output in -a local `info.txt` file. - -__NOTE__: Currently, only details on iOS and Android platforms are -available. ## Updating Cordova and Your Project @@ -540,29 +274,17 @@ Use this syntax to install a specific version: $ sudo npm install -g cordova@3.1.0-0.2.0 -Run `cordova -v` to see which version is currently running. Run the `npm -info` command for a longer listing that includes the current version -along with other available version numbers: - - $ npm info cordova - -Cordova 3.0 is the first version to support the command-line interface -described in this section. If you are updating from a version prior to -3.0, you need to create a new project as described above, then copy -the older application's assets into the top-level `www` directory. -Where applicable, further details about upgrading to 3.0 are available -in the [Platform Guides](../platforms/index.html). Once you upgrade to the `cordova` -command-line interface and use `npm update` to stay current, the more -time-consuming procedures described there are no longer relevant. - -Cordova 3.0+ may still require various changes to -project-level directory structures and other dependencies. After you -run the `npm` command above to update Cordova itself, you may need to -ensure your project's resources conform to the latest version's -requirements. Run a command such as the following for each platform -you're building: - - $ cordova platform update android - $ cordova platform update ios +Run `cordova -v` to see which version is currently running. To find the latest released cordova version, you can run: + + $ npm info cordova version + +To update platform that you're targeting: + + $ cordova platform update android --save + $ cordova platform update ios --save ...etc. +[DeviceReadyEvent]: ../../cordova/events/events.html#deviceready +[BackButtonEvent]: ../../cordova/events/events.html#backbutton +[CLI reference]: ../../cordova-cli/index.html +[Core Plugin APIs]: ../../guide/support/index.html#core-plugin-apis --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org For additional commands, e-mail: commits-h...@cordova.apache.org
