CordovaProject API

CordovaProjectAPI.js

/*jshint node:true, unused:false */

// TODO: Refine usage of options parameter

/**
 * Class, that acts as abstract on top of Cordova project. Encapsulates the
 *   basic properties, that represents project configuration and methods for
 *   managing the project. This class shouldn't be instantiated directly.
 *   Instead user is intended to use 'getProjectAt' and 'createProject' class
 *   methods.
 *
 * @param  {String} appName   Optional. Application name, that will be used for
 *   '<name>' element in config.xml. If not specified, 'HelloCordova' will be used.
 *
 * @param  {String} appId     Optional. Application id, that will be used for 'id'
 *   attribute of '<widget>' element. If not specified 'io.cordova.hellocordova'
 *   will be used.
 */
function CordovaProject (appName, appId) {}

/**
 * Gets a CordovaProject instance for specified directory. Returns a cached
 *   value, if exists or instantiates a new CordovaProject.
 *
 * @param   {String}  projectDir  Path to cordova project.
 *
 * @return  {Promise<CordovaProject>}  Returns a promise either fulfilled with a
 *   Cordova project instance or rejected with CordovaError.
 */
CordovaProject.getProjectAt = function (projectDir) {};

/**
 * Initializes an empty cordova project at specified directory. Copies
 *
 * @param  {String} targetDir Path to directory, where new project will be
 *   created.
 * @param  {String} appName   Optional. Application name, that will be used for
 *   '<name>' element in config.xml. If not specified, 'HelloCordova' will be
 *   used.
 * @param  {String} appId     Optional. Application id, that will be used for
 *   'id' attribute of '<widget>' element. If not specified
 *   'io.cordova.hellocordova' will be used.
 * @param  {Object} options   An options object. See list of common options
 *   below:
 * @param  {String} options.wwwSource  Specifies the www assets source for new
 *   application instead of default one. If not specified, the Cordova
 *   HelloWorld assets will be used.
 * @param  {Boolean}  options.link  Specifies that www source will be symlinked
 *   to app's directory instead of copying.
 *
 * @return {Promise<CordovaProject>} Returns a promise either fulfilled with a
 *   Cordova project instance or rejected with CordovaError.
 */
CordovaProject.createProject = function (targetDir, appName, appId, options) {};

/**
 * Adds a new platform to project.
 *
 * @param  {String}  platformSpec  A platform spec that should be one of
 *   following:
 *   * valid platform name: 'android', 'windows', etc.
 *   * valid npm identifier, that resolves to valid platform: [email protected]
 *   * git url, that points to repo with valid platform:
 *       http://github.com/apache/cordova-android.git#4.0.0
 *   * path to local repo of valid platform:
 *       /my/cordova/repositories/cordova-android
 *
 * @param {Boolean}  saveToProject  Flag that indicates, that added
 *   platform should be saved into project configuration to be easily
 *   restored after. The approach is similar to 'npm install --save' command.
 *
 * @return {Promise} A promise either fulfilled if platform is installed
 *   successfully, or rejected with CordovaError.
 */
CordovaProject.prototype.addPlatform = function (platformSpec, saveToProject) {};

/**
 * Removes a platform from project.
 *
 * @param  {String}  platformName  A name of platform that should be removed
 *   from project.
 *
 * @param {Boolean}  saveToProject  Flag that indicates, that platform
 *   also should be removed from project configuration.
 *
 * @return {Promise} A promise either fulfilled if platform is removed
 *   successfully, or rejected with CordovaError.
 */
CordovaProject.prototype.removePlatform = function (platformName, saveToProject) {};

/**
 * Adds a new plugin into project. Installs it to each platform in project.
 *
 * @param  {String}  pluginSpec  A plugin spec that should be one of
 *   following:
 *   * valid plugin id that can be resolved through either cordova
 *   plugin registry or npm:
 *       'org.apache.cordova.globalization', 'cordova-plugin-globalization'
 *   * valid npm identifier, that resolves to valid plugin:
 *       [email protected]
 *   * git url, that points to repo with valid plugin:
 *       http://github.com/apache/cordova-plugin-globalization.git#r1.0.0
 *   * path to local repo of valid plugin:
 *       /my/cordova/repositories/cordova-plugin-globalization
 *
 * @param  {Object}  options   An options object. Possible options are:
 *   * saveToProject: Boolean. Flag that indicates, that added plugin
 *   should be saved into project configuration.
 *   * link: Boolean. Flag that specifies that plugin sources will be symlinked to
 *   app's directory instead of copying if possible.
 *   * searchPath: String. Valid path, that will be used to search for plugin
 *   in local filesystem.
 *   * variables: Object. An object that represents variables that will
 *   be used to install plugin. See more details on plugin variables in
 *   documentation: https://cordova.apache.org/docs/en/4.0.0/plugin_ref_spec.md.html
 *
 * @return {Promise} A promise either fulfilled if plugin is installed
 *   successfully, or rejected with CordovaError.
 */
CordovaProject.prototype.addPlugin = function (pluginSpec, options) {};

/**
 * Removes a plugin from project.
 *
 * @param  {String}  pluginId  An id of plugin that should be removed
 *   from project.
 *
 * @param {Boolean}  saveToProject  Flag that indicates, that plugin
 *   also should be removed from project configuration.
 *
 * @return {Promise} A promise either fulfilled if platform is removed
 *   successfully, or rejected with CordovaError.
 */
CordovaProject.prototype.removePlugin = function (pluginId, options) {};

/**
 * Enumerates all platforms, installed into project.
 *
 * @return  {Object<String, PlatformApi>}  An array of PlatformApi instances.
 */
CordovaProject.prototype.getInstalledPlatforms = function () {};

/**
 * Enumerates plugins, installed into project.
 *
 * @return  {Array<PluginInfo>}  An array of PluginInfo instances.
 */
CordovaProject.prototype.getInstalledPlugins = function () {};

// TODO: Refine list of available options. Maybe a separate class?

/**
 * Builds an application package for specified platform. If platform is
 *   specified, this acts as a shortcut for
 *   getInstalledPlatforms[platform].build(buildOptions).
 *
 * @param   {String|String[]}  platform  Optional. If not specified, builds
 *   packages for all platforms, installed into project. If specified, could be
 *   either an array of platform names, which app packages should be built for,
 *   or single platform name.
 *
 * @param   {Object}  buildOptions  A build options. Possible options are:
 *   * release: Boolean. Indicates that packages should be built with release
 *   configuration. If not set to true, debug configuration will be used.
 *   * architectures: String[]. Specifies chip architectures which app
 *   packages should be built for.
 *   Note: List of valid architectures is specific for each platforms. Also
 *   not all platforms supports this option.
 *
 * @return {Promise} A promise either fulfilled if packages built
 *   successfully, or rejected with CordovaError.
 */
CordovaProject.prototype.build = function (platform, buildOptions) {};

/**
 * Builds and runs an application package for specified platform on specified
 *   device/emulator. If platform is specified, this acts as a shortcut for
 *   getInstalledPlatforms[platform].run(runOptions).
 *
 * @param   {String|String[]}  platform  Optional. If not specified, builds
 *   and runs packages for all platforms, installed into project. If specified,
 *   could be one of following:
 *   * String[]. An array of platform names, which app packages should be built/run for.
 *   * String. Equal to 'CordovaProject.run([platform])'.
 *
 * @param   {Object}  runOptions  Similar to build options. See build doc
 *   for options reference.
 *
 * @return {Promise} A promise either fulfilled if application ran
 *   successfully, or rejected with CordovaError.
 */
CordovaProject.prototype.run = function (platform, runOptions) {};

// TODO: Clean options?

/**
 * Cleans out the build artifacts for specified platform. If single platform is
 * specified, this acts as a shortcut for
 *   getInstalledPlatforms[platform].clean(cleanOptions).
 *
 * @param   {String|String[]}  platform  Optional. If not specified, builds
 *   and runs packages for all platforms, installed into project. If specified,
 *   could be one of following:
 *   * String[]. An array of platform names, which app packages should be built/run for.
 *   * String. Equal to 'CordovaProject.run([platform])'.
 *
 * @param   {Object}  runOptions  Similar to build options. See build doc
 *   for options reference.
 *
 * @return {Promise} A promise either fulfilled or rejected with CordovaError.
 */
CordovaProject.prototype.clean = function(platform, cleanOptions) {};

// TODO: requirementsOptions?

/**
 * Performs a requirements check for each platforms installed. Each platform
 *   defines its own set of requirements, which should be resolved before
 *   platform can be built successfully.
 *
 * @param   {String|String[]}  platform  Optional. If not specified, checks
 *   requirements for all platforms, installed into project. If specified,
 *   could be one of following:
 *   * String[]. An array of platform names, which app requirements should
 *   be checked for.
 *   * String. Equal to 'CordovaProject.requirements([platform])'.
 *
 * @param   {Object}  requirementsOptions  [description]
 *
 * @return  {Promise<Requirement[]>}  Promise resolved with set of
 *   Requirement objects for each platform.
 */
CordovaProject.prototype.requirements = function(platform, requirementsOptions) {};