This PR is an updated version of #9 with addressed notes
The proposal describes the way how we can improve current cordova lib design and interaction between cordova lib and platforms. The document contains high-level descriptions of proposed interfaces only. For more details on methods signatures see *.js files in this pull request.
The most important points of this proposal are:
1. The PlatformApi class
PlatformApi (or CordovaPlatform) class - an abstraction around particular platform that exposes all the actions for this platform (such as build/run), so they're accessible programmatically. It also knows how to install/uninstall plugins with all source files, web assets and js files, so this is no more responsibility of cordova-lib. It also exposes single 'prepare' method to provide a way for cordova-lib to apply project's settings/www content to platform.
The PlatformApi class needs to be implemented by each platform, that wants to use new API flow. For those platforms, which doesn't provide own PlatformApi, there will be a polyfill in cordova-lib.
There is a PR to cordova-lib, which implements the polyfill: https://github.com/MSOpenTech/cordova-lib/pull/2
2. The ProjectAPI class
ProjectAPI (or CordovaProject) class - an abstraction of cordova project with multiple platforms/plugins installed. Manages the platforms and delegates the responsibilities to corresponding platform:
It also does some additional job:
You mention that the PlatformAPI will have a getPlatformInfo function that returns "the file structure and other properties". What exactly does this include? Does this include "the build output", and what notion is that? E.g. the iOS build output is a .app folder and maybe a plist file, while the windows build output is (a collection of) .appx or .appxbundle files?
The definition of this class is here (decided to rename
The location of build artifacts is intended to be returned as a result of
Yup - creating a new platform is not a common task.
However, integrating a platform in your workflow - gulp/grunt might be relevant for more people. It's un-validated use case and we might have issues with using the API that way. However, in theory these APIs might help with that. On those lines - maybe Api.js should be the index file of the package for the platform.
Though for the grunt/gulp story need some more thought- there are other options of using the cordova-lib api itself instead of cordova-android's platform API. There are probably pros and cons for each of these - we should come up with the guidance around this and blog about it eventually.