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