[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user asfgit closed the pull request at: https://github.com/apache/cordova-plugin-file/pull/176 --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user rakatyal commented on the pull request: https://github.com/apache/cordova-plugin-file/pull/176#issuecomment-208616871 Minor comments. LGTM. --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user rakatyal commented on a diff in the pull request: https://github.com/apache/cordova-plugin-file/pull/176#discussion_r59298774 --- Diff: README.md --- @@ -538,3 +540,296 @@ Android also supports a special filesystem named "documents", which represents a * `root`: The entire device filesystem By default, the library and documents directories can be synced to iCloud. You can also request two additional filesystems, `library-nosync` and `documents-nosync`, which represent a special non-synced directory within the `/Library` or `/Documents` filesystem. + +## Sample: Create Files and Directories, Write, Read, and Append files + +The File plugin allows you to do things like store files in a temporary or persistent storage location for your app (sandboxed storage) and to store files in other platform-dependent locations. The code snippets in this section demonstrate different tasks including: +* Accessing the file system +* Using cross-platform Cordova file URLs to store your files (see _Where to Store Files_ for more info) --- End diff -- Consider making these hyperlinks for ease of navigation. --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user rakatyal commented on a diff in the pull request: https://github.com/apache/cordova-plugin-file/pull/176#discussion_r59298517 --- Diff: README.md --- @@ -36,7 +36,9 @@ Although most of the plugin code was written when an earlier spec was current: It also implements the FileWriter spec : [http://dev.w3.org/2009/dap/file-system/file-writer.html](http://dev.w3.org/2009/dap/file-system/file-writer.html) -For usage, please refer to HTML5 Rocks' excellent [FileSystem article.](http://www.html5rocks.com/en/tutorials/file/filesystem/) +>*Note* While the W3C FileSystem spec is deprecated for web browsers, the FileSystem APIs are supported in Cordova applications with this plugin for the platforms listed in the _Supported Platforms_ list, with the exception of the Browser platform. + +For usage, please refer to the [sample section](#sample) at the end of this article. For additional examples (browser focused), see the HTML5 Rocks' [FileSystem article.](http://www.html5rocks.com/en/tutorials/file/filesystem/) For an overview of other storage options, refer to Cordova's [storage guide](http://cordova.apache.org/docs/en/edge/cordova_storage_storage.md.html). --- End diff -- Kindly update this link to use 'latest' instead of 'edge'. http://cordova.apache.org/docs/en/latest/cordova/storage/storage.html --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
Re: [GitHub] cordova-plugin-file pull request: adding sample section to readme
1. Browser platform... the one under discussion. 2. I understood everything you say in your response paragraphs 2 and 3. 3. My points still remain... your statement "many of these APIs..." is confusing. 4. Your words in paragraphs 2 and 3 of your response should be included as clarification. 5. Replace "I believe it" with "Chrome Version 49.0.2623.112 m still works, but there is no guarantee that this will continue." Regards Rob Regards *Rob Posener* 0419 012 627 On 8 April 2016 at 08:44, jasongin wrote: > Github user jasongin commented on the pull request: > > > https://github.com/apache/cordova-plugin-file/pull/176#issuecomment-207123605 > > Rob, what platform are you looking at? > > The W3C FileSystems spec for web browsers is deprecated; what that > effectively means is no other browsers will implement the spec. Chrome was > the only browser to ever implement that spec, and I believe it still works > in current builds of Chrome > > However, the Cordova file plugin implements that spec as a polyfill > for Cordova platforms other than the "Browser" platform (because the > Browser platform isn't able to call native plugin APIs). So it makes the > deprecation of the spec mostly irrelevant for Cordova app developers. > > > --- > If your project is set up for it, you can reply to this email and have your > reply appear on GitHub as well. If your project does not have this feature > enabled and wishes so, or if the feature is enabled but not working, please > contact infrastructure at infrastruct...@apache.org or file a JIRA ticket > with INFRA. > --- > > - > To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org > For additional commands, e-mail: dev-h...@cordova.apache.org > >
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on the pull request: https://github.com/apache/cordova-plugin-file/pull/176#issuecomment-207123605 Rob, what platform are you looking at? The W3C FileSystems spec for web browsers is deprecated; what that effectively means is no other browsers will implement the spec. Chrome was the only browser to ever implement that spec, and I believe it still works in current builds of Chrome However, the Cordova file plugin implements that spec as a polyfill for Cordova platforms other than the "Browser" platform (because the Browser platform isn't able to call native plugin APIs). So it makes the deprecation of the spec mostly irrelevant for Cordova app developers. --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user RobPosener commented on the pull request: https://github.com/apache/cordova-plugin-file/pull/176#issuecomment-207120687 I am able to get all of the File System APIs that I require to work correctly. I can create directories and sub-directories. I can create files and read files. So I am confused by the "many of these APIs are depreciated" statement. I think you should expand on this statement... Does it mean that the APIs work, but will be withdrawn? Does it mean that they don't work? Which ones does "many" refer to? --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on the pull request: https://github.com/apache/cordova-plugin-file/pull/176#issuecomment-207076949 Looks good, thanks! --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request:
https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58929077
--- Diff: README.md ---
@@ -538,3 +540,298 @@ Android also supports a special filesystem named
"documents", which represents a
* `root`: The entire device filesystem
By default, the library and documents directories can be synced to iCloud.
You can also request two additional filesystems, `library-nosync` and
`documents-nosync`, which represent a special non-synced directory within the
`/Library` or `/Documents` filesystem.
+
+## Sample: Create Files and Directories, Write, Read, and Append files
+
+The File plugin allows you to do things like store files in a temporary or
persistent storage location for your app (sandboxed storage) and to store files
in other platform-dependent locations. The code snippets in this section
demonstrate different tasks including:
+* Accessing the file system
+* Using cross-platform Cordova file URLs to store your files (see _Where
to Store Files_ for more info)
+* Creating files and directories
+* Writing to files
+* Reading files
+* Appending files
+
+## Create a persistent file
+
+Before you use the File plugin APIs, you can get access to the file system
using `requestFileSystem`. When you do this, you can request either persistent
or temporary storage. Persistent storage will not be removed unless permission
is granted by the user.
+
+When you get file system access using `requestFileSystem`, access is
granted for the sandboxed file system only (the sandbox limits access to the
app itself), not for general access to any file system location on the device.
(To access file system locations outside the sandboxed storage, use other
methods such as window.requestLocalFileSystemURL, which support
platform-specific locations. For one example of this, see _Append a File_.)
+
+Here is a request for persistent storage.
+
+>*Note* When targeting WebView clients (instead of a browser) or native
apps (Windows), you dont need to use `requestQuota` before using persistent
storage.
+
+```js
+window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) {
+
+console.log('file system open: ' + fs.name);
+fs.root.getFile("newPersistentFile.txt", { create: true, exclusive:
false }, function (fileEntry) {
+
+console.log("fileEntry is file?" + fileEntry.isFile.toString());
+// fileEntry.name == 'someFile.txt'
+// fileEntry.fullPath == '/someFile.txt'
+writeFile(fileEntry, null);
+
+}, onErrorCreateFile);
+
+}, onErrorLoadFs);
+```
+
+The success callback receives FileSystem object (fs). Use `fs.root` to
return a DirectoryEntry object, which you can use to create or get a file (by
calling `getFile`). In this example, `fs.root` is a DirectoryEntry object that
represents the persistent storage in the sandboxed file system.
+
+The success callback for `getFile` receives a FileEntry object. You can
use this to perform file write and file read operations.
+
+## Create a temporary file
+
+Here is an example of a request for temporary storage. Temporary storage
may be deleted by the operating system if the device runs low on memory.
+
+```js
+window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+console.log('file system open: ' + fs.name);
+createFile(fs.root, "newTempFile.txt", false);
+
+}, onErrorLoadFs);
+```
+When you are using temporary storage, you can create or get the file by
calling `getFile`. As in the persistent storage example, this will give you a
FileEntry object that you can use for read or write operations.
+
+```js
+function createFile(dirEntry, fileName, isAppend) {
+// Creates a new file or returns the file if it already exists.
+dirEntry.getFile(fileName, {create: true, exclusive: false},
function(fileEntry) {
+
+writeFile(fileEntry, null, isAppend);
+
+}, onErrorCreateFile);
+
+}
+```
+
+## Write to a file
+
+Once you have a FileEntry object, you can write to the file by calling
`createWriter`, which returns a FileWriter object in the success callback. Call
the `write` method of FileWriter to write to the file.
+
+```js
+function writeFile(fileEntry, dataObj) {
+// Create a FileWriter object for our FileEntry (log.txt).
+fileEntry.createWriter(function (fileWriter) {
+
+fileWriter.onwriteend = function (e) {
+console.log("Successful file read...");
+readFile(fileEntry);
+};
+
+fileWriter.onerror = function (e) {
+console.log("Failed file read: " + e.toString());
+};
+
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request: https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58928914 --- Diff: README.md --- @@ -36,7 +36,9 @@ Although most of the plugin code was written when an earlier spec was current: It also implements the FileWriter spec : [http://dev.w3.org/2009/dap/file-system/file-writer.html](http://dev.w3.org/2009/dap/file-system/file-writer.html) -For usage, please refer to HTML5 Rocks' excellent [FileSystem article.](http://www.html5rocks.com/en/tutorials/file/filesystem/) +>*Note* For Cordova clients that run in native WebViews (for example, iOS and Android) or as native apps (Windows), many of the W3C APIs FileSystem are supported. This is true for the platforms listed in the _Supported Platforms_ list except the Browser platform. On the Browser platform, many of these APIs are deprecated. --- End diff -- "W3C APIs FileSystem" => "W3C FileSystem APIs" Avoid the term "native apps" to refer to Cordova apps on Windows. Even though Windows has built-in support for HTML/JS apps, most developers would not consider Cordova apps to be "native". (also on line 562) How about something like this: While the W3C FileSystem spec is deprecated for web browsers, the FileSystem APIs are supported in Cordova applications with this plugin for the platforms listed in the Supported Platforms list, with the exception of the Browser platform. --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request: https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58927585 --- Diff: README.md --- @@ -36,9 +36,9 @@ Although most of the plugin code was written when an earlier spec was current: It also implements the FileWriter spec : [http://dev.w3.org/2009/dap/file-system/file-writer.html](http://dev.w3.org/2009/dap/file-system/file-writer.html) ->*Note* For browser targets, some of the file system APIs are deprecated, but many of the APIs are supported in Cordova for the non-browser platforms listed in the _Supported Platforms_ list (see below). +>*Note* For Cordova clients that run in native WebViews (for example, iOS and Android) or as native apps (Windows), many of the W3C APIs FileSystem are supported. This is true for the platforms listed in the _Supported Platforms_ list except the Browser platform. On the Browser platform, many of these APIs are deprecated. --- End diff -- "W3C APIs FileSystem" => "W3C FileSystem APIs" Avoid the term "native apps" to refer to Cordova apps on Windows. Even though Windows has built-in support for HTML/JS apps, most developers would not consider Cordova apps to be "native". (also on line 562) How about something like this: While the W3C FileSystem spec is deprecated for web browsers, the FileSystem APIs are supported in Cordova applications with this plugin for the platforms listed in the _Supported Platforms_ list, with the exception of the Browser platform. --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request:
https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58928337
--- Diff: README.md ---
@@ -671,89 +718,111 @@ window.requestFileSystem(window.TEMPORARY, 5 * 1024
* 1024, function (fs) {
}, onErrorLoadFs);
```
-For completeness, here is the xhr request to get a Blob image. There is
nothing Cordova-specific in this code, except that you forward the
DirectoryEntry reference that you already obtained as an argument to the
saveFile function. You will save the image as a DOM string URL and display it
later after reading the file (to validate the operation).
+For completeness, here is the xhr request to get a Blob image. There is
nothing Cordova-specific in this code, except that you forward the
DirectoryEntry reference that you already obtained as an argument to the
saveFile function. You will save the blob image and display it later after
reading the file (to validate the operation).
-```
+```js
function getSampleFile(dirEntry) {
var xhr = new XMLHttpRequest();
xhr.open('GET',
'http://cordova.apache.org/static/img/cordova_bot.png', true);
xhr.responseType = 'blob';
-xhr.onload = function (e) {
+xhr.onload = function() {
if (this.status == 200) {
var blob = new Blob([this.response], { type: 'image/png' });
-var img = new Image();
-// Note: Use window.URL.revokeObjectURL when finished with
image.
-img.src = window.URL.createObjectURL(blob);
-
-saveFile(dirEntry, img.src, "downloadedImage.png");
+saveFile(dirEntry, blob, "downloadedImage.png");
}
};
xhr.send();
}
```
>*Note* For Cordova 5 security, the preceding code requires that you add
the domain name, http://cordova.apache.org, to the Content-Security-Policy
element in index.html.
-After getting the file, copy the contents to a new file. The current
DirectoryEntry object is already associated the app cache.
+After getting the file, copy the contents to a new file. The current
DirectoryEntry object is already associated with the app cache.
-```
-function saveFile(dirEntry, srcImage, fileName) {
+```js
+function saveFile(dirEntry, fileData, fileName) {
dirEntry.getFile(fileName, { create: true, exclusive: false },
function (fileEntry) {
-writeFile(fileEntry, srcImage);
+writeFile(fileEntry, fileData);
}, onErrorCreateFile);
}
```
-In writeFile, you pass in the DOM string URL as the dataObj and you will
save that in the new file.
+In writeFile, you pass in the Blob object as the dataObj and you will save
that in the new file.
+
+```js
+function writeFile(fileEntry, dataObj, isAppend) {
-```
-function writeFile(fileEntry, dataObj) {
// Create a FileWriter object for our FileEntry (log.txt).
fileEntry.createWriter(function (fileWriter) {
-fileWriter.onwriteend = function (e) {
+fileWriter.onwriteend = function() {
console.log("Successful file write...");
-readFile(fileEntry);
+if (dataObj.type == "image/png") {
+readBinaryFile(fileEntry);
+}
+else {
+readFile(fileEntry);
+}
};
-fileWriter.onerror = function (e) {
+fileWriter.onerror = function() {
console.log("Failed file write: " + e.toString());
};
-// If data object is not passed in,
-// create a new Blob instead.
-if (!dataObj) {
-dataObj = new Blob(['some file data'], { type: 'text/plain' });
-}
-
fileWriter.write(dataObj);
});
}
```
-After writing to the file, read it and display it. These operations re-use
the code that we showed you already in previous tasks, so theres nothing new
there (see the previous sections). After reading the data, you can display the
image using code like this.
+After writing to the file, read it and display it. You saved the image as
binary data, so you can read it using FileReader.readAsArrayBuffer.
+
+```js
+function readBinaryFile(fileEntry) {
+
+fileEntry.file(function (file) {
+var reader = new FileReader();
+
+reader.onloadend = function() {
+console.log("Successful file write: " + this.result);
+displayFileData(fileEntry.fullPath + ": " + this.result);
+
+var blob = new Blob([new Uint8Array(this.result)], { type:
"image/png" });
+displayImage(blob);
+};
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request:
https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58928048
--- Diff: README.md ---
@@ -671,89 +718,111 @@ window.requestFileSystem(window.TEMPORARY, 5 * 1024
* 1024, function (fs) {
}, onErrorLoadFs);
```
-For completeness, here is the xhr request to get a Blob image. There is
nothing Cordova-specific in this code, except that you forward the
DirectoryEntry reference that you already obtained as an argument to the
saveFile function. You will save the image as a DOM string URL and display it
later after reading the file (to validate the operation).
+For completeness, here is the xhr request to get a Blob image. There is
nothing Cordova-specific in this code, except that you forward the
DirectoryEntry reference that you already obtained as an argument to the
saveFile function. You will save the blob image and display it later after
reading the file (to validate the operation).
-```
+```js
function getSampleFile(dirEntry) {
var xhr = new XMLHttpRequest();
xhr.open('GET',
'http://cordova.apache.org/static/img/cordova_bot.png', true);
xhr.responseType = 'blob';
-xhr.onload = function (e) {
+xhr.onload = function() {
if (this.status == 200) {
var blob = new Blob([this.response], { type: 'image/png' });
-var img = new Image();
-// Note: Use window.URL.revokeObjectURL when finished with
image.
-img.src = window.URL.createObjectURL(blob);
-
-saveFile(dirEntry, img.src, "downloadedImage.png");
+saveFile(dirEntry, blob, "downloadedImage.png");
}
};
xhr.send();
}
```
>*Note* For Cordova 5 security, the preceding code requires that you add
the domain name, http://cordova.apache.org, to the Content-Security-Policy
element in index.html.
-After getting the file, copy the contents to a new file. The current
DirectoryEntry object is already associated the app cache.
+After getting the file, copy the contents to a new file. The current
DirectoryEntry object is already associated with the app cache.
-```
-function saveFile(dirEntry, srcImage, fileName) {
+```js
+function saveFile(dirEntry, fileData, fileName) {
dirEntry.getFile(fileName, { create: true, exclusive: false },
function (fileEntry) {
-writeFile(fileEntry, srcImage);
+writeFile(fileEntry, fileData);
}, onErrorCreateFile);
}
```
-In writeFile, you pass in the DOM string URL as the dataObj and you will
save that in the new file.
+In writeFile, you pass in the Blob object as the dataObj and you will save
that in the new file.
+
+```js
+function writeFile(fileEntry, dataObj, isAppend) {
-```
-function writeFile(fileEntry, dataObj) {
// Create a FileWriter object for our FileEntry (log.txt).
fileEntry.createWriter(function (fileWriter) {
-fileWriter.onwriteend = function (e) {
+fileWriter.onwriteend = function() {
console.log("Successful file write...");
-readFile(fileEntry);
+if (dataObj.type == "image/png") {
+readBinaryFile(fileEntry);
+}
+else {
+readFile(fileEntry);
+}
};
-fileWriter.onerror = function (e) {
+fileWriter.onerror = function() {
--- End diff --
Oops, this e parameter is actually used below.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
-
To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org
For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request:
https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58442897
--- Diff: README.md ---
@@ -538,3 +540,263 @@ Android also supports a special filesystem named
"documents", which represents a
* `root`: The entire device filesystem
By default, the library and documents directories can be synced to iCloud.
You can also request two additional filesystems, `library-nosync` and
`documents-nosync`, which represent a special non-synced directory within the
`/Library` or `/Documents` filesystem.
+
+## Sample: Create Files and Directories, Write, Read, and Append files ##
+
+The File plugin allows you to do things like store files in a temporary or
persistent storage location for your app (sandboxed storage). The code snippets
in this section demonstrate different tasks including:
+* Accessing the file system
+* Using cross-platform Cordova file URLs to store your files (see _Where
to Store Files_ for more info)
+* Creating files and directories
+* Writing to files
+* Reading files
+* Appending files
+
+## Create a persistent file
+
+Before you can use the File plugin APIs, you must get access to the file
system using `requestFileSystem`. When you do this, you can request either
persistent or temporary storage. Persistent storage will not be removed unless
permission is granted by the user.
+
+When you get file system access, access is granted for the sandboxed file
system only (the sandbox limits access to the app itself), not for general
access to any file system location on the device.
+
+Here is a request for persistent storage.
+
+>*Note* When targeting devices (instead of a browser), you dont need to
use `requestQuota` before using persistent storage.
+
+```
+window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) {
+
+console.log('file system open: ' + fs.name);
+fs.root.getFile("newPersistentFile.txt", { create: true, exclusive:
false }, function (fileEntry) {
+
+console.log("fileEntry is file?" + fileEntry.isFile.toString());
+// fileEntry.name == 'someFile.txt'
+// fileEntry.fullPath == '/someFile.txt'
+writeFile(fileEntry, null);
+
+}, onErrorCreateFile);
+
+}, onErrorLoadFs);
+```
+
+The success callback receives FileSystem object (fs). Use `fs.root` to
return a DirectoryEntry object, which you can use to create or get a file (by
calling `getFile`). In this example, `fs.root` is a DirectoryEntry object that
represents the persistent storage in the sandboxed file system.
+
+The success callback for `getFile` receives a FileEntry object. You can
use this to perform file write and file read operations.
+
+## Create a temporary file
+
+Here is an example of a request for temporary storage. Temporary storage
may be deleted by the operating system if the device runs low on memory.
+
+```
+window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+console.log('file system open: ' + fs.name);
+createFile(fs.root, "newTempFile.txt");
+
+}, onErrorLoadFs);
+```
+When you are using temporary storage, you can create or get the file by
calling `getFile`. As in the persistent storage example, this will give you a
FileEntry object that you can use for read or write operations.
+
+```
+// Creates a new file or returns the file if it already exists.
+dirEntry.getFile(fileName, {create: true, exclusive: false},
function(fileEntry) {
+
+writeFile(fileEntry);
+
+}, onErrorCreateFile);
+```
+
+## Write to a file
+
+Once you have a FileEntry object, you can write to the file by calling
`createWriter`, which returns a FileWriter object in the success callback. Call
the `write` method of FileWriter to write to the file.
+
+```
+function writeFile(fileEntry, dataObj) {
+// Create a FileWriter object for our FileEntry (log.txt).
+fileEntry.createWriter(function (fileWriter) {
+
+fileWriter.onwriteend = function (e) {
+console.log("Successful file read...");
+readFile(fileEntry);
+};
+
+fileWriter.onerror = function (e) {
+console.log("Failed file read: " + e.toString());
+};
+
+// If data object is not passed in,
+// create a new Blob instead.
+if (!dataObj) {
+dataObj = new Blob(['some file data'], { type: 'text/plain' });
+}
+
+fileWriter.write(dataObj);
+});
+}
+```
+
+## Read a file
+
+You also need a FileEntry object to read an existing file. Use the file
property of FileEntry to get the file reference
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request:
https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58442531
--- Diff: README.md ---
@@ -538,3 +540,263 @@ Android also supports a special filesystem named
"documents", which represents a
* `root`: The entire device filesystem
By default, the library and documents directories can be synced to iCloud.
You can also request two additional filesystems, `library-nosync` and
`documents-nosync`, which represent a special non-synced directory within the
`/Library` or `/Documents` filesystem.
+
+## Sample: Create Files and Directories, Write, Read, and Append files ##
+
+The File plugin allows you to do things like store files in a temporary or
persistent storage location for your app (sandboxed storage). The code snippets
in this section demonstrate different tasks including:
+* Accessing the file system
+* Using cross-platform Cordova file URLs to store your files (see _Where
to Store Files_ for more info)
+* Creating files and directories
+* Writing to files
+* Reading files
+* Appending files
+
+## Create a persistent file
+
+Before you can use the File plugin APIs, you must get access to the file
system using `requestFileSystem`. When you do this, you can request either
persistent or temporary storage. Persistent storage will not be removed unless
permission is granted by the user.
+
+When you get file system access, access is granted for the sandboxed file
system only (the sandbox limits access to the app itself), not for general
access to any file system location on the device.
+
+Here is a request for persistent storage.
+
+>*Note* When targeting devices (instead of a browser), you dont need to
use `requestQuota` before using persistent storage.
+
+```
+window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) {
+
+console.log('file system open: ' + fs.name);
+fs.root.getFile("newPersistentFile.txt", { create: true, exclusive:
false }, function (fileEntry) {
+
+console.log("fileEntry is file?" + fileEntry.isFile.toString());
+// fileEntry.name == 'someFile.txt'
+// fileEntry.fullPath == '/someFile.txt'
+writeFile(fileEntry, null);
+
+}, onErrorCreateFile);
+
+}, onErrorLoadFs);
+```
+
+The success callback receives FileSystem object (fs). Use `fs.root` to
return a DirectoryEntry object, which you can use to create or get a file (by
calling `getFile`). In this example, `fs.root` is a DirectoryEntry object that
represents the persistent storage in the sandboxed file system.
+
+The success callback for `getFile` receives a FileEntry object. You can
use this to perform file write and file read operations.
+
+## Create a temporary file
+
+Here is an example of a request for temporary storage. Temporary storage
may be deleted by the operating system if the device runs low on memory.
+
+```
+window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+console.log('file system open: ' + fs.name);
+createFile(fs.root, "newTempFile.txt");
+
+}, onErrorLoadFs);
+```
+When you are using temporary storage, you can create or get the file by
calling `getFile`. As in the persistent storage example, this will give you a
FileEntry object that you can use for read or write operations.
+
+```
+// Creates a new file or returns the file if it already exists.
+dirEntry.getFile(fileName, {create: true, exclusive: false},
function(fileEntry) {
+
+writeFile(fileEntry);
+
+}, onErrorCreateFile);
+```
+
+## Write to a file
+
+Once you have a FileEntry object, you can write to the file by calling
`createWriter`, which returns a FileWriter object in the success callback. Call
the `write` method of FileWriter to write to the file.
+
+```
+function writeFile(fileEntry, dataObj) {
+// Create a FileWriter object for our FileEntry (log.txt).
+fileEntry.createWriter(function (fileWriter) {
+
+fileWriter.onwriteend = function (e) {
+console.log("Successful file read...");
+readFile(fileEntry);
+};
+
+fileWriter.onerror = function (e) {
+console.log("Failed file read: " + e.toString());
+};
+
+// If data object is not passed in,
+// create a new Blob instead.
+if (!dataObj) {
+dataObj = new Blob(['some file data'], { type: 'text/plain' });
+}
+
+fileWriter.write(dataObj);
+});
+}
+```
+
+## Read a file
+
+You also need a FileEntry object to read an existing file. Use the file
property of FileEntry to get the file reference
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request:
https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58442202
--- Diff: README.md ---
@@ -538,3 +540,263 @@ Android also supports a special filesystem named
"documents", which represents a
* `root`: The entire device filesystem
By default, the library and documents directories can be synced to iCloud.
You can also request two additional filesystems, `library-nosync` and
`documents-nosync`, which represent a special non-synced directory within the
`/Library` or `/Documents` filesystem.
+
+## Sample: Create Files and Directories, Write, Read, and Append files ##
+
+The File plugin allows you to do things like store files in a temporary or
persistent storage location for your app (sandboxed storage). The code snippets
in this section demonstrate different tasks including:
+* Accessing the file system
+* Using cross-platform Cordova file URLs to store your files (see _Where
to Store Files_ for more info)
+* Creating files and directories
+* Writing to files
+* Reading files
+* Appending files
+
+## Create a persistent file
+
+Before you can use the File plugin APIs, you must get access to the file
system using `requestFileSystem`. When you do this, you can request either
persistent or temporary storage. Persistent storage will not be removed unless
permission is granted by the user.
+
+When you get file system access, access is granted for the sandboxed file
system only (the sandbox limits access to the app itself), not for general
access to any file system location on the device.
+
+Here is a request for persistent storage.
+
+>*Note* When targeting devices (instead of a browser), you dont need to
use `requestQuota` before using persistent storage.
+
+```
+window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) {
+
+console.log('file system open: ' + fs.name);
+fs.root.getFile("newPersistentFile.txt", { create: true, exclusive:
false }, function (fileEntry) {
+
+console.log("fileEntry is file?" + fileEntry.isFile.toString());
+// fileEntry.name == 'someFile.txt'
+// fileEntry.fullPath == '/someFile.txt'
+writeFile(fileEntry, null);
+
+}, onErrorCreateFile);
+
+}, onErrorLoadFs);
+```
+
+The success callback receives FileSystem object (fs). Use `fs.root` to
return a DirectoryEntry object, which you can use to create or get a file (by
calling `getFile`). In this example, `fs.root` is a DirectoryEntry object that
represents the persistent storage in the sandboxed file system.
+
+The success callback for `getFile` receives a FileEntry object. You can
use this to perform file write and file read operations.
+
+## Create a temporary file
+
+Here is an example of a request for temporary storage. Temporary storage
may be deleted by the operating system if the device runs low on memory.
+
+```
+window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+console.log('file system open: ' + fs.name);
+createFile(fs.root, "newTempFile.txt");
+
+}, onErrorLoadFs);
+```
+When you are using temporary storage, you can create or get the file by
calling `getFile`. As in the persistent storage example, this will give you a
FileEntry object that you can use for read or write operations.
+
+```
+// Creates a new file or returns the file if it already exists.
+dirEntry.getFile(fileName, {create: true, exclusive: false},
function(fileEntry) {
+
+writeFile(fileEntry);
+
+}, onErrorCreateFile);
+```
+
+## Write to a file
+
+Once you have a FileEntry object, you can write to the file by calling
`createWriter`, which returns a FileWriter object in the success callback. Call
the `write` method of FileWriter to write to the file.
+
+```
+function writeFile(fileEntry, dataObj) {
+// Create a FileWriter object for our FileEntry (log.txt).
+fileEntry.createWriter(function (fileWriter) {
+
+fileWriter.onwriteend = function (e) {
+console.log("Successful file read...");
+readFile(fileEntry);
+};
+
+fileWriter.onerror = function (e) {
+console.log("Failed file read: " + e.toString());
+};
+
+// If data object is not passed in,
+// create a new Blob instead.
+if (!dataObj) {
+dataObj = new Blob(['some file data'], { type: 'text/plain' });
+}
+
+fileWriter.write(dataObj);
+});
+}
+```
+
+## Read a file
+
+You also need a FileEntry object to read an existing file. Use the file
property of FileEntry to get the file reference
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request:
https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58441628
--- Diff: README.md ---
@@ -538,3 +540,263 @@ Android also supports a special filesystem named
"documents", which represents a
* `root`: The entire device filesystem
By default, the library and documents directories can be synced to iCloud.
You can also request two additional filesystems, `library-nosync` and
`documents-nosync`, which represent a special non-synced directory within the
`/Library` or `/Documents` filesystem.
+
+## Sample: Create Files and Directories, Write, Read, and Append files ##
+
+The File plugin allows you to do things like store files in a temporary or
persistent storage location for your app (sandboxed storage). The code snippets
in this section demonstrate different tasks including:
+* Accessing the file system
+* Using cross-platform Cordova file URLs to store your files (see _Where
to Store Files_ for more info)
+* Creating files and directories
+* Writing to files
+* Reading files
+* Appending files
+
+## Create a persistent file
+
+Before you can use the File plugin APIs, you must get access to the file
system using `requestFileSystem`. When you do this, you can request either
persistent or temporary storage. Persistent storage will not be removed unless
permission is granted by the user.
+
+When you get file system access, access is granted for the sandboxed file
system only (the sandbox limits access to the app itself), not for general
access to any file system location on the device.
+
+Here is a request for persistent storage.
+
+>*Note* When targeting devices (instead of a browser), you dont need to
use `requestQuota` before using persistent storage.
+
+```
+window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) {
+
+console.log('file system open: ' + fs.name);
+fs.root.getFile("newPersistentFile.txt", { create: true, exclusive:
false }, function (fileEntry) {
+
+console.log("fileEntry is file?" + fileEntry.isFile.toString());
+// fileEntry.name == 'someFile.txt'
+// fileEntry.fullPath == '/someFile.txt'
+writeFile(fileEntry, null);
+
+}, onErrorCreateFile);
+
+}, onErrorLoadFs);
+```
+
+The success callback receives FileSystem object (fs). Use `fs.root` to
return a DirectoryEntry object, which you can use to create or get a file (by
calling `getFile`). In this example, `fs.root` is a DirectoryEntry object that
represents the persistent storage in the sandboxed file system.
+
+The success callback for `getFile` receives a FileEntry object. You can
use this to perform file write and file read operations.
+
+## Create a temporary file
+
+Here is an example of a request for temporary storage. Temporary storage
may be deleted by the operating system if the device runs low on memory.
+
+```
+window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+console.log('file system open: ' + fs.name);
+createFile(fs.root, "newTempFile.txt");
+
+}, onErrorLoadFs);
+```
+When you are using temporary storage, you can create or get the file by
calling `getFile`. As in the persistent storage example, this will give you a
FileEntry object that you can use for read or write operations.
+
+```
+// Creates a new file or returns the file if it already exists.
+dirEntry.getFile(fileName, {create: true, exclusive: false},
function(fileEntry) {
+
+writeFile(fileEntry);
+
+}, onErrorCreateFile);
+```
+
+## Write to a file
+
+Once you have a FileEntry object, you can write to the file by calling
`createWriter`, which returns a FileWriter object in the success callback. Call
the `write` method of FileWriter to write to the file.
+
+```
+function writeFile(fileEntry, dataObj) {
+// Create a FileWriter object for our FileEntry (log.txt).
+fileEntry.createWriter(function (fileWriter) {
+
+fileWriter.onwriteend = function (e) {
--- End diff --
Same for a few more non-error callbacks below.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
-
To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org
For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request:
https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58441476
--- Diff: README.md ---
@@ -538,3 +540,263 @@ Android also supports a special filesystem named
"documents", which represents a
* `root`: The entire device filesystem
By default, the library and documents directories can be synced to iCloud.
You can also request two additional filesystems, `library-nosync` and
`documents-nosync`, which represent a special non-synced directory within the
`/Library` or `/Documents` filesystem.
+
+## Sample: Create Files and Directories, Write, Read, and Append files ##
+
+The File plugin allows you to do things like store files in a temporary or
persistent storage location for your app (sandboxed storage). The code snippets
in this section demonstrate different tasks including:
+* Accessing the file system
+* Using cross-platform Cordova file URLs to store your files (see _Where
to Store Files_ for more info)
+* Creating files and directories
+* Writing to files
+* Reading files
+* Appending files
+
+## Create a persistent file
+
+Before you can use the File plugin APIs, you must get access to the file
system using `requestFileSystem`. When you do this, you can request either
persistent or temporary storage. Persistent storage will not be removed unless
permission is granted by the user.
+
+When you get file system access, access is granted for the sandboxed file
system only (the sandbox limits access to the app itself), not for general
access to any file system location on the device.
+
+Here is a request for persistent storage.
+
+>*Note* When targeting devices (instead of a browser), you dont need to
use `requestQuota` before using persistent storage.
+
+```
+window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) {
+
+console.log('file system open: ' + fs.name);
+fs.root.getFile("newPersistentFile.txt", { create: true, exclusive:
false }, function (fileEntry) {
+
+console.log("fileEntry is file?" + fileEntry.isFile.toString());
+// fileEntry.name == 'someFile.txt'
+// fileEntry.fullPath == '/someFile.txt'
+writeFile(fileEntry, null);
+
+}, onErrorCreateFile);
+
+}, onErrorLoadFs);
+```
+
+The success callback receives FileSystem object (fs). Use `fs.root` to
return a DirectoryEntry object, which you can use to create or get a file (by
calling `getFile`). In this example, `fs.root` is a DirectoryEntry object that
represents the persistent storage in the sandboxed file system.
+
+The success callback for `getFile` receives a FileEntry object. You can
use this to perform file write and file read operations.
+
+## Create a temporary file
+
+Here is an example of a request for temporary storage. Temporary storage
may be deleted by the operating system if the device runs low on memory.
+
+```
+window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
+
+console.log('file system open: ' + fs.name);
+createFile(fs.root, "newTempFile.txt");
+
+}, onErrorLoadFs);
+```
+When you are using temporary storage, you can create or get the file by
calling `getFile`. As in the persistent storage example, this will give you a
FileEntry object that you can use for read or write operations.
+
+```
+// Creates a new file or returns the file if it already exists.
+dirEntry.getFile(fileName, {create: true, exclusive: false},
function(fileEntry) {
+
+writeFile(fileEntry);
+
+}, onErrorCreateFile);
+```
+
+## Write to a file
+
+Once you have a FileEntry object, you can write to the file by calling
`createWriter`, which returns a FileWriter object in the success callback. Call
the `write` method of FileWriter to write to the file.
+
+```
+function writeFile(fileEntry, dataObj) {
+// Create a FileWriter object for our FileEntry (log.txt).
+fileEntry.createWriter(function (fileWriter) {
+
+fileWriter.onwriteend = function (e) {
--- End diff --
Remove the (e) parameter from this callback function, since there is not an
error.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
-
To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org
For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request: https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58440889 --- Diff: README.md --- @@ -538,3 +540,263 @@ Android also supports a special filesystem named "documents", which represents a * `root`: The entire device filesystem By default, the library and documents directories can be synced to iCloud. You can also request two additional filesystems, `library-nosync` and `documents-nosync`, which represent a special non-synced directory within the `/Library` or `/Documents` filesystem. + +## Sample: Create Files and Directories, Write, Read, and Append files ## + +The File plugin allows you to do things like store files in a temporary or persistent storage location for your app (sandboxed storage). The code snippets in this section demonstrate different tasks including: +* Accessing the file system +* Using cross-platform Cordova file URLs to store your files (see _Where to Store Files_ for more info) +* Creating files and directories +* Writing to files +* Reading files +* Appending files + +## Create a persistent file + +Before you can use the File plugin APIs, you must get access to the file system using `requestFileSystem`. When you do this, you can request either persistent or temporary storage. Persistent storage will not be removed unless permission is granted by the user. + +When you get file system access, access is granted for the sandboxed file system only (the sandbox limits access to the app itself), not for general access to any file system location on the device. --- End diff -- It's certainly possible to use the file plugin APIs to access some paths outside the application sandbox areas, though it may require additional permissions, for example READ/WRITE_EXTERNAL_STORAGE on Android. And you would need to use resolveLocalFileSystemURL() rather than requestFileSystem(). --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request: https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58439895 --- Diff: README.md --- @@ -538,3 +540,263 @@ Android also supports a special filesystem named "documents", which represents a * `root`: The entire device filesystem By default, the library and documents directories can be synced to iCloud. You can also request two additional filesystems, `library-nosync` and `documents-nosync`, which represent a special non-synced directory within the `/Library` or `/Documents` filesystem. + +## Sample: Create Files and Directories, Write, Read, and Append files ## + +The File plugin allows you to do things like store files in a temporary or persistent storage location for your app (sandboxed storage). The code snippets in this section demonstrate different tasks including: +* Accessing the file system +* Using cross-platform Cordova file URLs to store your files (see _Where to Store Files_ for more info) +* Creating files and directories +* Writing to files +* Reading files +* Appending files + +## Create a persistent file + +Before you can use the File plugin APIs, you must get access to the file system using `requestFileSystem`. When you do this, you can request either persistent or temporary storage. Persistent storage will not be removed unless permission is granted by the user. --- End diff -- That's not accurate. It's possible to use window.resolveLocalFileSystemURL() to get DirectoryEntry and FileEntry objects that you can read and write without ever calling window.requestFileSystem() first. You may even request a persistent or temporary path using cdvfile://localhost/persistent/ or cdvfile://localhost/temporary/. It's unfortunately confusing that there is more than one way to do the same thing, although each of those 2 APIs can do some things that the other can't. --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user jasongin commented on a diff in the pull request: https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58438965 --- Diff: README.md --- @@ -36,7 +36,9 @@ Although most of the plugin code was written when an earlier spec was current: It also implements the FileWriter spec : [http://dev.w3.org/2009/dap/file-system/file-writer.html](http://dev.w3.org/2009/dap/file-system/file-writer.html) -For usage, please refer to HTML5 Rocks' excellent [FileSystem article.](http://www.html5rocks.com/en/tutorials/file/filesystem/) +>*Note* For browser targets, some of the file system APIs are deprecated, but many of the APIs are supported in Cordova for the non-browser platforms listed in the _Supported Platforms_ list (see below). --- End diff -- I'm concerned that many readers of this may be unfamiliar with the "browser" target platform of Cordova, and potentially confused because Cordova apps on all platforms are rendered in a web browser control. Can this be made clearer? --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user riknoll commented on a diff in the pull request:
https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58276468
--- Diff: README.md ---
@@ -538,3 +540,263 @@ Android also supports a special filesystem named
"documents", which represents a
* `root`: The entire device filesystem
By default, the library and documents directories can be synced to iCloud.
You can also request two additional filesystems, `library-nosync` and
`documents-nosync`, which represent a special non-synced directory within the
`/Library` or `/Documents` filesystem.
+
+## Sample: Create Files and Directories, Write, Read, and Append files ##
+
+The File plugin allows you to do things like store files in a temporary or
persistent storage location for your app (sandboxed storage). The code snippets
in this section demonstrate different tasks including:
+* Accessing the file system
+* Using cross-platform Cordova file URLs to store your files (see _Where
to Store Files_ for more info)
+* Creating files and directories
+* Writing to files
+* Reading files
+* Appending files
+
+## Create a persistent file
+
+Before you can use the File plugin APIs, you must get access to the file
system using `requestFileSystem`. When you do this, you can request either
persistent or temporary storage. Persistent storage will not be removed unless
permission is granted by the user.
+
+When you get file system access, access is granted for the sandboxed file
system only (the sandbox limits access to the app itself), not for general
access to any file system location on the device. For more information about
location-specific URLs, see _Where to Store Files_.
+
+Here is a request for persistent storage.
+
+>*Note* When targeting devices (instead of a browser), you dont need to
use `requestQuota` before using persistent storage.
+
+```
+window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) {
+
+console.log('file system open: ' + fs.name);
+createPersistentFile("newPersistentFile.txt");
+
+}, onErrorLoadFs);
+```
+
+Once you have access, you generally want to use the Cordova file URLs,
like `cordova.file.dataDirectory`, where possible (see _Where to Store Files_).
This will hide implementation details related to the file locations. To use a
Cordova file URL, call `window.resolveLocalFileSystemURL`. The success callback
receives a DirectoryEntry object as input. You can use this object to create or
get a file (by calling `getFile`).
+
+The success callback for `getFile` receives a FileEntry object. You can
use this to perform file write and file read operations.
+
+```
+function createPersistentFile(fileName) {
+
+// Return a DirectoryEntry using Cordova file URLs.
+window.resolveLocalFileSystemURL(cordova.file.dataDirectory, function
(dirEntry) {
--- End diff --
If you are trying to write a file to the sandboxed storage location, I
believe you can just call `fs.root.getFile()` (where `fs` comes from
`requestFileSystem`) instead of calling
`window.resolveLocalFileSystemURL(cordova.file.dataDirectory, ...)` first.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
-
To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org
For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
Github user riknoll commented on a diff in the pull request:
https://github.com/apache/cordova-plugin-file/pull/176#discussion_r58275738
--- Diff: README.md ---
@@ -538,3 +540,263 @@ Android also supports a special filesystem named
"documents", which represents a
* `root`: The entire device filesystem
By default, the library and documents directories can be synced to iCloud.
You can also request two additional filesystems, `library-nosync` and
`documents-nosync`, which represent a special non-synced directory within the
`/Library` or `/Documents` filesystem.
+
+## Sample: Create Files and Directories, Write, Read, and Append files ##
+
+The File plugin allows you to do things like store files in a temporary or
persistent storage location for your app (sandboxed storage). The code snippets
in this section demonstrate different tasks including:
+* Accessing the file system
+* Using cross-platform Cordova file URLs to store your files (see _Where
to Store Files_ for more info)
+* Creating files and directories
+* Writing to files
+* Reading files
+* Appending files
+
+## Create a persistent file
+
+Before you can use the File plugin APIs, you must get access to the file
system using `requestFileSystem`. When you do this, you can request either
persistent or temporary storage. Persistent storage will not be removed unless
permission is granted by the user.
+
+When you get file system access, access is granted for the sandboxed file
system only (the sandbox limits access to the app itself), not for general
access to any file system location on the device. For more information about
location-specific URLs, see _Where to Store Files_.
+
+Here is a request for persistent storage.
+
+>*Note* When targeting devices (instead of a browser), you dont need to
use `requestQuota` before using persistent storage.
+
+```
+window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) {
+
+console.log('file system open: ' + fs.name);
+createPersistentFile("newPersistentFile.txt");
+
+}, onErrorLoadFs);
+```
+
+Once you have access, you generally want to use the Cordova file URLs,
like `cordova.file.dataDirectory`, where possible (see _Where to Store Files_).
This will hide implementation details related to the file locations. To use a
Cordova file URL, call `window.resolveLocalFileSystemURL`. The success callback
receives a DirectoryEntry object as input. You can use this object to create or
get a file (by calling `getFile`).
+
+The success callback for `getFile` receives a FileEntry object. You can
use this to perform file write and file read operations.
+
+```
+function createPersistentFile(fileName) {
+
+// Return a DirectoryEntry using Cordova file URLs.
+window.resolveLocalFileSystemURL(cordova.file.dataDirectory, function
(dirEntry) {
--- End diff --
You don't actually have to call `window.resolveLocalFileSystemURL` from
within `window.requestFileSystem`. `window.requestFileSystem` is for getting
access to the sandboxed application-specific storage only.
`window.resolveLocalFileSystemURL` is for arbitrarily accessing storage
(including non-sandboxed storage locations, like a phone's photo folder) and
can be called on its own.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
-
To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org
For additional commands, e-mail: dev-h...@cordova.apache.org
[GitHub] cordova-plugin-file pull request: adding sample section to readme
GitHub user Mikejo5000 opened a pull request: https://github.com/apache/cordova-plugin-file/pull/176 adding sample section to readme removed link to current complete sample, related edits You can merge this pull request into a Git repository by running: $ git pull https://github.com/Mikejo5000/cordova-plugin-file master Alternatively you can review and apply these changes as the patch at: https://github.com/apache/cordova-plugin-file/pull/176.patch To close this pull request, make a commit to your master/trunk branch with (at least) the following in the commit message: This closes #176 commit 2cf6527ec83286e5c8aaa19a055dedc8e53af354 Author: Mikejo5001 Date: 2016-03-29T00:22:49Z readme updates with samples commit ebe57fe3780812d5ce3e5b38423f0c0ac3269ea5 Author: Mikejo5001 Date: 2016-03-29T00:31:01Z readme edits commit 96af5b056357e827d5ec4307af67a714498d5ee5 Author: Mikejo5001 Date: 2016-04-01T21:17:15Z readme updates --- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- - To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org For additional commands, e-mail: dev-h...@cordova.apache.org
