PhoneGap - File System Actions Action Javascript
Description
The PhoneGap - File System Actions Action Javascript allows you to perform actions on the file system of the mobile device in your Cordova application.
Discussion
PhoneGap - File System Actions Action Javascript makes working with files in the mobile device file system easier in a Cordova application. When you choose this action, you can select from the following list of file system actions:
Get Directory Contents
Gets the contents of the directory on a mobile device. When the directory has been obtained, the onComplete callback function is called. If an error occurs, the onError callback function is called.
The onComplete callback function is passed an array. The array has objects for each item in the directory. The item object has these properties:
- fullPath
The full path of the file.
- isFile
A true or false value indicating if the entry is a file (true) or a directory (false).
- display
The fullPath followed by either [F] or [D] indicating if the entry is a file or directory.
Get Directory Contents (Recursive)
Similar to Get Directory Contents, but recurses into directories to get the contents of all child directories. See [Get Directory Contents] for more information.
Create Directory
Creates a directory on the mobile device's file system.
Remove Directory
Deletes a directory from the mobile device file system. For example if you specify 'dir1/dir2' as the name of the directory to remove it will remove 'dir2'.
Remove Directory (Recursive)
Removes a directory recursively. For example, if you specify 'dir1/dir2' as the name of the directory to remove, it will remove both 'dir1' and 'dir1/dir2'.
Create File
Creates a new text file. The filename can include a full path (e.g. dir1/dir2/file.txt). The directory structure for the target file must exists. After the file has been created the onSuccess callback is called. If the file was not created, the onError callback is called.
Delete File
Deletes a file. The filename can include a full path (e.g. dir1/dir2/file.txt). After the file has been deleted the onSuccess callback is called. If the file was not deleted, the onError callback is called.
File Exists
Checks if a file exists. The filename can include a full path (e.g. dir1/dir2/file.txt). The onSuccess callback is called if there were no errors. Your code can refer to the 'flagExists' variable which will be true (file exists) or false (file does not exist). If there was an error in trying to check the file, the onError callback is called.
Read File
Reads a text file. The filename can include a full path (e.g. dir1/dir2/file.txt). The onSuccess callback is called if there were no errors. Your code can refere to the 'data' variable which will be the file contents. If there was an error in trying to read the file, the onError callback is called.
Get File System URI for Legacy Persistent Storage
Gets the URI for the legacy persistent file system.
All of the actions defined in this builder use the Legacy Persistent File Storage location. If you want to use the newer PhoneGap - File System Actions (File URI Based) to work with any files or directories created by the actions exposed in this genie you will need the URI of the legacy file system.
All actions are performed asynchronously. For each action you specify the Javascript to execute once the action has successfully completed. If the action fails, the Javascript you specify for the on failure action is executed.
Because the actions are asynchronous, you cannot simply define an Action Javascript that calls two file system actions sequentially. For example, assume that you defined an Action Javascript that did this
Create a new directory
Write a file to the new directory
This would likely fail because the second action (write a file to the new directory) would be executed immediately after the first action (before the new directory had actually been created).
In order to make the above work, the second action (write a file) needs to be called in the first action's onSuccess function.
The asynchronous nature of file system actions makes it tricky to write complex scripts that perform many file system actions.
In the above example, you would need to convert your Action Javascript to text mode and the rearrange the code.
For example, assume you defined the above two actions using Action Javascript. Once you converted to text mode your code would look like this:
{dialog.object}.phoneGapCreateDirectory('dir1', function() { //ok}, function() { //fail } );
{dialog.object}.phoneGapCreateFile('dir1/file1.txt','some data',function() { //ok }, function() {//fail },false);To re-organize the code so that the write file action happens after the new directory has been created, paste the action into the create directory's onSuccess function:
{dialog.object}.phoneGapCreateDirectory('dir1', function() {
//ok
{dialog.object}.phoneGapCreateFile('dir1/file1.txt','some data',
function() { //ok },
function() {//fail },false);
}, function() { //fail } );See Also