bin/create scripts
"main": "src/cordova/Api.js"
PlatformApi
with methods as you define later.The PlatformApi class
PlatformApi
class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.prepare
method to provide a way for cordova-lib to apply a project‘s setting/www content to the platform. It interpolates metadata, such as application name or description from a Cordova
project’s config.xml into the format expected by the platform. See config.xml documentation.PlatformApi
instance must implement all prototype methods of this class to be fully compatible with cordova-lib
.create
, requirements
, prepare
, addPlugin
, and removePlugin
build
, run
PlatformApi
instance should define the following field:Api.js must export a static function createPlatform(destination, cfg, options, events);
that returns a new instance of the PlatformApi
.
PlatformApi.createPlatform = function(cordovaProject, options) {};
.createPlatform
: is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject
instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
cordovaProject : This is a CordovaProject
instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova
project. See CordovaProject documentation.
options : This is an options object. The most common options are :
create
should copy from there instead of it's own template. Example:var project_template_dir = options.customTemplate || path.join(ROOT, 'bin', 'templates', 'project'); // copy project template shell.cp('-r', path.join(project_template_dir, 'assets'), project_path); shell.cp('-r', path.join(project_template_dir, 'res'), project_path);
Cordova
platform..createPlatform
must return a promise, which is either fulfilled with a PlatformApi
instance or rejected with a CordovaError
.
The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
A call to the platforms static Api.createPlatform will:
Api.js exports a constructor function This is NOT a requirement. All instances of the platform api are typically created and returned by the createPlatform function. The newly created platform (which copies code from the template to the project dir) must export a constructor.
var Api = require('path/Api.js'); var api = new Api();
These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
.requirements
: should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.cordova-android
platform requires tooling from the Android SDK, and uses this method to check that the operating system has access to all necessary tooling..requirements
must return a promise, resolved with a set of Requirement
objects for the current platform..clean
should clean out the build artifacts from the platform's directory..clean
must return a promise either fulfilled or rejected with a CordovaError
..build
should build an application package for the current platform.
buildOptions : an options object. The most common options are:
build
command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic..build
must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError
. The return value in most cases will contain only one item, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.{ architecture: 'x86', buildType: 'debug', path: '/path/to/build', type: 'app' }
.run
should build an application package for the current platform and runs it on the specified/default device. If no ‘device’/‘emulator’/‘target’ options are specified, then it should try to launch the app on a default device if connected, otherwise it should launch on the app on the emulator..run
must return a promise either fulfilled if the package was build and ran successfully, or rejected with a CordovaError
..addPlugin
should install a plugin into a platform. It should handle all the non-www files shipped by plugin (sources, libs, assets, js-files) and accept a PluginInfo
instance that represents the plugin that will be installed and an options object. It cannot resolve the dependencies of a plugin.PluginInfo
instance that should represent the plugin that will be installed. See PluginInfo documentation.It is expected to accept a plugin spec that should be one of the 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 : cordova-plugin-globalization@1.0.0 - git url, that points to a repo with a valid plugin: http://github.com/apache/cordova-plugin-globalization.git#r.1.0.0 - path to local repo of valid plugin: /my/cordova/repositories/cordova-plugin-globalization
.addPlugin
must return a promise either fulfilled or rejected with a CordovaError
instance..removePlugin
should remove an installed plugin from a platform. It should accept a PluginInfo
instance that represents the plugin that will be removed and an options object.PluginInfo
instance as an input parameter, instead of a plugin id, the caller should take care of managing and storing the PluginInfo
instances for future uninstalls.PluginInfo
instance that should represent the plugin that will be uninstalled. See PluginInfo documentation. It is expected to accept a plugin spec that should be one of the following:.removePlugin
must return a promise either fulfilled or rejected with a CordovaError
instance..prepare
should update the installed platform with provided www assets and new app configuration. This method is required for CLI work flow and should be called each time before build, so the changes, made to app configuration and www code, will be applied to the platform..prepare
doesn‘t rebuild the cordova_plugins file and doesn’t reapply assets and js files installed by plugins to the platform's www directory.CordovaProject
instance, that defines a project structure and configuration, that should be applied to the platform. See CordovaProject documentation. (It contains the project‘s www location and ConfigParser
instance for the project’s config.).prepare
must return a promise either fulfilled, or rejected with a CordovaError
instance..getPlatformInfo
should get a CordovaPlatform
object that represents the platform structure. (Platform's directories/main file locations such as config.xml, www, etc.).getPlatformInfo
must return a CordovaPlatform
object that contains the description of the platform's file structure and other properties of the platform.