Wondering what’s next for npm?Check out our public roadmap! »

    plugman

    3.0.1 • Public • Published

    plugman

    A command line tool to install and uninstall plugins for use with Apache Cordova projects.

    This document defines tool usage.

    Requirements

    You must have git on your PATH to be able to install plugins directly from remote git URLs.

    Plugin Specification

    --> Available on docs.cordova.io <--

    Quickstart

    npm install -g plugman
    

    Design Goals

    • Facilitate programmatic installation and manipulation of plugins
    • Detail the dependencies and components of individual plugins
    • Allow code reuse between different target platforms

    Supported Platforms

    • Amazon Fire OS
    • Android
    • BlackBerry 10
    • iOS
    • Tizen
    • Windows Phone 8
    • Windows 8

    Command Line Usage

    Display all available plugman commands:

    plugman help
    

    Plugin Management

    Install a plugin into a Cordova project:

    plugman install --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]
    

    Uninstall a Plugin from a Cordova project:

    plugman uninstall --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]
    

    For each command (install and uninstall), 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 for more information.

    Registry Search

    Search the Plugin registry for plugin id's that match the given space separated list of keywords.

    plugman search <plugin keywords>
    

    Configuration Management:

    Display the current list of configuration settings:

    plugman config ls
    

    Display the current repository endpoint:

    plugman config get registry
    

    Set the registry endpoint:

    plugman config set registry <url-to-registry>
    

    You should leave this set to http://registry.cordova.io, unless you want to use a third party plugin registry.

    Node Module Usage

    This section details how to consume Plugman as a node module and is only for Cordova tool authors and other hackers. You should not need to read this section if you are just using Plugman to manage a Cordova project.

    node
    > require('plugman')
    { install: [Function: installPlugin],
      uninstall: [Function: uninstallPlugin],
      fetch: [Function: fetchPlugin],
      search: [Function: search],
      publish: [Function: publish],
      unpublish: [Function: unpublish],
      adduser: [Function: adduser],
      prepare: [Function: handlePrepare],
      create: [Function: create],
      platform: [Function: platform] }
    

    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 amazon-fireos, android, ios, blackberry10, 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 or a plugin published to the Cordova registry
    • 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 names (see plugin specification) 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 amazon-fireos, android, ios, blackberry10, 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 names (see plugin specification) 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, URL to a plugin directory/repository or name of a plugin published to the Cordova registry.
    • 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 amazon-fireos, android, ios, blackberry10, or wp8
    • plugins_dir: path housing all plugins used in this project

    Registry related actions

    adduser method

    Adds a user account to the registry. Function takes no arguments other than a an optional callback

    module.exports = function(callback) {
    

    publish method

    Publishes plugins to the registry. plugin_paths is an array of plugin paths to publish to the registry.

    module.exports = function(plugin_paths, callback) {
    

    unpublish method

    unpublishes plugins from the registry. Can unpublish a version by specifying plugin@version or the whole plugin by just specifying plugin. plugins is an array of plugin[@version] elements.

    module.exports = function(plugins, callback) {
    

    search method

    Searches plugins in the registry. search_opts is an array of keywords

    module.exports = function(search_opts, callback) {
    

    config method

    Configures registry settings. params is an array that describes the action /* * var params = ['get', 'registry']; * var params = ['set', 'registry', 'http://registry.cordova.io']; * module.exports = function(params, callback) { */

    Create plugin related actions

    create method

    Creates basic scaffolding for a new plugin

    module.exports = function create( name, id, version, pluginPath, options, callback ) {...}

    • name : a name for the plugin
    • id : an id for the plugin
    • version : a version for the plugin
    • pluginPath : a path to create the plugin in
    • options : an array of options
    • 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

    platform method

    Add/Remove a platform from a newly created plugin

    module.exports = function platform( { operation: operation, platform_name: cli_opts.platform_name } );

    • operation : "add or remove"
    • platform_name : ios, android

    Example Plugins

    Development

    Basic installation:

    git clone https://git-wip-us.apache.org/repos/asf/cordova-plugman.git
    cd cordova-plugman
    npm install -g
    

    Linking the global executable to the git repo:

    git clone https://git-wip-us.apache.org/repos/asf/cordova-plugman.git
    cd cordova-plugman
    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. However, plugins may have only one of these things - a plugin could be a single JavaScript file, or some native code with no corresponding JavaScript.

    Here is a sample plugin named foo with android and ios platforms support, and 2 www assets.

    foo-plugin/
    |- plugin.xml     # xml-based manifest
    |- src/           # native source for each platform
    |  |- android/
    |  |  `- Foo.java
    |  `- ios/
    |     |- CDVFoo.h
    |     `- CDVFoo.m
    |- README.md
    `- www/
       |- foo.js
       `- foo.png
    

    This structure is suggested, but not required.

    Contributors

    See the package.json file for attribution notes.

    License

    Apache License 2.0

    Keywords

    none

    Install

    npm i plugman

    DownloadsWeekly Downloads

    964

    Version

    3.0.1

    License

    Apache-2.0

    Unpacked Size

    61.2 kB

    Total Files

    23

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar