Name: phonegap-plugin-contentsync
Owner: Natural History Museum
Description: Download and cache remotely hosted content
Forked from: phonegap/phonegap-plugin-contentsync
Created: 2016-12-09 11:10:11.0
Updated: 2016-12-09 11:10:12.0
Pushed: 2017-07-27 10:02:43.0
Size: 1234
Language: C
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
Download and cache remotely hosted zipped content bundles, unzipping automatically.
This requires phonegap 5.0+ ( current stable v1.2.0 )
egap plugin add phonegap-plugin-contentsync
It is also possible to install via repo url directly ( unstable )
egap plugin add https://github.com/phonegap/phonegap-plugin-contentsync
reate a new instance of ContentSync pointing to zipped resource 'movie-1.zip' - note
hat the url need not end in zip - it just needs to point to something producing
application/octet-stream mime type
sync = ContentSync.sync({
src: 'https://myserver/assets/movie-1.zip',
id: 'movie-1'
.on('progress', function(data) {
// data.progress
.on('complete', function(data) {
// data.localPath
.on('error', function(e) {
// e
.on('cancel', function() {
// triggered if event is cancelled
For updating a production app using ContentSync.sync
, always use HTTPS. Other Updaters have had vulnerabilities exposed when updating over insecure HTTP.
Parameter | Description
——— | ————
options.src
| String
URL to the remotely hosted content. For updates in production, this URL should always use HTTPS
options.id
| String
Unique identifer to reference the cached content.
options.type
| String
(Optional) Defines the copy strategy for the cached content.
The type replace
is the default behaviour that deletes the old content and caches the new content.
The type merge
will add the new content to the existing content. This will replace existing files, add new files, but never delete files.
The type local
returns the full path to the cached content if it exists or downloads it from options.src
if it doesn't. options.src
is not required if cached content actually exists.
options.headers
| Object
(Optional) Set of headers to use when requesting the remote content from options.src
.
options.copyCordovaAssets
| Boolean
(Optional) Copies cordova.js
, cordova_plugins.js
and plugins/
to sync'd folder. This operation happens after the source content has been cached, so it will override any existing Cordova assets. Default is false
.
options.copyRootApp
| Boolean
(Optional) Copies the www
folder to sync'd folder. This operation happens before the source content has been cached, then the source content is cached and finally it copies cordova.js
, cordova_plugins.js
and plugins/
to sync'd folder to remain consistent with the installed plugins. Default is false
.
options.timeout
| Double
(Optional) Request timeout. Default is 15 seconds.
options.trustHost
| Boolean
(Optional) Trust SSL host. Host defined in options.src
will be trusted. Ignored if options.src
is undefined.
options.manifest
| String
(Optional) If specified the copyRootApp
functionality will use the list of files contained in the manifest file during it's initial copy. {Android only}
options.validateSrc
| Boolean
(Optional) Whether to validate src url with a HEAD request before download (ios only, default true).
ContentSync
.sync = ContentSync.sync({
src: 'https://myserver/app/1',
id: 'app-1'
Parameter | Description
——— | ————
event
| String
Name of the event to listen to. See below for all the event names.
callback
| Function
is called when the event is triggered.
The event progress
will be triggered on each update as the native platform downloads and caches the content.
Callback Parameter | Description
—————— | ———–
data.progress
| Integer
Progress percentage between 0 - 100
. The progress includes all actions required to cache the remote content locally. This is different on each platform, but often includes requesting, downloading, and extracting the cached content along with any system cleanup tasks.
data.status
| Integer
Enumeration of PROGRESS_STATE
to describe the current progress state.
.on('progress', function(data) {
// data.progress
// data.status
The event complete
will be triggered when the content has been successfully cached onto the device.
Callback Parameter | Description
—————— | ———–
data.localPath
| String
The file path to the cached content. The file path will be different on each platform and may be relative or absolute. However, it is guaraneteed to be a compatible reference in the browser.
data.cached
| Boolean
Set to true
if options.type is set to local
and cached content exists. Set to false
otherwise.
.on('complete', function(data) {
// data.localPath
// data.cached
The event error
will trigger when an internal error occurs and the cache is aborted.
Callback Parameter | Description
—————— | ———–
e.type
| Integer
Enumeration of ERROR_STATE
to describe the current error
e.responseCode
| Integer
HTTP error code if available, -1
otherwise
.on('error', function(e) {
// e
The event cancel
will trigger when sync.cancel
is called.
Callback Parameter | Description
—————— | ———–
no parameters
|
.on('cancel', function() {
// user cancelled the sync operation
Cancels the content sync operation and triggers the cancel callback.
sync = ContentSync.sync({
src: 'https://myserver/app/1',
id: 'app-1'
.on('cancel', function() {
console.log('content sync was cancelled');
.cancel();
An enumeration that describes the current progress state. The mapped String
values can be customized for the user's app.
Integer | Description
——- | ———–
0
| STOPPED
1
| DOWNLOADING
2
| EXTRACTING
3
| COMPLETE
An enumeration that describes the received error. The mapped String
values can be customized for the user's app.
Error Code | Description
—————— | ———–
1
| INVALID_URL_ERR
2
| CONNECTION_ERR
3
| UNZIP_ERR
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.
unzip(<source zip>, <destination dir>, <callback>, [<progressCallback>]);
There is also an extra convenience method that can be used to download an archive
entSync.download(url, headers, cb)
The progress events described above also apply for these methods.
entSync.PROGRESS_STATE[1] = 'Downloading the media content...';
Use this API to load assets after extraction on cordova-ios > 4.x and cordova-plugin-wkwebview-engine. Do not use document.location
as it probably won't work. Make sure to prefix your url with file://
sync = ContentSync.sync({
src: 'https://myserver/app/1',
id: 'app-1'
.on('complete', function(data) {
ContentSync.loadUrl('file://' + data.localPath, function() {
console.log('success');
});
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.
sync = ContentSync.sync({
src: 'https://myserver/app/1',
id: 'app-1'
.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
path from the cordova-plugin-file
package. This is a change from previous versions so please be aware you may need to do a full sync after upgrading to version 1.2.0.
Platform | Path
—————— | ———–
Android | /data/data/<app-id>/files/<options.id>
iOS | /var/mobile/Applications/<UUID>/Library/NoCloud/<options.id>
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
folder you would invoke it via:
sync = ContentSync.sync({
src: 'https://myserver/app/1',
id: 'app-1',
copyRootApp: true,
manifest: 'manifest.json'
This results in the copyRootApp
taking about a third of the time as when a manifest file is not specified.
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.
id
parameter. This will allow the Content Sync plugin to lookup the file path at a later time using the id
parameter.cordova.js
, cordova_plugins.js
, and plugins/**/*
.test
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
// Then from the root of this repo
// test ios :
cordova-paramedic --platform ios --plugin .
// test android :
cordova-paramedic --platform android --plugin .
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.
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.
CMD+SHIFT+P
lint_on_load
and lint_on_save
to true