cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rakat...@apache.org
Subject cordova-plugin-file-transfer git commit: CB-11003: Adding sample section to documentation.
Date Tue, 26 Apr 2016 00:06:52 GMT
Repository: cordova-plugin-file-transfer
Updated Branches:
  refs/heads/master 128c388d5 -> eb8052711


CB-11003: Adding sample section to documentation.

 This closes #136


Project: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer/commit/eb805271
Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer/tree/eb805271
Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer/diff/eb805271

Branch: refs/heads/master
Commit: eb8052711fe0b4dec4559458860a4217e262c5b1
Parents: 128c388
Author: Mikejo5001 <m.jones168@outlook.com>
Authored: Fri Apr 1 14:04:31 2016 -0700
Committer: Raghav Katyal <rakatyal@microsoft.com>
Committed: Mon Apr 25 17:05:24 2016 -0700

----------------------------------------------------------------------
 README.md | 250 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 250 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer/blob/eb805271/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index cc879c7..10e7c96 100644
--- a/README.md
+++ b/README.md
@@ -319,3 +319,253 @@ If you are upgrading to a new (1.0.0 or newer) version of File, and
you have pre
     cdvfile://localhost/persistent/path/to/file
 
 which can be used in place of the absolute file path in both `download()` and `upload()`
methods.
+
+## Sample: Download and Upload Files <a name="sample"></a>
+
+Use the File-Transfer plugin to upload and download files. In these examples, we demonstrate
several tasks like:
+
+* [Downloading a binary file to the application cache](#binaryFile)
+* [Uploading a file created in your application's root](#uploadFile)
+* [Downloading the uploaded file](#downloadFile)
+
+## Download a Binary File to the application cache <a name="binaryFile"></a>
+
+Use the File plugin with the File-Transfer plugin to provide a target for the files that
you download (the target must be a FileEntry object). Before you download the file, create
a DirectoryEntry object by using `resolveLocalFileSystemURL` and calling `fs.root` in the
success callback. Use the `getFile` method of DirectoryEntry to create the target file.
+
+```js
+window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+    console.log('file system open: ' + fs.name);
+
+    // Make sure you add the domain name to the Content-Security-Policy <meta> element.
+    var url = 'http://cordova.apache.org/static/img/cordova_bot.png';
+    // Parameters passed to getFile create a new file or return the file if it already exists.
+    fs.root.getFile('downloaded-image.png', { create: true, exclusive: false }, function
(fileEntry) {
+        download(fileEntry, url, true);
+
+    }, onErrorCreateFile);
+
+}, onErrorLoadFs);
+```
+
+>*Note* For persistent storage, pass LocalFileSystem.PERSISTENT to requestFileSystem.
+
+When you have the FileEntry object, download the file using the `download` method of the
FileTransfer object. The 3rd argument to the `download` function of FileTransfer is the success
callback, which you can use to call the app's `readBinaryFile` function. In this code example,
the `entry` variable is a new FileEntry object that receives the result of the download operation.
+
+```js
+function download(fileEntry, uri, readBinaryData) {
+
+    var fileTransfer = new FileTransfer();
+    var fileURL = fileEntry.toURL();
+
+    fileTransfer.download(
+        uri,
+        fileURL,
+        function (entry) {
+            console.log("Successful download...");
+            console.log("download complete: " + entry.toURL());
+            if (readBinaryData) {
+              // Read the file...
+              readBinaryFile(entry);
+            }
+            else {
+              // Or just display it.
+              displayImageByFileURL(entry);
+            }
+        },
+        function (error) {
+            console.log("download error source " + error.source);
+            console.log("download error target " + error.target);
+            console.log("upload error code" + error.code);
+        },
+        null, // or, pass false
+        {
+            //headers: {
+            //    "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
+            //}
+        }
+    );
+}
+```
+
+If you just need to display the image, take the FileEntry to call its toURL() function.
+
+```js
+function displayImageByFileURL(fileEntry) {
+    var elem = document.getElementById('imageFile');
+    elem.src = fileEntry.toURL();
+}
+```
+
+Depending on your app requirements, you may want to read the file. To support operations
with binary files, FileReader supports two methods, `readAsBinaryString` and `readAsArrayBuffer`.
In this example, use `readAsArrayBuffer` and pass the FileEntry object to the method. Once
you read the file successfully, construct a Blob object using the result of the read.
+
+```js
+function readBinaryFile(fileEntry) {
+    fileEntry.file(function (file) {
+        var reader = new FileReader();
+
+        reader.onloadend = function() {
+
+            console.log("Successful file read: " + this.result);
+            // displayFileData(fileEntry.fullPath + ": " + this.result);
+
+            var blob = new Blob([new Uint8Array(this.result)], { type: "image/png" });
+            displayImage(blob);
+        };
+
+        reader.readAsArrayBuffer(file);
+
+    }, onErrorReadFile);
+}
+```
+
+Once you read the file successfully, you can create a DOM URL string using `createObjectURL`,
and then display the image.
+
+```js
+function displayImage(blob) {
+
+    // Note: Use window.URL.revokeObjectURL when finished with image.
+    var objURL = window.URL.createObjectURL(blob);
+
+    // Displays image if result is a valid DOM string for an image.
+    var elem = document.getElementById('imageFile');
+    elem.src = objURL;
+}
+```
+
+As you saw previously, you can call FileEntry.toURL() instead to just display the downloaded
image (skip the file read).
+
+## Upload a File <a name="uploadFile"></a>
+
+When you upload a File using the File-Transfer plugin, use the File plugin to provide files
for upload (again, they must be FileEntry objects). Before you can upload anything, create
a file for upload using the `getFile` method of DirectoryEntry. In this example, create the
file in the application's cache (fs.root). Then call the app's writeFile function so you have
some content to upload.
+
+```js
+function onUploadFile() {
+    window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+        console.log('file system open: ' + fs.name);
+        var fileName = "uploadSource.txt";
+        var dirEntry = fs.root;
+        dirEntry.getFile(fileName, { create: true, exclusive: false }, function (fileEntry)
{
+
+            // Write something to the file before uploading it.
+            writeFile(fileEntry);
+
+        }, onErrorCreateFile);
+
+    }, onErrorLoadFs);
+}
+```
+
+In this example, create some simple content, and then call the app's upload function.
+
+```js
+function writeFile(fileEntry, dataObj) {
+    // Create a FileWriter object for our FileEntry (log.txt).
+    fileEntry.createWriter(function (fileWriter) {
+
+        fileWriter.onwriteend = function () {
+            console.log("Successful file write...");
+            upload(fileEntry);
+        };
+
+        fileWriter.onerror = function (e) {
+            console.log("Failed file write: " + e.toString());
+        };
+
+        if (!dataObj) {
+          dataObj = new Blob(['file data to upload'], { type: 'text/plain' });
+        }
+
+        fileWriter.write(dataObj);
+    });
+}
+```
+
+Forward the FileEntry object to the upload function. To perform the actual upload, use the
upload function of the FileTransfer object.
+
+```js
+function upload(fileEntry) {
+    // !! Assumes variable fileURL contains a valid URL to a text file on the device,
+    var fileURL = fileEntry.toURL();
+
+    var success = function (r) {
+        console.log("Successful upload...");
+        console.log("Code = " + r.responseCode);
+        displayFileData(fileEntry.fullPath + " (content uploaded to server)");
+    }
+
+    var fail = function (error) {
+        alert("An error has occurred: Code = " + error.code);
+    }
+
+    var options = new FileUploadOptions();
+    options.fileKey = "file";
+    options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
+    options.mimeType = "text/plain";
+
+    var params = {};
+    params.value1 = "test";
+    params.value2 = "param";
+
+    options.params = params;
+
+    var ft = new FileTransfer();
+    // SERVER must be a URL that can handle the request, like
+    // http://some.server.com/upload.php
+    ft.upload(fileURL, encodeURI(SERVER), success, fail, options);
+};
+```
+
+## Download the uploaded file <a name="downloadFile"></a>
+
+To download the image you just uploaded, you will need a valid URL that can handle the request,
for example, http://some.server.com/download.php. Again, the success handler for the FileTransfer.download
method receives a FileEntry object. The main difference here from previous examples is that
we call FileReader.readAsText to read the result of the download operation, because we uploaded
a file with text content.
+
+```js
+function download(fileEntry, uri) {
+
+    var fileTransfer = new FileTransfer();
+    var fileURL = fileEntry.toURL();
+
+    fileTransfer.download(
+        uri,
+        fileURL,
+        function (entry) {
+            console.log("Successful download...");
+            console.log("download complete: " + entry.toURL());
+            readFile(entry);
+        },
+        function (error) {
+            console.log("download error source " + error.source);
+            console.log("download error target " + error.target);
+            console.log("upload error code" + error.code);
+        },
+        null, // or, pass false
+        {
+            //headers: {
+            //    "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
+            //}
+        }
+    );
+}
+```
+
+In the readFile function, call the `readAsText` method of the FileReader object.
+
+```js
+function readFile(fileEntry) {
+    fileEntry.file(function (file) {
+        var reader = new FileReader();
+
+        reader.onloadend = function () {
+
+            console.log("Successful file read: " + this.result);
+            // displayFileData(fileEntry.fullPath + ": " + this.result);
+
+        };
+
+        reader.readAsText(file);
+
+    }, onErrorReadFile);
+}
+```


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org


Mime
View raw message