Tatsujinichi / phonegap-plugin-wizAssets

PhoneGap plugin for managing application assets with javascript asset maps. Includes (background threaded) downloadFile, getFileURI, getFileURIs, deleteFile.

phonegap-plugin-wizAssets

• PhoneGap Version : 3.0

Description

PhoneGap plugin for managing application assets with javascript asset maps. Includes downloadFile, getFileURI, getFileURIs, deleteFile, deleteFiles.

Install (with Plugman)

cordova plugin add https://github.com/Wizcorp/phonegap-plugin-wizAssets
cordova build ios

< or >

phonegap local plugin add https://github.com/Wizcorp/phonegap-plugin-wizAssets
phonegap build ios

APIs

wizAssets.initialize(success, fail)

• Call this method first to know if plugin initialization went well. In some rare corner cases (if device storage is not writable for an unknown reason for instance) it can fail.
• If initialization failed, any other API call will call the error callback.

Example

wizAssets.initialize(function () {
        console.log('wiz assets is ready to be used');
    }, function () {
        console.log('wiz assets did not initialize, it cannot be used');
    }
);

wizAssets.downloadFile(remoteURL, assetId, success, fail)

• downloads a file to native App directory @ ./ + gameDir+ / + assetId
  
• A success returns a local URL string like; file://documents/settings/img/cards/card001.jpg
  
• An error returns an error object such as:

{
    "code": WizAssetsError value,
    "status": if code is a HTTP_REQUEST_ERROR, the status of the HTPP request, optional
    "message": description of the error if any
}

Example

wizAssets.downloadFile("http://google.com/logo.jpg", "img/ui/logo.jpg", successCallback, failCallback);

wizAssets.deleteFile(assetId, success, fail)

• deletes the file specified by the asset id
  
• if the asset id does not exist fail will be called with error NotFoundError
  
• if the asset id cannot be deleted (i.e. file resides in read-only memory) fail will be called with an error message

Example

wizAssets.deleteFile("img/cards/card001.jpg", successCallback, failCallback);

wizAssets.deleteFiles(assetIds, success, fail)

• delete files specified by their asset id in Array
  
• if an asset id uses a path format and matches a folder, then the folder content will be deleted; img/cards
  
• if an asset id cannot be deleted (i.e. file resides in read-only memory) fail will be called with an error message
• the array CAN contain one asset id

Example

wizAssets.deleteFiles(["img/cards/card001.jpg", "img/cards/card002.jpg"], successCallback, failCallback);

wizAssets.getFileURI(assetId, success, fail)

• A success returns a local URL string like file://documents/settings/img/cards/card001.jpg
  
• A failure returns an error message

Example

wizAssets.getFileURI("img/ui/logo.jpg", successCallback, failCallback);

wizAssets.getFileURIs(success, fail)

• A success returns a hashmap of asset id matching its local URL such as
• A failure returns an error message

{

    "img/ui/loader.gif"  : "/sdcard/<appname>/img/ui/loading.gif", 
    "img/cards/card001.jpg" : "file://documents/settings/img/cards/card001.jpg" 

}

Example

wizAssets.getFileURIs(successCallback, failCallback);

Error handling

All error codes are available via window.WizAssetsError.

Example

function fail(error) {
    if (error.code === window.WizAssetsError.HTTP_REQUEST_ERROR) {
        // Check error.status
    } else {
        // Log error code with error.message
    }
}

Code	Constant	Description
1	ARGS_MISSING_ERROR	Arguments are missing in your call to WizAssets' method
2	INVALID_URL_ERROR	Specified URL to download is invald
3	CONNECTIVITY_ERROR	Download could not be processed because network could not be accessed
4	HTTP_REQUEST_ERROR	HTTP status of the request is not successful (not 2XX)
5	HTTP_REQUEST_CONTENT_ERROR	Content received in HTTP request could not be read
6	DIRECTORY_CREATION_ERROR	Creation of the directory to save the asset failed
7	FILE_CREATION_ERROR	Saving the asset failed
8	JSON_CREATION_ERROR	Your call to WizAssets' method failed and its error could not be processed internally
9	INITIALIZATION_ERROR	WizAssets initialization failed
10	NOT_FOUND_ERROR	Asset could not be found
11	UNREFERENCED_ERROR	Unknown error: message string (error.message) will contain more information