phonegap-plugin-contentsync

Download and cache remotely hosted zipped content bundles, unzipping automatically.

Installation

This requires phonegap 5.0+ ( current stable v1.2.0 )

phonegap plugin add phonegap-plugin-contentsync

It is also possible to install via repo url directly ( unstable )

phonegap plugin add https://github.com/phonegap/phonegap-plugin-contentsync

Supported Platforms

• Android
• iOS
• WP8

Quick Example

// Create a new instance of ContentSync pointing to zipped resource 'movie-1.zip' - note
// that the url need not end in zip - it just needs to point to something producing
// a application/octet-stream mime type
var sync = ContentSync.sync({
        src: 'https://myserver/assets/movie-1.zip',
        id: 'movie-1'
});

sync.on('progress', function(data) {
    // data.progress
});
sync.on('complete', function(data) {
    // data.localPath
});
sync.on('error', function(e) {
    // e
});
sync.on('cancel', function() {
    // triggered if event is cancelled
});

Security note:

For updating a production app using

ContentSync.sync

API

ContentSync.sync(options)

options.src

String

options.id

String

options.type

String

replace

merge

local

options.src

options.src

options.headers

Object

options.src

options.copyCordovaAssets

Boolean

cordova.js

cordova_plugins.js

plugins/

false

options.copyRootApp

Boolean

www

cordova.js

cordova_plugins.js

plugins/

false

options.timeout

Double

options.trustHost

Boolean

options.src

options.src

options.manifest

String

copyRootApp

options.validateSrc

Boolean

Returns

• Instance of

  ContentSync

  .

Example

var sync = ContentSync.sync({
        src: 'https://myserver/app/1',
        id: 'app-1'
});

sync.on(event, callback)

event

String

callback

Function

sync.on('progress', callback)

The event

progress

data.progress

Integer

0 - 100

data.status

Integer

PROGRESS_STATE

Example

sync.on('progress', function(data) {
    // data.progress
    // data.status
});

sync.on('complete', callback)

The event

complete

data.localPath

String

data.cached

Boolean

true

local

false

Example

sync.on('complete', function(data) {
    // data.localPath
    // data.cached
});

sync.on('error', callback)

The event

error

e.type

Integer

ERROR_STATE

e.responseCode

Integer

-1

Example

sync.on('error', function(e) {
    // e
});

sync.on('cancel', callback)

The event

cancel

sync.cancel

no parameters

Example

sync.on('cancel', function() {
    // user cancelled the sync operation
});

sync.cancel()

Cancels the content sync operation and triggers the cancel callback.

var sync = ContentSync.sync({
        src: 'https://myserver/app/1',
        id: 'app-1'
});

sync.on('cancel', function() {
    console.log('content sync was cancelled');
});
sync.cancel();

ContentSync.PROGRESS_STATE

An enumeration that describes the current progress state. The mapped

String

0

STOPPED

1

DOWNLOADING

2

EXTRACTING

3

COMPLETE

ContentSync.ERROR_STATE

An enumeration that describes the received error. The mapped

String

1

INVALID_URL_ERR

2

CONNECTION_ERR

3

UNZIP_ERR

ContentSync.unzip || Zip.unzip - ContentSync.download

If you are using the Chromium Zip plugin this plugin won't work for you on iOS. However, it supports the same interface so you don't have to install both.

zip.unzip(, , , []);

There is also an extra convenience method that can be used to download an archive

ContentSync.download(url, headers, cb)

The progress events described above also apply for these methods.

Example

ContentSync.PROGRESS_STATE[1] = 'Downloading the media content...';

ContentSync.loadUrl (cordova-ios > 4.x with cordova-plugin-wkwebview-engine)

Use this API to load assets after extraction on cordova-ios > 4.x and cordova-plugin-wkwebview-engine. Do not use

document.location

file://

var sync = ContentSync.sync({
        src: 'https://myserver/app/1',
        id: 'app-1'
});

sync.on('complete', function(data) {
    ContentSync.loadUrl('file://' + data.localPath, function() {
        console.log('success');
    });
});

Working with the Native File System

One of the main benefits of the content sync plugin is that it does not depend on the File or FileTransfer plugins. As a result the end user should not care where the ContentSync plugin stores it's files as long as it fills the requirements that it is private and removed when it's associated app is uninstalled.

However, if you do need to use the File plugin to navigate the data downloaded by ContentSync you can use the following code snippet to get a DirectoryEntry for the synced content.

var sync = ContentSync.sync({
        src: 'https://myserver/app/1',
        id: 'app-1'
});

sync.on('complete', function(data) {
    window.resolveLocalFileSystemURL("file://" + data.localPath, function(entry) {
        // entry is a DirectoryEntry object
    }, function(error) {
        console.log("Error: " + error.code);
    });
});

As of version 1.2.0 of the plugin the location in which the plugin stores the synched content is equivaltent to the

cordova.file.dataDirectory

cordova-plugin-file

/data/data//files/

/var/mobile/Applications//Library/NoCloud/

Copy Root App

The asset file system is pretty slow on Android so in order to speed up the initial copy of your app to the content sync location you can specify a manifest file on Android. The file must be in the format:

{
    'files': [
        'img/logo.png',
        'index.html',
        'js/index.js'
   ]
}

and if the file is placed in your apps

www

var sync = ContentSync.sync({
        src: 'https://myserver/app/1',
        id: 'app-1',
        copyRootApp: true,
        manifest: 'manifest.json'
});

This results in the

copyRootApp

Persistence of Synced Content

Content downloaded via this plugin persists between runs of the application or reboots of the phone. The content will only be removed if the application is uninstalled or you use the File API to remove the location of the synched content.

Native Requirements

• There should be no dependency on the existing File or FileTransfer plugins.
• The native cached file path should be uniquely identifiable with the

  id

  parameter. This will allow the Content Sync plugin to lookup the file path at a later time using the

  id

  parameter.
• The first version of the plugin assumes that all cached content is downloaded as a compressed ZIP. The native implementation must properly extract content and clean up any temporary files, such as the downloaded zip.
• The locally compiled Cordova web assets should be copied to the cached content. This includes

  cordova.js

  ,

  cordova_plugins.js

  , and

  plugins/**/*

  .
• Multiple syncs should be supported at the same time.

Running Tests ( static tests against source code )

npm test

Emulator Testing

The emulator tests use cordova-paramedic and the cordova-plugin-test-framework. To run them you will need cordova-paramedic installed:

npm install -g cordova-paramedic

Some of the tests require a simple HTTP server to host .zip payloads:

./tests/scripts/start-server.sh

Run the tests:

// From the root of this repo
// test ios :
cordova-paramedic --platform ios --plugin .

// test android :
cordova-paramedic --platform android --plugin .

Once complete, the simple HTTP server can be stopped:

./tests/scripts/stop-server.sh

Contributing

Editor Config

The project uses .editorconfig to define the coding style of each file. We recommend that you install the Editor Config extension for your preferred IDE.

JSHint

The project uses .jshint to define the JavaScript coding conventions. Most editors now have a JSHint add-on to provide on-save or on-edit linting.

Install JSHint for vim

1. Install jshint.
2. Install jshint.vim.

Install JSHint for Sublime

1. Install Package Control
2. Restart Sublime
3. Type

   CMD+SHIFT+P

4. Type Install Package
5. Type JSHint Gutter
6. Sublime -> Preferences -> Package Settings -> JSHint Gutter
7. Set

   lint_on_load

   and

   lint_on_save

   to

   true