You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by er...@apache.org on 2020/03/31 15:22:57 UTC
[cordova-js] branch master updated: doc(README): update (#227)
This is an automated email from the ASF dual-hosted git repository.
erisu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-js.git
The following commit(s) were added to refs/heads/master by this push:
new c128d21 doc(README): update (#227)
c128d21 is described below
commit c128d21762800d3a3d9c2ce7d587a50b0486a2ce
Author: エリス <er...@users.noreply.github.com>
AuthorDate: Wed Apr 1 00:22:49 2020 +0900
doc(README): update (#227)
* doc(README): update
* doc(README): apply "Project Structure" suggestions from code review
* doc(README): apply "Adding a New Platform" suggestions from code review
* doc(README): apply "platform.js example" suggestion from code review
Co-Authored-By: Raphael von der Grün <ra...@gmail.com>
---
README.md | 201 +++++++++++++++++++++++++++++---------------------------------
1 file changed, 95 insertions(+), 106 deletions(-)
diff --git a/README.md b/README.md
index 8eac5c2..6b28d51 100644
--- a/README.md
+++ b/README.md
@@ -21,66 +21,85 @@
# cordova-js
+[](https://nodei.co/npm/cordova-js/)
+
[](https://github.com/apache/cordova-js/actions?query=branch%3Amaster)
A unified JavaScript layer for [Apache Cordova](http://cordova.apache.org/) projects.
## Project Structure
- ./
- |-src/
- | |-cordova.js ........ common Cordova stuff
- | |-common/ ........... base modules shared across platfoms
- | | |-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 ........ 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
- | |
- | |-scripts/ .......... non-module JS that gets concated to cordova.<platform>.js
- | | |-bootstrap.js ... bootstrap the Cordova platform, inject APIs and fire events
- | | '-require.js ..... module definition and require() impl
- | |
- | |-legacy-exec/ ...... contains old platform specific modules
- | | |-<platform>/ .... contains the platform-specific base modules
- |
- |-tasks/ ............... custom grunt tasks
- |-tests/ ............... unit tests
- |
- '-pkg/ ................. generated platform cordova.js files
+ ```text
+ ./
+ |-build-tools/ ......... custom bundler for our CommonJS-like modules
+ |-pkg/ ................. generated platform cordova.js files
+ |-src/
+ | |-cordova.js ........ common Cordova stuff
+ | |-common/ ........... base modules shared across platfoms
+ | | |-argscheck.js ... utility for type-checking arguments during runtime
+ | | |-base64.js ...... base64 utilites (toArrayBuffer & fromArrayBuffer)
+ | | |-builder.js ..... utilities to install a set of properties onto an object
+ | | |-channel.js ..... pub/sub implementation for custom framework events
+ | | |-init.js ........ bootstraps the Cordova platform, inject APIs and fire events
+ | | |-utils.js ....... closures, uuids, object, cloning, extending prototypes
+ | | |
+ | | |-exec/ .......... exec methods
+ | | | '-proxy.js .... utility for adding and removing exec proxy methods
+ | |
+ | |-scripts/ .......... non-module JS that gets concatenated to cordova.<platform>.js
+ | | |-bootstrap.js ... bootstrap the Cordova platform, inject APIs and fire events
+ | | '-require.js ..... module definition and require() implementation
+ |
+ '-tests/ ............... unit tests
+ ```
+
+## Setup for Building
+
+* Make sure you have [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed.
+
+ `npm` should come pre-installed with `Node.js`. If `Node.js` installed but can not run `npm`, please follow the npm doc: [Downloading and installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
+
+* Install all the node dependencies by running the following command from the repository root:
+
+ ```bash
+ npm install
+ ```
## 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:
-
- npm install
-
-The build script assumes that users have cordova-platforms as siblings to this `cordova-js` directory. When generating `cordova.js`, `grunt compile` will grab platform specific files from these directories if they exist. The default locations are defined in `package.json`.
+The build script assumes that users have the cordova-platforms checked out as siblings to this `cordova-js` directory. When generating `cordova.js`, `npm run build` will grab platform specific files from these directories if they exist.
Then from the repository root run:
- npm run build
+ ```bash
+ npm run build
+ ```
To compile the js for just one platform, run:
- npx grunt compile:android --platformVersion=4.0.0
+ ```bash
+ npx grunt compile:android --platformVersion=4.0.0
+ ```
To compile the js for all platforms but pass in a custom path for your cordova-android and cordova-ios platforms, run:
- npx grunt compile --android='../custompath/cordova-android' --ios='../custompath/cordova-ios'
+ ```bash
+ npm run build -- --android='../custompath/cordova-android' --ios='../custompath/cordova-ios'
+ ```
For integration, see the 'Integration' section below.
## 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.
+The `build-tools/build.js` process 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 `src/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 `src/scripts/bootstrap.js`. This file attaches the `boot` function to the `channel.onNativeReady` event - fired by native with a call to:
- cordova.require('cordova/channel').onNativeReady.fire()
+ ```js
+ cordova.require('cordova/channel').onNativeReady.fire()
+ ```
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 initialize [...]
@@ -88,7 +107,9 @@ The `boot` method does all the work. First, it grabs the common platform defini
Tests run in a bundled headless Chromium instance. They can be run with:
- npm test
+ ```bash
+ npm test
+ ```
Final testing should always be done with the [Mobile Spec test application](https://github.com/apache/cordova-mobile-spec).
@@ -104,77 +125,45 @@ Once the new js file has been added, any new projects created will use the updat
## 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
- call it `exec.js`. The `exec` method is a JavaScript function
- that enables communication from the platform's JavaScript environment
- into the platform's native environment. Each platform uses a different
- mechanism to enable this bridge. We recommend you check out the other
- platform `exec` definitions for inspiration. Drop this into the
- `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
- 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:
- - `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 `path` and
- `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:
-
- <pre>
- {
- id:"atari",
- initialize:function(){
- console.log('firing up Cordova in my Atari, yo.');
- },
- objects:{
- cordova:{
- path:"cordova",
- children:{
- joystick:{
- path:"cordova/plugin/atari/joystick"
- }
- }
+### In Your Platform Repository
+
+1. Create the `cordova-js-src` directory.
+
+2. Write a module that encapsulates your platform's `exec` method and call it `exec.js`. This file should be added into the `<platform-repo>/cordova-js-src` directory which was created from step 1.
+
+ The `exec` method is a JavaScript function that enables communication from the platform's JavaScript environment into the platform's native environment. Each platform uses a different mechanism to enable this bridge. We recommend you check out the other platform `exec` definitions for inspiration.
+
+ The `exec` method has the following method signature: `function(success, fail, service, action, args)`
+
+ **Methods Arguments:**
+
+ * `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.
+
+3. Define your platform definition object and name it `platform.js`. This file should be added into the `<platform-repo>/cordova-js-src` directory which was created from step 1.
+
+ This file should export an object with the following properties:
+
+ * `id`: a string representing the platform. This should match the name of the `.js` file.
+ * `bootstrap`: A function that sets up the platform. Must fire the `onNativeReady` channel when done.
+ * `initialize`: an optional function that is called after the global scope setup is done (i.e. Cordova and all plugins are ready)
+
+ The following is a simple example of a platform definition:
+
+ ```js
+ module.exports = {
+ id: 'atari',
+ bootstrap: function() {
+ require('cordova/channel').onNativeReady.fire();
}
- }
- }
- </pre>
-
-3. You should probably add a `<platform>:{}` entry to the `Gruntfile` compile arrays.
-4. Make sure your native implementation executes the following JavaScript once all of the native side is initialized and ready: `require('cordova/channel').onNativeReady.fire()`.
-5. The `deviceready` event is important. To make sure that the stock
- common JavaScript fires this event off, the device and network
- connection plugins must successfully be instantiated and return
- information about the connectivity and device information. The
- success callbacks for these plugins should include calls to
- `require('cordova/channel').onCordovaInfoReady.fire()` (for device
- information) and
- `require('cordova/channel').OnCordovaConnectionReady.fire()` (for
- network information).
-6. 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!
+ };
+ ```
+
+### In `cordova-js` Repository
+
+1. Add a `<platform>: {}` entry to the `Gruntfile.js` `compile` arrays.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org