Repository: cordova-docs Updated Branches: refs/heads/master c6e807d36 -> 312e2d5a1
CB-10504 CB-10348 Add Create your first app doc & link CLI reference Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/312e2d5a Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/312e2d5a Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/312e2d5a Branch: refs/heads/master Commit: 312e2d5a116e939d8482fa067ce5effc5fcdb987 Parents: c6e807d Author: Nikhil Khandelwal <[email protected]> Authored: Tue Feb 23 09:30:18 2016 -0800 Committer: Nikhil Khandelwal <[email protected]> Committed: Wed Feb 24 16:32:03 2016 -0800 ---------------------------------------------------------------------- gulpfile.js | 5 +- tools/bin/fetch_docs.js | 57 +++- www/_data/fetched-files.yml | 2 +- www/_data/toc/de-dev-manual.yml | 4 +- www/_data/toc/en-dev-manual.yml | 4 +- www/_data/toc/es-dev-manual.yml | 4 +- www/_data/toc/fr-dev-manual.yml | 4 +- www/_data/toc/it-dev-manual.yml | 4 +- www/_data/toc/ja-dev-manual.yml | 4 +- www/_data/toc/ko-dev-manual.yml | 4 +- www/_data/toc/pl-dev-manual.yml | 4 +- www/_data/toc/ru-dev-manual.yml | 4 +- www/_data/toc/sl-dev-manual.yml | 4 +- www/_data/toc/zh-dev-manual.yml | 4 +- www/_layouts/docs.html | 2 +- www/docs/en/dev/guide/cli/index.md | 473 ++++++---------------------- www/docs/en/dev/guide/support/index.md | 2 +- 17 files changed, 177 insertions(+), 408 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/gulpfile.js ---------------------------------------------------------------------- diff --git a/gulpfile.js b/gulpfile.js index d8c38e7..9b0d594 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -24,6 +24,8 @@ var uglify = require("gulp-uglify"); var envify = require("envify"); var htmllint = require("gulp-htmllint"); var crawler = require("simplecrawler"); +var argv = require('yargs').argv; +var yaml = require('js-yaml'); // constants var ROOT_DIR = "."; @@ -176,6 +178,7 @@ gulp.task("help", function () { gutil.log("Arguments:"); gutil.log(" --nodocs don't generate docs"); gutil.log(" --prod build for production; without it, will build dev instead"); + gutil.log(" --nofetch skips fetching external docs"); gutil.log(""); }); @@ -232,7 +235,7 @@ gulp.task("serve", ["build"], function () { }); }); -gulp.task("build", ["configs", "data", "styles", "plugins"], function (done) { +gulp.task("build", [ "configs", "data", "styles", "plugins"], function (done) { jekyllBuild(done); }); http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/tools/bin/fetch_docs.js ---------------------------------------------------------------------- diff --git a/tools/bin/fetch_docs.js b/tools/bin/fetch_docs.js index 8c9d4c6..59b92c9 100644 --- a/tools/bin/fetch_docs.js +++ b/tools/bin/fetch_docs.js @@ -39,10 +39,7 @@ function generateFrontMatter(fetchedFile) { frontMatterConfig.plugin_name = fetchedFile.packageName; frontMatterConfig.plugin_version = fetchedFile.version; } - - // return front matter as a string - var frontMatterString = "---\n" + yaml.dump(frontMatterConfig) + "---\n\n"; - return frontMatterString; + return frontMatterConfig; } function isPluginName(packageName) { @@ -161,7 +158,6 @@ function main () { // fetch all files configEntries.forEach(function (entry) { - // verify and process entry var fetchedFile = getFetchedFile(entry); if (!fetchedFile) { @@ -183,16 +179,53 @@ function main () { // open the file for writing var outFile = fs.createWriteStream(outFilePath); - outFile.write(frontMatter, function () { - - // open an HTTP request for the file - var request = https.get(fetchURI, function (response) { + // open an HTTP request for the file + var request = https.get(fetchURI, function (response) { + var res = ''; + response.setEncoding('utf8'); + response.on('data', function(data) { + res += data; + }); - // write the HTTP response to the file - response.pipe(outFile); + response.on('end', function() { + var mergedFile = mergeFrontMatter(res, frontMatter); + outFile.end(mergedFile); + }).on('error', function(e) { + console.error(e); }); - }); + }); }); // entries } main(); + +// If front matter exists in the source, merge it! +function mergeFrontMatter(originalFile, frontMatter) { + var lines = originalFile.split(/\r?\n/); + var mergedFile = originalFile; + var endLine; + if (lines[0] && lines[0] === "---") { + for (var i = 1; i < lines.length; i++) { + if(lines[i] && lines[i] === "---") { + endLine = i; + break; + } + } + } + if (endLine) { + var fm = ''; + for (var j = 1; j <= endLine - 1; j++) { + fm += lines[j] + '\n'; + } + var fmFile = yaml.load(fm); + Object.keys(fmFile).forEach(function(key) { + frontMatter[key] = fmFile[key]; + }); + mergedFile = ''; + for (var j = endLine + 1; j < lines.length; j++) { + mergedFile += lines[j] + '\n'; + } + } + mergedFile = "---\n" + yaml.dump(frontMatter) + "---\n\n" + mergedFile; + return mergedFile; +} http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_data/fetched-files.yml ---------------------------------------------------------------------- diff --git a/www/_data/fetched-files.yml b/www/_data/fetched-files.yml index 8fe23e8..69cdebf 100644 --- a/www/_data/fetched-files.yml +++ b/www/_data/fetched-files.yml @@ -15,7 +15,7 @@ repoName: "apache/cordova-cli" packageName: "cordova" commit: "master" - path: "doc/bash.md" + path: "doc/readme.md" dest: permalink: "/docs/en/dev/cordova-cli/index.html" - http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_data/toc/de-dev-manual.yml ---------------------------------------------------------------------- diff --git a/www/_data/toc/de-dev-manual.yml b/www/_data/toc/de-dev-manual.yml index fc64930..6836d43 100644 --- a/www/_data/toc/de-dev-manual.yml +++ b/www/_data/toc/de-dev-manual.yml @@ -9,7 +9,7 @@ - name: "Create apps" children: - name: "Create your first app" - url: + url: "guide/cli/index.html" - name: "Platform support" url: "guide/support/index.html" - name: "Develop for platforms" @@ -81,7 +81,7 @@ - name: "Events" url: "cordova/events/events.html" - name: "CLI" - url: "guide/cli/index.html" + url: "cordova-cli/index.html" - name: "Hooks" url: "guide/appdev/hooks/index.html" - name: "Plugin.xml" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_data/toc/en-dev-manual.yml ---------------------------------------------------------------------- diff --git a/www/_data/toc/en-dev-manual.yml b/www/_data/toc/en-dev-manual.yml index fc64930..6836d43 100644 --- a/www/_data/toc/en-dev-manual.yml +++ b/www/_data/toc/en-dev-manual.yml @@ -9,7 +9,7 @@ - name: "Create apps" children: - name: "Create your first app" - url: + url: "guide/cli/index.html" - name: "Platform support" url: "guide/support/index.html" - name: "Develop for platforms" @@ -81,7 +81,7 @@ - name: "Events" url: "cordova/events/events.html" - name: "CLI" - url: "guide/cli/index.html" + url: "cordova-cli/index.html" - name: "Hooks" url: "guide/appdev/hooks/index.html" - name: "Plugin.xml" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_data/toc/es-dev-manual.yml ---------------------------------------------------------------------- diff --git a/www/_data/toc/es-dev-manual.yml b/www/_data/toc/es-dev-manual.yml index fc64930..6836d43 100644 --- a/www/_data/toc/es-dev-manual.yml +++ b/www/_data/toc/es-dev-manual.yml @@ -9,7 +9,7 @@ - name: "Create apps" children: - name: "Create your first app" - url: + url: "guide/cli/index.html" - name: "Platform support" url: "guide/support/index.html" - name: "Develop for platforms" @@ -81,7 +81,7 @@ - name: "Events" url: "cordova/events/events.html" - name: "CLI" - url: "guide/cli/index.html" + url: "cordova-cli/index.html" - name: "Hooks" url: "guide/appdev/hooks/index.html" - name: "Plugin.xml" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_data/toc/fr-dev-manual.yml ---------------------------------------------------------------------- diff --git a/www/_data/toc/fr-dev-manual.yml b/www/_data/toc/fr-dev-manual.yml index fc64930..6836d43 100644 --- a/www/_data/toc/fr-dev-manual.yml +++ b/www/_data/toc/fr-dev-manual.yml @@ -9,7 +9,7 @@ - name: "Create apps" children: - name: "Create your first app" - url: + url: "guide/cli/index.html" - name: "Platform support" url: "guide/support/index.html" - name: "Develop for platforms" @@ -81,7 +81,7 @@ - name: "Events" url: "cordova/events/events.html" - name: "CLI" - url: "guide/cli/index.html" + url: "cordova-cli/index.html" - name: "Hooks" url: "guide/appdev/hooks/index.html" - name: "Plugin.xml" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_data/toc/it-dev-manual.yml ---------------------------------------------------------------------- diff --git a/www/_data/toc/it-dev-manual.yml b/www/_data/toc/it-dev-manual.yml index fc64930..6836d43 100644 --- a/www/_data/toc/it-dev-manual.yml +++ b/www/_data/toc/it-dev-manual.yml @@ -9,7 +9,7 @@ - name: "Create apps" children: - name: "Create your first app" - url: + url: "guide/cli/index.html" - name: "Platform support" url: "guide/support/index.html" - name: "Develop for platforms" @@ -81,7 +81,7 @@ - name: "Events" url: "cordova/events/events.html" - name: "CLI" - url: "guide/cli/index.html" + url: "cordova-cli/index.html" - name: "Hooks" url: "guide/appdev/hooks/index.html" - name: "Plugin.xml" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_data/toc/ja-dev-manual.yml ---------------------------------------------------------------------- diff --git a/www/_data/toc/ja-dev-manual.yml b/www/_data/toc/ja-dev-manual.yml index fc64930..6836d43 100644 --- a/www/_data/toc/ja-dev-manual.yml +++ b/www/_data/toc/ja-dev-manual.yml @@ -9,7 +9,7 @@ - name: "Create apps" children: - name: "Create your first app" - url: + url: "guide/cli/index.html" - name: "Platform support" url: "guide/support/index.html" - name: "Develop for platforms" @@ -81,7 +81,7 @@ - name: "Events" url: "cordova/events/events.html" - name: "CLI" - url: "guide/cli/index.html" + url: "cordova-cli/index.html" - name: "Hooks" url: "guide/appdev/hooks/index.html" - name: "Plugin.xml" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_data/toc/ko-dev-manual.yml ---------------------------------------------------------------------- diff --git a/www/_data/toc/ko-dev-manual.yml b/www/_data/toc/ko-dev-manual.yml index fc64930..6836d43 100644 --- a/www/_data/toc/ko-dev-manual.yml +++ b/www/_data/toc/ko-dev-manual.yml @@ -9,7 +9,7 @@ - name: "Create apps" children: - name: "Create your first app" - url: + url: "guide/cli/index.html" - name: "Platform support" url: "guide/support/index.html" - name: "Develop for platforms" @@ -81,7 +81,7 @@ - name: "Events" url: "cordova/events/events.html" - name: "CLI" - url: "guide/cli/index.html" + url: "cordova-cli/index.html" - name: "Hooks" url: "guide/appdev/hooks/index.html" - name: "Plugin.xml" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_data/toc/pl-dev-manual.yml ---------------------------------------------------------------------- diff --git a/www/_data/toc/pl-dev-manual.yml b/www/_data/toc/pl-dev-manual.yml index fc64930..6836d43 100644 --- a/www/_data/toc/pl-dev-manual.yml +++ b/www/_data/toc/pl-dev-manual.yml @@ -9,7 +9,7 @@ - name: "Create apps" children: - name: "Create your first app" - url: + url: "guide/cli/index.html" - name: "Platform support" url: "guide/support/index.html" - name: "Develop for platforms" @@ -81,7 +81,7 @@ - name: "Events" url: "cordova/events/events.html" - name: "CLI" - url: "guide/cli/index.html" + url: "cordova-cli/index.html" - name: "Hooks" url: "guide/appdev/hooks/index.html" - name: "Plugin.xml" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_data/toc/ru-dev-manual.yml ---------------------------------------------------------------------- diff --git a/www/_data/toc/ru-dev-manual.yml b/www/_data/toc/ru-dev-manual.yml index fc64930..6836d43 100644 --- a/www/_data/toc/ru-dev-manual.yml +++ b/www/_data/toc/ru-dev-manual.yml @@ -9,7 +9,7 @@ - name: "Create apps" children: - name: "Create your first app" - url: + url: "guide/cli/index.html" - name: "Platform support" url: "guide/support/index.html" - name: "Develop for platforms" @@ -81,7 +81,7 @@ - name: "Events" url: "cordova/events/events.html" - name: "CLI" - url: "guide/cli/index.html" + url: "cordova-cli/index.html" - name: "Hooks" url: "guide/appdev/hooks/index.html" - name: "Plugin.xml" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_data/toc/sl-dev-manual.yml ---------------------------------------------------------------------- diff --git a/www/_data/toc/sl-dev-manual.yml b/www/_data/toc/sl-dev-manual.yml index fc64930..6836d43 100644 --- a/www/_data/toc/sl-dev-manual.yml +++ b/www/_data/toc/sl-dev-manual.yml @@ -9,7 +9,7 @@ - name: "Create apps" children: - name: "Create your first app" - url: + url: "guide/cli/index.html" - name: "Platform support" url: "guide/support/index.html" - name: "Develop for platforms" @@ -81,7 +81,7 @@ - name: "Events" url: "cordova/events/events.html" - name: "CLI" - url: "guide/cli/index.html" + url: "cordova-cli/index.html" - name: "Hooks" url: "guide/appdev/hooks/index.html" - name: "Plugin.xml" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_data/toc/zh-dev-manual.yml ---------------------------------------------------------------------- diff --git a/www/_data/toc/zh-dev-manual.yml b/www/_data/toc/zh-dev-manual.yml index fc64930..6836d43 100644 --- a/www/_data/toc/zh-dev-manual.yml +++ b/www/_data/toc/zh-dev-manual.yml @@ -9,7 +9,7 @@ - name: "Create apps" children: - name: "Create your first app" - url: + url: "guide/cli/index.html" - name: "Platform support" url: "guide/support/index.html" - name: "Develop for platforms" @@ -81,7 +81,7 @@ - name: "Events" url: "cordova/events/events.html" - name: "CLI" - url: "guide/cli/index.html" + url: "cordova-cli/index.html" - name: "Hooks" url: "guide/appdev/hooks/index.html" - name: "Plugin.xml" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/_layouts/docs.html ---------------------------------------------------------------------- diff --git a/www/_layouts/docs.html b/www/_layouts/docs.html index f31166e..3c52fce 100644 --- a/www/_layouts/docs.html +++ b/www/_layouts/docs.html @@ -189,7 +189,7 @@ analytics_id: UA-64283057-1 <span aria-hidden="true">×</span> </button> {{ page.plugin_version_text }} {{ page.plugin_version }}. - <a href="https://github.com/{{ page.plugin_name }}/releases"> + <a href="https://github.com/apache/{{ page.plugin_name }}/releases"> {{ page.visit_github_text }} </a> </div> http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/docs/en/dev/guide/cli/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/cli/index.md b/www/docs/en/dev/guide/cli/index.md index 1c5f764..dc69c07 100644 --- a/www/docs/en/dev/guide/cli/index.md +++ b/www/docs/en/dev/guide/cli/index.md @@ -17,65 +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. - -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) -* Android (Mac, Linux, Windows) -* BlackBerry 10 (Mac, Linux, Windows) -* Windows Phone 8 (Windows) -* Windows (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. @@ -101,152 +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: - - $ cordova platform add ios - $ cordova platform add android - $ cordova platform add blackberry10 +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`: -Run any of these from a Windows machine, where _wp_ refers to -different versions of the Windows Phone operating system: + $ cordova platform add ios --save + $ cordova platform add android --save - $ cordova platform add wp8 - $ cordova platform add windows - $ cordova platform add android - $ cordova platform add blackberry10 +To check your current set of platforms: -Run this to check your current set of platforms: + $ cordova platform ls - $ cordova platforms ls +Running commands to add or remove platforms affects the contents of +the project's _platforms_ directory, where each specified platform +appears as a subdirectory. -(Note the `platform` and `platforms` commands are synonymous.) +> 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. -Run either of the following synonymous commands to remove a platform: +###See Also +- [Cordova platform command reference documentation](../../cordova-cli/index.html#cordova-platform-command) - $ cordova platform remove blackberry10 - $ cordova platform rm android +##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. -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. +To check if you satisfy requirements for building the platform: +``` + $ 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 -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. -Use this approach if you simply want to initialize a project using the CLI and -then switch to an SDK for native work. + Requirements check results for ios: + Apple OS X: not installed + Cordova tooling for iOS requires Apple OS X + Error: Some of requirements check failed +``` -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][DeviceReadyEvent] 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 @@ -256,14 +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. - - -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:  @@ -279,103 +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 devices, you would have to enable a __USB debugging__ option on -the device, and perhaps add a USB driver depending on your development -environmnent. - -## 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: - - $ 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 +testing, following procedures that vary for each platform. -* Access files on device or network (File API): +###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-file - $ cordova plugin add cordova-plugin-file-transfer +## Add Plugins -* Notification via dialog box or vibration: +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-dialogs - $ cordova plugin add cordova-plugin-vibration +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: -* Contacts: + $ 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-contacts + $ 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 -* Globalization: +Plugins can also be added using a directory or a git repo. - $ cordova plugin add cordova-plugin-globalization - -* Splashscreen: - - $ cordova plugin add cordova-plugin-splashscreen - -* Open new browser windows (InAppBrowser): - - $ 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 @@ -384,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 [email protected] - -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 + $ cordova plugin ls + cordova-plugin-camera 2.1.0 "Camera" + cordova-plugin-whitelist 1.2.1 "Whitelist" -or a branch: - - $ cordova plugin add https://github.com/apache/cordova-plugin-console.git#CB-8438cordova-plugin-console - -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 @@ -469,7 +236,9 @@ 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. @@ -479,7 +248,9 @@ font size for Android 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. @@ -491,31 +262,6 @@ graphic into the iOS interface, stored in 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 @@ -528,30 +274,17 @@ Use this syntax to install a specific version: $ sudo npm install -g [email protected] -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. -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 http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/312e2d5a/www/docs/en/dev/guide/support/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/support/index.md b/www/docs/en/dev/guide/support/index.md index 8b622f5..6df9281 100644 --- a/www/docs/en/dev/guide/support/index.md +++ b/www/docs/en/dev/guide/support/index.md @@ -78,7 +78,7 @@ CLI's shorthand names. <tr> <th></th> - <th colspan="20">Platform APIs</th> + <th colspan="20"><h2>Core plugin APIs</h2></th> </tr> <tr> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
