Platform API reference

PlatformApi.md

PlatformApi()

Class, that acts as abstraction over particular platform. Encapsulates the platform's properties and methods.

Platform that implements own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.

The PlatformApi instance also should define the following field:

• platform: String that defines a platform name.

Kind: global function

• PlatformApi()
  • instance
    • .prepare(projectInfo) ⇒ Promise
    • .addPlugin(plugin, installOptions) ⇒ Promise
    • .removePlugin(pluginId) ⇒ Promise
    • .build(buildOptions) ⇒ Promise.<Array.<String>>
    • .run(runOptions) ⇒ Promise
    • .clean() ⇒ Promise
    • .requirements() ⇒ Promise.<Array.<Requirement>>
  • static
    • .createPlatform(projectInfo, options) ⇒ Promise.<PlatformApi>
    • .getPlatformInfo() ⇒ PlatformInfo

platformApi.prepare(projectInfo) ⇒ Promise

Updates installed platform with provided www assets and new app configuration. This method is required for CLI workflow and will be called each time before build, so the changes, made to app configuration and www code, will be applied to platform.

Kind: instance method of PlatformApi
Returns: Promise - Return a promise either fulfilled, or rejected with CordovaError instance.

Param	Type	Description
projectInfo	ProjectInfo	A ProjectInfo instance, that defines a project structure and configuration, that should be applied to platform (contains project's www location and ConfigParser instance for project's config).

platformApi.addPlugin(plugin, installOptions) ⇒ Promise

Installs a new plugin into platform. This method only copies non-www files (sources, libs, etc.) to platform. It also doesn't resolves the dependencies of plugin. Both of handling of www files, such as assets and js-files and resolving dependencies are the responsibility of caller.

Kind: instance method of PlatformApi
Returns: Promise - Return a promise either fulfilled, or rejected with CordovaError instance.

Param	Type	Description
plugin	PluginInfo	A PluginInfo instance that represents plugin that will be installed.
installOptions	Object	An options object. Possible options below:
installOptions.link:	Boolean	Flag that specifies that plugin sources will be symlinked to app's directory instead of copying (if possible).
installOptions.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

platformApi.removePlugin(pluginId) ⇒ Promise

Removes an installed plugin from platform.

Kind: instance method of PlatformApi
Returns: Promise - Return a promise either fulfilled, or rejected with CordovaError instance.

Param	Type	Description
pluginId	String	An id of plugin that should be removed from platform.

platformApi.build(buildOptions) ⇒ Promise.<Array.<String>>

Builds an application package for current platform.

Kind: instance method of PlatformApi
Returns: Promise.<Array.<String>> - A promise either fulfilled with an array of build artifacts (application packages) paths if package was built successfully, or rejected with CordovaError.

The return value in most cases will contain only one item but in some cases there could be multiple items in output array, e.g. when multiple arhcitectures is specified.

Param	Type	Description
buildOptions	Object	A build options. This object's structure is highly depends on platform's specific. The most common options are:
buildOptions.debug	Boolean	Indicates that packages should be built with debug configuration. This is set to true by default unless the 'release' option is not specified.
buildOptions.release	Boolean	Indicates that packages should be built with release configuration. If not set to true, debug configuration will be used.
buildOptions.device	Boolean	Specifies that built app is intended to run on device
buildOptions.emulator:	Boolean	Specifies that built app is intended to run on emulator
buildOptions.target	String	Specifies the device id that will be used to run built application.
buildOptions.nobuild	Boolean	Indicates that this should be a dry-run call, so no build artifacts will be produced.
buildOptions.archs	Array.<String>	Specifies chip architectures which app packages should be built for. List of valid architectures is depends on platform.
buildOptions.buildConfig	String	The path to build configuration file. The format of this file is depends on platform.
buildOptions.argv	Array.<String>	Raw array of command-line arguments, passed to build command. The purpose of this property is to pass a platform-specific arguments, and eventually let platform define own arguments processing logic.

platformApi.run(runOptions) ⇒ Promise

Builds an application package for current platform and runs it on specified/default device. If no 'device'/'emulator'/'target' options are specified, then tries to run app on default device if connected, otherwise runs the app on emulator.

Kind: instance method of PlatformApi
Returns: Promise - A promise either fulfilled if package was built and ran successfully, or rejected with CordovaError.

Param	Type	Description
runOptions	Object	An options object. The structure is the same as for build options.

platformApi.clean() ⇒ Promise

Cleans out the build artifacts from platform's directory.

Kind: instance method of PlatformApi
Returns: Promise - Return a promise either fulfilled, or rejected with CordovaError.

platformApi.requirements() ⇒ Promise.<Array.<Requirement>>

Performs a requirements check for current platform. Each platform defines its own set of requirements, which should be resolved before platform can be built successfully.

Kind: instance method of PlatformApi
Returns: Promise.<Array.<Requirement>> - Promise, resolved with set of Requirement objects for current platform.

PlatformApi.createPlatform(projectInfo, options) ⇒ Promise.<PlatformApi>

Installs platform to specified directory and creates a platform project.

Kind: static method of PlatformApi
Returns: Promise.<PlatformApi> - Promise either fulfilled with PlatformApi instance or rejected with CordovaError.

Param	Type	Description
projectInfo	ProjectInfo	A ProjectInfo instance, that defines a project structure and configuration, that should be applied to new platform (contains platform's target location and ConfigParser instance for project's config). This argument is optional and if not defined, this means that platform is used as standalone project and is not a part of cordova project.
options	Object	An options object. The most common options are:
options.customTemplate	String	A path to custom template, that should override the default one from platform.
options.link	Boolean	Flag that indicates that platform's sources will be linked to installed platform instead of copying.

PlatformApi.getPlatformInfo() ⇒ PlatformInfo

Gets a PlatformInfo object, that represents the platform structure.

Kind: static method of PlatformApi
Returns: PlatformInfo - A structure that contains the description of platform's file structure and other 'static' properties of platform.

Some notes/additional thoughts on this doc:

• Some of methods that requres www directory and/or config.xml/ConfigParser as an input parameters (e.g installPlatform(), prepare()) could be changed to accept more general parameter/class, that describes project structure (proposed name platformMetadata). The pros of this approach that set of input parameters could be easily changed in future, if we'll hame more parameters to describe project/platform state.
• The methods that accepts an arbitrary options object with set of common/recommended parameters (build(), run(), etc.) might be updated to accept a strictly-typed *Options objects (such as BuildOptions, InstallOptions). But passing a simple raw object to these methods might be easier to use.
• All the API methods uses the the same CordovaError class to report an errors through rejecting promises/throwing. To make exception handling more accurate in high-level API we may want to have a number of different error classes, or introduce an CordovaError.code field and a set of corresponding constants, such as CordovaError.PLATFORM_API_NOT_IMPLEMENTED_ERROR, CordovaError.PLATFORM_API_ARGUMENT_ERROR...