Have Cordova run the latest version of your HTML5 app.
JavaScript Shell HTML CSS
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
build
src
.gitignore
.jshintrc
README.md
build.sh
license.txt
package.json

README.md

Cordova Loader

Load the latest version of your HTML5 app.

Host your HTML5 app resources on the web. The latest version of each file will run on launch. When offline, the most recently downloaded version runs.

Caveat: tests are run on iOS only; we don’t work on issues affecting non-iOS devices. The command line tool is Mac/Unix/Linux only.

It’s quite easy.

(1) Host your app, and create a manifest.

Put app resources on the web, and create manifest.json. It’s a simple array, and order doesn’t matter. An 'index.html' file is required.

[
  {
    "url": "http://srvr.io/app/index.html",   // Remote location
    "uri": "index.html",                      // Root-relative location
    "version": "1.0.1"                        // Stamp, semver, or int
  },
  {
    "url": "http://srvr.io/app/js/main.js",
    "uri": "js/main.js",
    "version": "1.0.3"
  },
  {
    "url": "http://srvr.io/app/style.css",
    "uri": "style.css",
    "version": "1.0.1"
  },
  // ...
]

(2) Create a Cordova “wrapper” app.

  1. Create a new project and add the File plugin: cordova plugin add cordova-plugin-file.
  2. Put cdvLoader.js and index.html (example below) in /www.
<!-- Don't add JS, CSS, or HTML here; Cordova Loader will read the index.html
file given in manifest.json, and inject the includes and <body> markup. -->
<html>
<head>
<script src="cordova.js"></script>
<script src="cdvLoader.js" data-manifest="http://srvr.io/app/manifest.json"></script>
</head>
<body></body>
</html>

(3) Listen for the cdvLoaderReady event.

Cordova's deviceready event is no longer of interest to your HTML5 app, since your app's files haven't been injected into the DOM on deviceready. Instead, you'll await cdvLoaderReady, which fires after your app's files are ready to roll.

document.addEventListener('cdvLoaderReady', function () {
  // Run your app.
})

Now you can:

Add, update, and remove files.

  • To add: upload the file and add an entry to the manifest.
  • To update: upload an updated file and change its version in manifest.json.
  • To remove: remove an entry from the manifest.

Access the files.

Use ajax to get files from cdvLoader.root + 'the/file/uri/'. This provides a tidy solution for dynamically getting and loading template files, and can be used to set src and href attributes. Client apps can also use Apache's cdvfile scheme to define src and href attributes in raw HTML (cdvfile://the/file/uri).

Use the event system.

Client apps can use Cordova Loader's application state events to gracefully react to inevitable server troubles:

  1. cdvLoaderCheckingForUpdate
  2. cdvLoaderManifestDownloaded
  3. cdvLoaderUpdating
  4. cdvLoaderUpdateError
  5. cdvLoaderUpdateAborted
  6. cdvLoaderReady

Manage the update-in-progress view.

When the cdvLoaderUpdating event fires, the HTML5 app hasn’t been run yet, so managing the update view can’t be done from within the HTML5 app itself. For that reason, you can add an object of the following form to the manifest:

{
  "role": "updateController",
  "url": "https://server.io/app/js/updating.js",
  "uri": "updating.js",
  "version": "1.0.5"
}

Update Cordova Loader itself.

Host cdvLoader.js and add an object of the following form to manifest.json:

{
  "url": "https://server.io/app/cdvLoader.min.js",
  "uri": "cdvLoader.js",
  "version": "0.1.3"
}

Generate your manifest.

If your project is huge, use the (bare bones) command line tool to generate your manifest. You can use -gen <source dir> <root url> to add all files in the source directory to the manifest, with the root url added to each. For example:

build/cli -gen ../project-root/build-dir/ http://server.io/app-files/

The manifest.json file will be saved in the source directory.

Tests

Run npm run test to trigger both unit and integration tests; you must have node, cordova and ios-sim installed. Integration results will display in your terminal window, and your default browser will launch to run the unit tests. This will take around 2 minutes to complete, even on a very fast machine.

For detailed information on the testing approach and process, see /src/tests/.