Fly.File Reference - kitkatzecat/fly Wiki

This page serves as a reference for use of the Fly.File.php file, which adds the FLY.FILE include.

This file adds only JavaScript methods for runtime use.

This file has the following Fly include dependencies:


Fly.File adds the object file to the standard JavaScript Fly object (Fly.file). This object has the following methods and properties:


get (method)

Prompts the user to select a file via a dialog box and returns the selected file's fileprocess object, or false if canceled.

/images/Fly.File.get_454_1.png

This method takes the following arguments:

1. callback (function)

The function that is called when the file selection dialog is closed. If the user selects a file, the file (as a fileprocess object) will be passed as the first argument. Otherwise, the first argument will be false.

2. options (object)

Options for the dialog to be opened. May contain these properties:

All properties are optional for the options argument, but the arguments must be ordered in this way when the function is called.

Example call:

Opens a dialog asking the user to choose a file of any type, starting in the ./ directory.

Fly.file.get(function(result) {
	if (result) {
		// You now have a file!
	} else {
		// Failed
	}
}, {path:'./'});

set (method)

Prompts the user to select a folder, name, and (optionally) type for a file via a dialog box and returns the selected file's properties as an object, or false if canceled.

/images/Fly.File.set_454_1.png

This method takes the following arguments:

1. callback (function)

The function that is called when the file selection dialog is closed. If the user selects a file, the file's properties will be passed as the first argument. Otherwise, the first argument will be false.

2. options (object)

Options for the dialog to be opened. May contain these properties:

All properties are optional for the options argument, but the arguments must be ordered in this way when the function is called.

When the user is selecting the file name, the following characters are disallowed:

\ / ' " ? + = & | * : < > , % `

Example call:

Opens a dialog asking the user to select a location, name, and type for a file to be saved. The dialog will open in the directory ./ and will allow the user to select from the file extension types txt, png, or mp3 (in addition to the "Any (*.*)" type, which is always available and lets the user choose any extension).

Fly.file.set(function(result) {
	if (result) {
		// You now have the properties for your new file!
	} else {
		// Failed
	}
}, {path:'./',extensions:['txt','png','mp3']});

dir (method)

Prompts the user to select a folder via a dialog box and returns the selected folder's fileprocess object, or false if canceled.

/images/Fly.File.dir_493.png

This method takes the following arguments:

1. callback (function)

The function that is called when the folder selection dialog is closed. If the user selects a folder, the folder (as a fileprocess object) will be passed as the first argument. Otherwise, the first argument will be false.

2. options (object)

Options for the dialog to be opened. May contain these properties:

All properties are optional for the options argument, but the arguments must be ordered in this way when the function is called.

Example call:

Opens a dialog asking the user to choose a folder, starting in the ./ directory.

Fly.file.dir(function(result) {
	if (result) {
		// You now have a folder!
	} else {
		// Failed
	}
}, {path:'./'});

string (object)

Contains functions useful when manipulating file-related strings.

Note: None of the string functions will trim slashes automatically to avoid mutilating URL protocols.

This object contains the following methods:

name (method)

Takes a string of a path to a file and returns the file's name without its path.

Fly.file.string.name('./users/someone/Media/file.png');
file.png

path (method)

Takes a string of a path to a file and returns the file's path without its name.

Fly.file.string.path('./users/someone/Media/file.png');
./users/someone/Media/

bname (method)

Takes a string of a path to a file or a file name and returns the file's name without its extension. (Similar to the bname property of a fileprocess object)

Fly.file.string.bname('./users/someone/Media/file.png');
Fly.file.string.bname('file.png');
file
file

extension (method)

Takes a string of a path to a file or a file name and returns the file's extension.

Fly.file.string.extension('./users/someone/Media/file.png');
Fly.file.string.extension('file.png');
png
png

trimslashes (method)

Takes a string of a path to a file and returns the same string with all instances of repeating slashes reduced to one. (Similar to the trimslashes method provided by Fly.Core in PHP)

Warning: When using this function, be careful that you aren't removing the double slashes in URL protocols!

Note: None of the string functions will trim slashes automatically to avoid mutilating URL protocols.

Fly.file.string.trimslashes('.//users////someone/Media//file.png');
./users/someone/Media/file.png

write (method)

Transfers data to the back-end system and writes it to the specified file.

This method takes the following arguments:

1. options (object)

The specifications for the file write. May contain these properties:

All properties for the options object are optional since it is cascaded over the default options:

{
	method: 'text',
	content: '',
	file: false,
	overwrite: true,
	progress: function() {},
	ready: function() {}
}

Example call:

Writes the text Hello world! to the file ./Hello world.txt.

Fly.file.write({
	method: 'text',
	content: 'Hello world!',
	file: './Hello world.txt',
	ready: function(status,message) {
		if (status) {
			// Success - the file has been written with the specified contents
		} else {
			// Failure - the file has not been written, error message is in the "message" variable
		}
	}
});

read (method)

Reads data from the specified file in the back-end system and returns it.

This method takes the following arguments:

1. options (object)

The specifications for the file write. May contain these properties:

All properties for the options object are optional since it is cascaded over the default options:

{
	method: 'text',
	file: false,
	progress: function() {},
	ready: function() {}
}

Example call:

Read the contents of the file ./Hello world.txt as text.

Fly.file.read({
	method: 'text',
	file: './Hello world.txt',
	ready: function(result,message) {
		if (!!result) {
			// Success - file contents are now in result variable
		} else {
			// Failure - file could not be read, details are in message variable
		}
	}
});