Skip to content
Permalink
Browse files
Improve README (#201)
- add title
- fix headline levels
- fix typo
- fix indentation
  • Loading branch information
janpio committed May 4, 2019
1 parent f0dfd36 commit 5544ab0a616c1c72ae217c85bcf5e358abad30df
Showing 1 changed file with 18 additions and 18 deletions.
@@ -19,13 +19,13 @@
#
-->

[![Build Status](https://travis-ci.org/apache/cordova-js.svg?branch=master)](https://travis-ci.org/apache/cordova-js)
# cordova-js

[![Build status](https://ci.appveyor.com/api/projects/status/github/apache/cordova-js?branch=master&svg=true)](https://ci.appveyor.com/project/Humbedooh/cordova-js/branch/master)
[![Build Status](https://travis-ci.org/apache/cordova-js.svg?branch=master)](https://travis-ci.org/apache/cordova-js) [![Build status](https://ci.appveyor.com/api/projects/status/github/apache/cordova-js?branch=master&svg=true)](https://ci.appveyor.com/project/Humbedooh/cordova-js/branch/master)

A unified JavaScript layer for [Apache Cordova](http://cordova.apache.org/) projects.

# Project Structure
## Project Structure

./
|-src/
@@ -34,7 +34,7 @@ A unified JavaScript layer for [Apache Cordova](http://cordova.apache.org/) proj
| | |-builder.js ..... injects in our classes onto window and navigator
| | |-channel.js ..... pub/sub impl for custom framework events
| | |-init.js ........ common locations to add Cordova objects to browser globals
| | |-exec.js ........ interace stub for each platform specific version of exec.js
| | |-exec.js ........ interface stub for each platform specific version of exec.js
| | |-platform.js .... stub for platform's specific version of platform.js
| | '-utils.js ....... closures, uuids, object, cloning, extending prototypes
| |
@@ -50,7 +50,7 @@ A unified JavaScript layer for [Apache Cordova](http://cordova.apache.org/) proj
|
'-pkg/ ................. generated platform cordova.js files

# Building
## Building

Make sure you have [node.js](http://nodejs.org) installed. It should come pre-installed with [npm](http://npmjs.org) - 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:

@@ -72,7 +72,7 @@ To compile the js for all platforms but pass in a custom path for your cordova-a

For integration, see the 'Integration' section below.

# How It Works
## How It Works

The `tasks/lib/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.

@@ -84,25 +84,25 @@ The **Cordova** *native-to-webview* bridge is initialized in `src/scripts/bootst

The `boot` method does all the work. First, it grabs the common platform definition (under `src/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 `src/<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.

# Testing
## Testing

Tests run in a bundled headless Chromium instance. They can be run with:

npm test

Final testing should always be done with the [Mobile Spec test application](https://github.com/apache/cordova-mobile-spec).

# Integration
## Integration

## Cordova
### Cordova

Build the js files by running **grunt** as described above. Update each platform independently. For a given platform:

Replace the `cordova.js` file in the cordova <platform>platform_www/cordova.js directory with the newly generated `cordova.js` file. If necessary, change the name of the new file to match that of the overwritten one.

Once the new js file has been added, any new projects created will use the updated js. To update an already existing project, directly replace the cordova.js file within the project's `www/` folder with the generated `cordova.PLATFORM.js`. Make sure to change the file name to match the original.

# Adding a New Platform
## Adding a New Platform

1. Add your platform as a directory under the `legacy-exec` folder.
2. Write a module that encapsulates your platform's `exec` method and
@@ -114,14 +114,14 @@ Once the new js file has been added, any new projects created will use the updat
`src/legacy-exec/<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 `service`
- `args`: an array of parameters to pass to the native method invoked
by the `exec` call
- `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 `service`
- `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 `service` and `action` labels.
2. Define your platform definition object and name it `platform.js`. Drop this into the `src/legacy-exec/<platform>` folder. This file should contain a **JSON** object with the following properties:

0 comments on commit 5544ab0

Please sign in to comment.