You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by mr...@apache.org on 2013/11/22 22:30:34 UTC
docs commit: redo CB-5122 pull request 140
Updated Branches:
refs/heads/master b222806e1 -> a1e09bb98
redo CB-5122 pull request 140
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/a1e09bb9
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/a1e09bb9
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/a1e09bb9
Branch: refs/heads/master
Commit: a1e09bb9884905cf023304275022e2a5168290fe
Parents: b222806
Author: mbillau <mi...@gmail.com>
Authored: Fri Nov 22 16:15:57 2013 -0500
Committer: mbillau <mi...@gmail.com>
Committed: Fri Nov 22 16:15:57 2013 -0500
----------------------------------------------------------------------
docs/en/edge/guide/cli/index.md | 60 +++++---
docs/en/edge/guide/overview/index.md | 51 ++++++-
docs/en/edge/guide/platforms/android/index.md | 12 +-
docs/en/edge/index.md | 4 +
docs/en/edge/plugin_ref/plugman.md | 169 ++++++++++++++++-----
5 files changed, 231 insertions(+), 65 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a1e09bb9/docs/en/edge/guide/cli/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/cli/index.md b/docs/en/edge/guide/cli/index.md
index ad88ff4..ca5b7c4 100644
--- a/docs/en/edge/guide/cli/index.md
+++ b/docs/en/edge/guide/cli/index.md
@@ -23,9 +23,10 @@ license: Licensed to the Apache Software Foundation (ASF) under one
This guide shows you how to create applications 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 them within an emulator. You can
-also use the CLI to initialize project code, after which you use
-various platforms' SDKs to develop them further.
+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 (See the Overview for a description
+of the various workflows.) However, you can also use the CLI to initialize project code, after
+which you use various platforms' SDKs and shell tools for continued development.
## Prerequisites
@@ -57,7 +58,7 @@ 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` or `npm` on your
- command line.
+ command line.
1. Install the `cordova` utility. In Unix, prefixing the additional
`sudo` command may be necessary to install development utilities in
@@ -69,6 +70,12 @@ To install the `cordova` command-line tool, follow these steps:
platform SDKs. Following installation, you should be able to run
`cordova` on the command line.
+ **NOTE**: The `-g` flag above tells npm to install cordova globally.
+ 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` and on Unix at
+ `/usr/local/share/npm`.
+
## Create the App
Go to the directory where you maintain your source code, and run a
@@ -76,8 +83,8 @@ command such as the following:
$ cordova create hello com.example.hello HelloWorld
-It may take some time for the command to complete, so be patient. Run
-the `cordova -d` to see information about progress.
+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 specifies a _hello_ directory to be generated
for your project. Its `www` subdirectory houses your application's
@@ -133,17 +140,27 @@ 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`. By default,
-each platform's configuration file is set up to be able to access all
-of Cordova's APIs.
-
-If you wish, you can use an SDK at this point to open the project you
-created. However, any edits you make to the project within an SDK
-affect the derivative set of assets, not the original cross-platform
-source files. Use this approach if you simply want to initialize a
-project.
-(See the Platform Guides for information on how to develop applications within each SDK.)
-Read on if you wish to use command-line tools for the entire
+`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 are strongly discouraged
+from editing any files in the `/platforms/` folder unless you know what you are doing
+or are specifically told otherwise in documentation. This is because the files in the
+`/platforms/` direcotry will be overwritten on prepare or plugin reinstallation.
+
+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 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.
## Build the App
@@ -243,8 +260,13 @@ Searching for only the `bar` term yields and additional result:
org.apache.cordova.statusbar - Cordova StatusBar Plugin
The `cordova plugin add` command requires you to specify the
-repository for the plugin code. Here are examples of features you
-might add:
+repository for the plugin code. Please note that when you follow the
+Web Project Dev workflow and use the CLI, the CLI will take care of adding
+the plugin code to the appropriate place for each platform. (If you are following the
+Native Project Dev Workflow, you will have to add plugins using Plugman (guide link here),
+multiple times for each platform.)
+
+Here are examples of how you might use the CLI to add features to the app:
* Basic device information (Device API):
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a1e09bb9/docs/en/edge/guide/overview/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/overview/index.md b/docs/en/edge/guide/overview/index.md
index 02f0702..b33e9f5 100644
--- a/docs/en/edge/guide/overview/index.md
+++ b/docs/en/edge/guide/overview/index.md
@@ -66,9 +66,46 @@ components to communicate with each other.
## Development Paths
-The easiest way to set up an application is to run the `cordova`
-command-line utility, also known as the _command-line interface_
-(CLI). (To install the CLI, see The Command-Line Interface.)
+As of version 3.0, you can use two basic workflows to create
+a mobile application. While you can accomplish the same
+thing using both workflows, certain tasks are better suited to using one workflow
+over the other. For this reason, you should understand both workflows so
+that you can use the best tool for the best situation.
+
+The two main workflows that are supported are the _Web Project Dev_ workflow and the _Native Platform Dev_ workflow.
+
+### Web Project Dev
+
+You can think of the first workflow as the _Web Project Dev_ workflow. You should use
+this workflow when you want to create a Cordova application that runs on
+as many mobile operating systems as possible with as little platform-specific
+development work as possible. This workflow came into existence with Cordova 3.0
+and the creation of the Cordova _Command-line Interface_ (CLI). The CLI abstracts
+away a lot of the functionality of lower-level shell scripts that take care of the
+details involved with building your app, such as copying your web assets into
+the correct folders for each mobile platform, making platform specific configuration
+changes, or running specific build scripts to generate application binaries. You can read
+more about the _Web Project Dev_ workflow in The Command-line Interface. Please note
+that often when people speak of the "CLI," they are talking about this _Web Project Dev_
+workflow.
+
+### Native Platform Dev
+
+The second workflow can be thought of as a _Native Platform Dev_ workflow. You should use it
+when you want to focus on building an application for a single platform and are
+interested in changing the lower-level platform details. While you can still use this workflow
+to build cross-platform apps, the lack of tools to abstract away the various build steps will
+make it more difficult. For example, you will have to use Plugman to
+install the same plugin once for each platform that you want to support. The
+benefit to using this _Native Platform Dev_ workflow is that it gives you access to the lower-level
+shell scripts to build and test the application, so if you are hacking on the native
+side of things, this workflow is the most efficient way to test your changes. This workflow
+is also appropriate if you want to use the CordovaWebView as a small part in a larger native
+application (See the Embedding WebViews guide.) You can read about this workflow in the different
+Shell Tool guides, for instance, Android Shell Tool Guide and iOS Shell Tool Guide.
+
+When first starting out, it might be easiest to use the _Web Project Dev_ workflow
+to create an application. (To install the CLI, see The Command-line Interface.)
Depending on the set of platforms you wish to target, you can rely on
the CLI for progressively greater shares of the development cycle:
@@ -89,10 +126,10 @@ the CLI for progressively greater shares of the development cycle:
For comprehensive testing, you can also generate application files
and install them directly on a device.
-At any point in the development cycle, you can also rely on
-platform-specific SDK tools, which may provide a richer set of
-options.
-(See the Platform Guides for details about each platform's SDK tool set.)
+At any point in the development cycle, you can switch to using more of the _Native Platform
+Dev_ workflow. The platform-specific SDK tools provided may provide a richer set of
+options. (See the Platform Guides for details about each platform's SDK tool set.)
+
An SDK environment is more appropriate if you want implement a hybrid
app that mixes web-based and native application components.
You may use the command-line utility to initially generate the app, or
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a1e09bb9/docs/en/edge/guide/platforms/android/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/index.md b/docs/en/edge/guide/platforms/android/index.md
index 1a11178..039294b 100644
--- a/docs/en/edge/guide/platforms/android/index.md
+++ b/docs/en/edge/guide/platforms/android/index.md
@@ -20,8 +20,14 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# Android Platform Guide
This guide shows how to set up your SDK development environment to
-deploy Cordova apps for Android devices. See the following for more
-detailed platform-specific information:
+deploy Cordova apps for Android devices. It walks you through the process
+of installing the Android SDK, opening an Android project in Eclipse SDK,
+and deploying to an emulator or device. You will need to follow this guide
+to at least Install the Android SDK, regardless of which workflow you
+are following. (Both the _Web Project Dev_ and _Native Platform Dev_ workflows
+require the Android SDK to be installed and accessable via your PATH.)
+
+See the following for more detailed platform-specific information:
* Android Configuration
* Android WebViews
@@ -53,8 +59,6 @@ the Android SDK. See The Command-Line Interface for
information how to install it, add projects, then build and deploy a
project.
-## Install the SDK
-
Install the Android SDK from
[developer.android.com/sdk](http://developer.android.com/sdk/). The android sdk
is distributed as an 'adt-bundle-<os>-<arch>-<ver>' file.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a1e09bb9/docs/en/edge/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/index.md b/docs/en/edge/index.md
index dc10cac..7a2e8cc 100644
--- a/docs/en/edge/index.md
+++ b/docs/en/edge/index.md
@@ -38,6 +38,10 @@ license: Licensed to the Apache Software Foundation (ASF) under one
<span>Set up each SDK and update projects</span>
</li>
<li>
+ <h2>Using Plugman to Manage Plugins</h2>
+ <span>Using Plugman to manage Plugins without the CLI</span>
+ </li>
+ <li>
<h2>The config.xml File</h2>
<span>Customize the features of your app.</span>
</li>
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a1e09bb9/docs/en/edge/plugin_ref/plugman.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/plugin_ref/plugman.md b/docs/en/edge/plugin_ref/plugman.md
index 078f5ce..2c18a5b 100644
--- a/docs/en/edge/plugin_ref/plugman.md
+++ b/docs/en/edge/plugin_ref/plugman.md
@@ -20,34 +20,115 @@
# Using Plugman to Manage Plugins
From version 3.0 onward, Cordova implements all device APIs as
-plugins, and leaves them disabled by default. It also supports two
+plugins, and leaves them disabled by default. It also supports two
different ways to add and remove plugins. The first is by using the
`cordova` CLI described in The Command-Line Interface. The second is
by using a lower-level
-[plugman](https://github.com/apache/cordova-plugman/)
-command-line interface. This guide concentrates on the second
-approach, which may be useful for developers who want to upgrade their
-version of Cordova, but who haven't yet adopted the Cordova CLI in
-their workflow.
+[Plugman](https://github.com/apache/cordova-plugman/)
+command-line interface ("Native platform dev" workflow.) The main difference between these two development
+paths is that Plugman can only add plugins to one platform at a time, whereas the CLI will add plugins
+to all of the platforms that you are targeting. Because of this, it makes more sense to use Plugman when
+you are working closely with a single platform, hence the "Native Platform Dev" name of the workflow.
-For more information on plugman, see
-[the README file in its repository](https://github.com/apache/cordova-plugman/blob/master/README.md).
+For more information on Plugman, especially if you are interested in consuming Plugman as a node module
+or hacking on the Plugman code, see [the README file in its repository](https://github.com/apache/cordova-plugman/blob/master/README.md).
-## Basic Commands
+## Installing Plugman
To install plugman, you must have [node](http://nodejs.org/) installed
-on your machine:
+on your machine. Then you can run the following command from anywhere in your environment to install plugman globally, so that it
+is available from any directory on your machine:
$ npm install -g plugman
-
-Here is the syntax to add a plugin for each platform:
+
+You must have also have `git` on your `PATH` to be able to install plugins directly from remote git URLs.
+
+**TIP:** If you find that after installing plugman with npm you are still unable to run any `plugman` commands, make sure that you have
+added the `/npm/` directory into your `PATH`.
+
+**NOTE:** You can skip this step if you don't want to pollute your global npm namespace by installing Plugman globally. If this is the case, then
+when you create a Cordova project with the shell tools, there will be a `node_modules` directory inside your project which contains Plugman.
+Since you did not instally globally, you will have to invoke node for every Plugman command, for example `node ./node_modules/plugman/main.js -version`.
+The rest of this guide assumes you have installed Plugman globally, meaning you can invoke it with just `plugman`.
+
+## Create a Cordova Project
+
+Before you can use Plugman, you must create a Cordova project. You can do this with either the Command-line Interface or with
+the lower level shell scripts. Instructions for using the shell scripts to create your project are located in the various "Command-line Tools" guides
+listed on the Platform Guides page.
+
+## Adding a Plugin
+
+Once you have installed Plugman and have created a Cordova project, you can start adding plugins to the platform with:
$ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]
-
-To uninstall a plugin:
+
+Using minimum parameters, this command installs a plugin into a cordova project. You must specify a platform and cordova project location for that platform. You also must specify a plugin, with the different `--plugin` parameter forms being:
+
+ * `name`: The directory name where the plugin contents exist. This must be an existing directory under the `--plugins_dir` path (see below for more info) or a plugin in the Cordova registry.
+ * `url`: A URL starting with https:// or git://, pointing to a valid git repository that is clonable and contains a `plugin.xml` file. The contents of this repository would be copied into the `--plugins_dir`.
+ * `path`: A path to a directory containing a valid plugin which includes a `plugin.xml` file. This path's contents will be copied into the `--plugins_dir`.
+
+Other parameters:
+
+* `--plugins_dir` defaults to `<project>/cordova/plugins`, but can be any directory containing a subdirectory for each fetched plugin.
+* `--www` defaults to the project's `www` folder location, but can be any directory that is to be used as cordova project application web assets.
+* `--variable` allows to specify certain variables at install time, necessary for certain plugins requiring API keys or other custom, user-defined parameters. Please see the [plugin specification](plugin_spec.md) for more information.
+
+## Remove a Plugin
+
+To uninstall a plugin, you simply pass the `--uninstall` flag and provide the plugin ID.
$ plugman --uninstall --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]
-
+
+## Help Commands
+
+Plugman features a global help command which may help you if you get stuck or are experiencing problems. It will display
+a list of all available Plugman commands and their syntax:
+
+ plugman -help
+ plugman # same as above
+
+ **NOTE**: `plugman -help` may show some additional registry-related commands. These commands are for plugin developers and may not be implemented on third-party plugin registries.
+
+
+You can also append the `--debug|-d` flag to any Plugman command to run that command in verbose mode, which will display
+any internal debugging messages as they are emitted and may help you track down problems like missing files.
+
+ # Adding Android battery-status plugin to "myProject":
+ plugman -d --platform android --project myProject --plugin org.apache.cordova.battery-status
+
+Finally, you can use the `--version|-v` flag to see which version of Plugman you are using.
+
+ plugman -v
+
+## Registry Actions
+
+There are a number of plugman commands that can be used for interacting with the [Plugin registry](http://plugins.cordova.io).
+Please note that these registry commands are specific to the _plugins.cordova.io_ plugin registry and may not be implemented by
+third-party plugin registries.
+
+### Searching for a Plugin
+
+You can use Plugman to search the [Plugin registry](http://plugins.cordova.io) for plugin id's that match the given space separated list of keywords.
+
+ plugman search <plugin keywords>
+
+### Changing the Plugin Registry
+
+You can get or set the URL of the current plugin registry that plugman is using. Generally you should leave this set at http://registry.cordova.io unless you want to use a third party plugin registry.
+
+ plugman config set registry <url-to-registry>
+ plugman config get registry
+
+### Get Plugin Information
+
+You can get information about any specific plugin stored in the plugin repository with:
+
+ plugman info <id>
+
+This will contact the plugin registry and fetch information such as the plugin's version number.
+
## Installing Core Plugins
The examples below show how to add plugins as needed so that any
@@ -56,55 +137,73 @@ version 3.0. For each command, you need to select the target
platform, and reference the platform's project directory.
* cordova-plugin-battery-status
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.battery-status
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.battery-status
* cordova-plugin-camera
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.camera
-
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.camera
+
* cordova-plugin-console
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.console
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.console
* cordova-plugin-contacts
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.contacts
-
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.contacts
+
* cordova-plugin-device
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.device
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.device
* cordova-plugin-device-motion (accelerometer)
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.device-motion
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.device-motion
* cordova-plugin-device-orientation (compass)
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.device-orientation
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.device-orientation
* cordova-plugin-dialogs
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.dialogs
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.dialogs
* cordova-plugin-file
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.file
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.file
* cordova-plugin-file-transfer
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.file-transfer
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.file-transfer
* cordova-plugin-geolocation
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.geolocation
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.geolocation
* cordova-plugin-globalization
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.globalization
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.globalization
* cordova-plugin-inappbrowser
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.inappbrowser
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.inappbrowser
* cordova-plugin-media
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.media
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.media
* cordova-plugin-media-capture
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.media-capture
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.media-capture
* cordova-plugin-network-information
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.network-information
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.network-information
* cordova-plugin-splashscreen
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.splashscreen
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.splashscreen
* cordova-plugin-vibration
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.vibration
+
+ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin org.apache.cordova.vibration