You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by fi...@apache.org on 2013/05/18 08:03:16 UTC
[1/2] git commit: start of node module usage documentation
Updated Branches:
refs/heads/master 2be13c758 -> cbfdc6f9f
start of node module usage documentation
Project: http://git-wip-us.apache.org/repos/asf/cordova-plugman/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugman/commit/638d4b83
Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugman/tree/638d4b83
Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugman/diff/638d4b83
Branch: refs/heads/master
Commit: 638d4b83ab94350c430e7200a9dad15603c9bfd8
Parents: 2be13c7
Author: Fil Maj <ma...@gmail.com>
Authored: Fri May 17 22:37:17 2013 -0700
Committer: Fil Maj <ma...@gmail.com>
Committed: Fri May 17 22:37:17 2013 -0700
----------------------------------------------------------------------
README.md | 12 +++++++++++-
1 files changed, 11 insertions(+), 1 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-plugman/blob/638d4b83/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 2574e17..31bad05 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ This document defines tool usage.
* BlackBerry 10
* Windows Phone 7
-## Usage
+## Command Line Usage
plugman --install --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]
plugman --uninstall --platform <ios|android|blackberr10|wp7|wp8> --project <directory> --plugin <name> [--www <directory>] [--plugins_dir <directory>]
@@ -42,6 +42,16 @@ Other parameters:
* `--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.
+## Node Module Usage
+
+ > require('plugman')
+ { install: [Function: installPlugin],
+ uninstall: [Function: uninstallPlugin],
+ fetch: [Function: fetchPlugin],
+ prepare: [Function: handlePrepare] }
+
+### `install` method
+
## Example Plugins
[2/2] git commit: added node module usage docs
Posted by fi...@apache.org.
added node module usage docs
Project: http://git-wip-us.apache.org/repos/asf/cordova-plugman/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugman/commit/cbfdc6f9
Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugman/tree/cbfdc6f9
Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugman/diff/cbfdc6f9
Branch: refs/heads/master
Commit: cbfdc6f9f5ac1100cc22d41ffde43f948595c123
Parents: 638d4b8
Author: Fil Maj <ma...@gmail.com>
Authored: Fri May 17 23:02:33 2013 -0700
Committer: Fil Maj <ma...@gmail.com>
Committed: Fri May 17 23:02:33 2013 -0700
----------------------------------------------------------------------
README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 55 insertions(+), 0 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-plugman/blob/cbfdc6f9/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 31bad05..166c39f 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,7 @@ Other parameters:
## Node Module Usage
+ node
> require('plugman')
{ install: [Function: installPlugin],
uninstall: [Function: uninstallPlugin],
@@ -52,6 +53,56 @@ Other parameters:
### `install` method
+ module.exports = function installPlugin(platform, project_dir, id, plugins_dir, subdir, cli_variables, www_dir, callback) {
+
+Installs a plugin into a specified cordova project of a specified platform.
+
+ * `platform`: one of `android`, `ios`, `blackberry10`, `wp7` or `wp8`
+ * `project_dir`: path to an instance of the above specified platform's cordova project
+ * `id`: a string representing the `id` of the plugin, a path to a cordova plugin with a valid `plugin.xml` file, or an `https://` or `git://` url to a git repository of a valid cordova plugin
+ * `plugins_dir`: path to directory where plugins will be stored, defaults to `<project_dir>/cordova/plugins`
+ * `subdir`: subdirectory within the plugin directory to consider as plugin directory root, defaults to `.`
+ * `cli_variables`: an object mapping cordova plugin specification variable namess (see [plugin specification](plugin_spec.md)) to values
+ * `www_dir`: path to directory where web assets are to be copied to, defaults to the specified project directory's `www` dir (dependent on platform)
+ * `callback`: callback to invoke once complete. If specified, will pass in an error object as a first parameter if the action failed. If not and an error occurs, `plugman` will throw the error
+
+### `uninstall` method
+
+ module.exports = function uninstallPlugin(platform, project_dir, id, plugins_dir, cli_variables, www_dir, callback) {
+
+Uninstalls a previously-installed cordova plugin from a specified cordova project of a specified platform.
+
+ * `platform`: one of `android`, `ios`, `blackberry10`, `wp7` or `wp8`
+ * `project_dir`: path to an instance of the above specified platform's cordova project
+ * `id`: a string representing the `id` of the plugin
+ * `plugins_dir`: path to directory where plugins are stored, defaults to `<project_dir>/cordova/plugins`
+ * `subdir`: subdirectory within the plugin directory to consider as plugin directory root, defaults to `.`
+ * `cli_variables`: an object mapping cordova plugin specification variable namess (see [plugin specification](plugin_spec.md)) to values
+ * `www_dir`: path to directory where web assets are to be copied to, defaults to the specified project directory's `www` dir (dependent on platform)
+ * `callback`: callback to invoke once complete. If specified, will pass in an error object as a first parameter if the action failed. If not and an error occurs, `plugman` will throw the error
+
+### `fetch` method
+
+Copies a cordova plugin into a single location that plugman uses to track which plugins are installed into a project.
+
+ module.exports = function fetchPlugin(plugin_dir, plugins_dir, link, subdir, git_ref, callback) {
+
+ * `plugin_dir`: path or URL to a plugin directory/repository
+ * `plugins_dir`: path housing all plugins used in this project
+ * `link`: if `plugin_dir` points to a local path, will create a symbolic link to that folder instead of copying into `plugins_dir`, defaults to `false`
+ * `subdir`: subdirectory within the plugin directory to consider as plugin directory root, defaults to `.`
+ * `gitref`: if `plugin_dir` points to a URL, this value will be used to pass into `git checkout` after the repository is cloned, defaults to `HEAD`
+ * `callback`: callback to invoke once complete. If specified, will pass in an error object as a first parameter if the action failed. If not and an error occurs, `plugman` will throw the error
+
+### `prepare` method
+
+Finalizes plugin installation by making configuration file changes and setting up a JavaScript loader for js-module support.
+
+ module.exports = function handlePrepare(project_dir, platform, plugins_dir) {
+
+ * `project_dir`: path to an instance of the above specified platform's cordova project
+ * `platform`: one of `android`, `ios`, `blackberry10`, `wp7` or `wp8`
+ * `plugins_dir`: path housing all plugins used in this project
## Example Plugins
@@ -74,6 +125,10 @@ Linking the global executable to the git repo:
npm install
sudo npm link
+### Running Tests
+
+ npm test
+
## Plugin Directory Structure
A plugin is typically a combination of some web/www code, and some native code.