Ion.io

Get the path to a data file area on the system for the active user.

NOTE: In the near future, custom Organization and Application names will be configurable. The Organization and Application names currently default to "Sencha" and "Sencha Ion" respectively.

E.g.:

• Mac OS X: /Users/jarred/Library/Application Support/OrgName/AppName/
• Windows: C:/Users/jarred/AppData/Local/OrgName/AppName/
• Linux: /home/jarred/.local/share/data/OrgName/AppName/

Available since: 1.0

Get the path to the desktop area on the system for the active user.

E.g.:

• Mac OS X: /Users/jarred/Desktop/
• Windows: C:/Users/jarred/Desktop/
• Linux: /home/jarred/Desktop/

Available since: 1.0

Gets the path to the documents or "My Documents" area on the system for the active user.

E.g.:

• Mac OS X: /Users/jarred/Documents/
• Windows: C:/Users/jarred/Documents/
• Linux: /home/jarred/Documents/

Available since: 1.0

Gets the path to the home directory on the system for the active user.

E.g.:

• Mac OS X: /Users/jarred/
• Windows: C:/Users/jarred/
• Linux: /home/jarred/

Available since: 1.0

An array of directory paths currently being watched.

Available since: Desktop Packager 1.1

Opens native file chooser dialog.

// Let the user choose the JSON file to open and read.
var result = Ion.io.browseFiles({
    path: Ion.io.userHomePath,
    type: 'open',
    filters: [{
        name: 'JSON Files',
        pattern: '*.json'
    }]
});

if (result.success) {
    var read = Ion.io.readFile(result.value);
    if (read.success) {
        var obj = JSON.parse(read.data);
        // Do something with obj...
    }
}

Filters

On some platforms the file browser dialog supports a list of filters that the end user can use to filter which files are shown in the dialog. Each filter in the list consists of two parts:

• name: Descriptive text that the end user will see.
• pattern: The pattern (String) or patterns (String[]) this filter matches.

Filters can be defined as Objects with the fields name and pattern or as an Array of two parts, the name followed by the pattern String or String[].

For example:

filters: [
    ['Image Files', ['*.jpg', '*.jpeg', '*.png']],
    ['All Files', '*.*']
]

and

filters: [{
    name: 'Image Files',
    pattern: ['*.jpg', '*.jpeg', '*.png']
}, {
    name: 'All Files',
    pattern: '*.*'
}]

both define the same list of filters.

Available since: 1.0

Parameters

• options : Object (optional)

  Object containing the following options:

  • caption : String (optional)

    The title of the dialog window.

    Defaults to: "Open File" or "Save File" based on type

  • defaultValue : String (optional)

    The name of the file that will attempt to be pre-populated as the selected value.

  • filters : Array[]/Object[] (optional)

    Defines the list of filters to provide in the file browser dialog. See above for details.

    Note: Mac OS X will enable selections which match at least one of the provided filter patterns. This is temporary.

    Defaults to: [["All Files", "*.*"]]

  • path : String (optional)

    The initial directory that the user will begin navigating. path will be canonicalized (see Ion.io.canonicalizePath())

  • type : String (optional)

    Whether this is a save dialog (allows a path/value that is non-existent) or an open dialog (the path/value must exist on the file system).

    Defaults to: "save"

Returns

• Object

  Returns an object with the following structure:

  • success : Boolean
    true if the user selected a file. false if the user closed/cancelled the dialog.
  • value : String The full path to the selected file.

Canonicalizes a file system path if necessary.

• "~/" prefix expands to Ion.io.userHomePath()
• "-/" prefix expands to Ion.io.userDataPath()

If no convertable prefix is found, the path passed in as a parameter is returned unmodified. * All Ion.io member functions that take a path as a parameter, call this function internally, so you can pass in paths using the above prefixes.

// Open `config.json` in user's home directory
var config = Ion.io.readFile(Ion.io.canonicalizePath('~/config.json'));

// Can also open the file like this, because `Ion.io.readFile()` calls
// `canonicalizePath()` for you:
var config = Ion.io.browseFiles({path: '~/config.json'});

Available since: Desktop Packager 1.1

Parameters

• The : String

  path to be converted.

Returns

• String

  The canonicalized path.

If fromPath is a Directory: copies deeply all files and directories from fromPath to toPath.

If fromPath is a File: copies the file to toPath.

If the destination directory does not already exist, an attempt to create it will be made.

// Copy dir1 and its contents to dir2, resulting in /path/to/dir2/dir1/<dir1_contents>
if (!Ion.io.copyPath('/path/to/dir1', '/path/to/dir2')) {
    alert('Failed to copy directory!');
}

// Copy dir1 contents to dir2, resulting in /path/to/dir2/<dir1_contents>
if (!Ion.io.copyPath('/path/to/dir1/.', '/path/to/dir2')) {
    alert('Failed to copy directory!');
}

// Copy file to destination path, resulting in /path/to/dir/new_file
if (!Ion.io.copyPath('/path/to/file', '/path/to/dir/new_file')) {
    alert('Failed to copy file!');
}

// Copy file to dir, resulting in /path/to/dir/file
if (!Ion.io.copyPath('/path/to/file', '/path/to/dir/.')) {
    alert('Failed to copy file!');
}

Available since: 1.0

Parameters

• fromPath : String

  The file or directory to copy to toPath. toPath will be canonicalized (see Ion.io.canonicalizePath())

• toPath : String

  The destination path to where fromPath will be copied. fromPath will be canonicalized (see Ion.io.canonicalizePath())

Returns

• Boolean

  Returns whether or not the copy operation finished completely and successfully.

If path is a Directory: deeply deletes all files and folders from path and then deletes path.

If path is a File: deletes path.

// Delete dir completely
if (!Ion.io.deletePath('/path/to/dir')) {
    alert('Failed to delete directory!');
}

// Delete file
if (!Ion.io.deletePath('/path/to/file')) {
    alert('Failed to delete file!');
}

Available since: 1.0

Parameters

• path : String

  The file or directory to delete. path will be canonicalized (see Ion.io.canonicalizePath())

Returns

• Boolean

  Returns whether or not the delete operation finished completely and successfully.

Lists the names of all files and directories under the specified path. This operation is not deep and will only list immediate children of path.

 var items = Ion.io.listDirectory(Ion.io.userDataPath + 'records', { directories: false });
 for (var i = 0; i < items.length; i++) {
     MyApp.loadRecordFromFile(Ion.io.userDataPath + 'records/' + items[i]);
 }

Available since: 1.0

Parameters

• path : String

  The path of the directory to list. path will be canonicalized (see Ion.io.canonicalizePath())

• options : Object (optional)
  • directories : Boolean (optional)

    Whether or not to include directories in the result set.

    Defaults to: true

  • files : Boolean (optional)

    Whether or not to include files in the result set.

    Defaults to: true

Checks whether or not the specified path (file or directory) exists.

if (Ion.io.pathExists('/path/to/file')) {
    Ion.io.deletePath('/path/to/file');
}

Available since: 1.0

Parameters

• path : String

  path will be canonicalized (see Ion.io.canonicalizePath())

Returns

• Boolean

  Returns whether or not path exists.

Reads the entire contents of filePath. If the mode is text, the contents are read as UTF-8 encoded text. If the mode is binary then the contents are read as binary data.

NOTE: Files in UTF-16BE and UTF-16LE formats will be automatically detected and decoded accordingly.

// Let the user choose the JSON file to open and read.
var result = Ion.io.browseFiles({
    path: Ion.io.userHomePath,
    type: 'open',
    filters: [{
        name: 'JSON Files',
        pattern: '*.json'
    }]
});

if (result.success) {
    var read = Ion.io.readFile(result.value);
    if (read.success) {
        var obj = JSON.parse(read.data);
        // Do something with obj...
    }
}

Available since: 1.0

Parameters

• filePath : String

  The path of the file to read.

• options : Object (optional)
  • mode : String (optional)

    The mode in which to read the file, either text or binary.

    Defaults to: "text"

Returns

• Object

  Returns an object with the following structure:

  • success : Boolean
  • data : String/Number[]
    Either a String when mode is text, or a Number[] (one Number per byte) when mode is binary.

Remove a path from the list of watched directories (see Ion.io.watchedPaths and Ion.io.pathChanged).

Available since: Desktop Packager 1.1

Parameters

• path : String

  The path of the directory to stop watching.

Returns

• Boolean

  true if the path was successfully unwatched, false if not.

Unzip a file.

// Unzip the contents of myfile.zip into myfolder
var success = Ion.io.unzip('myfile.zip', '~/myfolder');

Available since: Desktop Packager 1.1

Parameters

• filePath : String

  The path to the zipped file. filePath will be canonicalized (see Ion.io.canonicalizePath())

• path : String

  The path to unzip the file into. path will be canonicalized (see Ion.io.canonicalizePath())

Returns

• Boolean

  true if the operation succeeded, false if it failed.

Add a path to the list of watched directories (see Ion.io.watchedPaths and Ion.io.pathChanged).

Available since: Desktop Packager 1.1

Parameters

• path : String

  The path of the directory to watch.

Returns

• Boolean

  true if the path was successfully watched, false if not.

Writes data to the specified file as UTF-8 encoded text if data is a String, or as binary if data is a Number[].

If the destination directory does not already exist, an attempt to create it will be made.

// Write our temp file that is storing cache
var result = Ion.io.writeFile(Ion.io.tempPath + 'MyApp.cache', JSON.stringify(cache));
if (!result.success) {
    alert('Failed to save cache!');
}

Available since: 1.0

Parameters

• filePath : String

  The path of the file which to write. filePath will be canonicalized (see Ion.io.canonicalizePath())

• data : String/Number[]

  Either a text String or a Number[] (one Number per byte) of data to write to filePath.

• options : Object (optional)
  • append : Boolean (optional)

    true to append data to the end of the file, false to truncate the contents of the file. If filePath does not exist, then it will be created.

    Defaults to: false

Returns

• Object

  Returns an object with the following structure:

  • success : Boolean

Zip a file.

// Zip the contents of ~/myfolder into mydata.zip
Ion.io.zip('mydata.zip', '~/myfolder');

Available since: Desktop Packager 1.1

Parameters

• filePath : String

  The path to where the zip file.

• path : String

  The path to the contents to zip into filePath.

• options : Object (optional)

  Optional parameters

  • append : Boolean (optional)

    If true, the contents of path will be appended to filePath.

  • root : String (optional)

    Path to use as root. The root will be prepended to all of the paths in the zip file so that when the file is unzipped, all of the contents will be unzipped into a folder called root.

Returns

• Boolean

  true if the operation succeeded, false if it failed.