The way the resulting
cordova.<platform>.js files will be built is by combining the scripts in the
lib/scripts directory with modules from the
lib/<platform> directories. For cases where there is the same named module in
lib/<platform> version wins. For instance, every
lib/<platform> includes an
exec.js, and there is also a version in
lib/common, so the
lib/<platform> version will always be used. In fact, the
lib/common one will throw errors, so if you build a new platform and forget
exec.js, the resulting
cordova.<platform>.js file will also throw errors.
Make sure you have node.js installed. It should come pre-installed with npm - but if you install node and can't run
npm then head over to the website and install it yourself. Make sure you have all of the node dependencies installed by running the following command from the repository root:
All of the build tasks can be run via the
grunt node module. Install it globally first by running:
sudo npm install -g grunt-cli
Then from the repository root run:
This will run the
test tasks by default. All of the available tasks are:
build: creates platform versions of cordova-js and builds them into the
test: runs all of the unit tests inside node
btest: creates a server so you can run the tests inside a browser
clean: cleans out the
hint: runs all of the script files through JSHint
fixwhitespace: converts all tabs to four spaces, removes carriage returns and cuts out trailing whitespace within the script files
npm install. Using node v0.6.6 works, though.
npm install, you may get errors regarding contextify. This is necessary for running the tests. Make sure you are running node v0.6.15 at the least (and npm v1.1.16 which should come bundled with node 0.6.15). Also, install Python 2.7.x and Visual C++ 2010 Express. When that is done, run
npm install again and it should build contextify natively on Windows.
build/packager.js tool is a node.js script that concatenates all of the core Cordova plugins in this repository into a
cordova.<platform>.js file under the
pkg/ folder. It also wraps the plugins with a RequireJS-compatible module syntax that works in both browser and node environments. We end up with a cordova.js file that wraps each Cordova plugin into its own module.
Cordova defines a
channel module under
lib/common/channel.js, which is a publish/subscribe implementation that the project uses for event management.
The Cordova native-to-webview bridge is initialized in
lib/scripts/bootstrap.js. This file attaches the
boot function to the
channel.onNativeReady event - fired by native with a call to:
boot method does all the work. First, it grabs the common platform definition (under
lib/common/common.js) and injects all of the objects defined there onto
window and other global namespaces. Next, it grabs all of the platform-specific object definitions (as defined under
lib/<platform>/platform.js) and overrides those onto
window. Finally, it calls the platform-specific
initialize function (located in the platform definition). At this point, Cordova is fully initialized and ready to roll. Last thing we do is wait for the
DOMContentLoaded event to fire to make sure the page has loaded properly. Once that is done, Cordova fires the
deviceready event where you can safely attach functions that consume the Cordova APIs.
Tests run in node or the browser. To run the tests in node:
To run them in the browser:
Final testing should always be done with the Mobile Spec test application.
Build the .js file and drop it in as a replacement for cordova.js.
exec method and call it exec.js. The
exec definitions for inspiration. Drop this into the
lib/<platform> folder you created in step 1. The
exec method has the following method signature:
function(success, fail, service, action, args), with the following parameters:
success: a success function callback
fail: a failure function callback
service: a string identifier that the platform can resolve to a native class
action: a string identifier that the platform can resolve to a specific method inside the class pointed to by
args: an array of parameters to pass to the native method invoked by the
exec call It is required that new platform additions be as consistent as possible with the existing
Define your platform definition object and name it platform.js. Drop this into the
lib/<platform> folder. This file should contain a JSON object with the following properties:
id: a string representing the platform. This should be the same name the .js file has
objects: the property names defined as children of this property are injected into
window, and also overrides any existing properties. Each property can have the following child properties:
path: a string representing the module ID that will define this object. For example, the file
lib/plugin/accelerometer.js can be accessed as
"cordova/plugin/accelerometer". More details on how the module IDs are defined are above under the “How It Works” section.
children: in a recursive fashion, can have
children properties of its own that are defined as children of the parent property object
merges: similar to the above
objects property, this one will not clobber existing objects, instead it will recursively merge this object into the specific target
initialize: a function that fires immediately after the
objects (see above) are defined in the global scope
The following is a simple example of a platform definition:
You should probably add a
packager.bundle('<platform>') call to the
Jakefile under the
require('cordova/channel').onCordovaInfoReady.fire() (for device information) and
require('cordova/channel').OnCordovaConnectionReady.fire() (for network information).
Last but certainly not least: add yourself to the contributors list! It's in the
package.json file in the root of this repository. You deserve it!