Fly.File Reference - kitkatzecat/fly GitHub 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.CORE
FLY.COMMAND
FLY.WINDOW

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

get
set
dir
string (collection of methods)
write
read

`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.

Defaults to function() {}

2. `options` (object)

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

path - path to folder, starting directory when dialog is opened
- %-variables, keywords, etc. are supported
- Defaults to %FLY.USER.PATH%
types - array, types of files to show in the dialog when the user is selecting
- Accepts file type extensions (txt,png,etc.) as well as MIME types (image/,text/)
  - MIME types use fuzzy matching, so incomplete types such as image/ will match any image type
- The "Any (*.*)" options is always available, allowing the user to bypass type filtering, so applications should still check if the file returned is a supported type
- Defaults to "All Supported Types (...)" (matches any of the provided extensions or MIME types) if types are provided, or "Any (*.*)" if none are provided

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.

Defaults to function() {}
The file's properties, if passed, will be passed as an object with the following properties:
- path - the path to the folder selected by the user, in relative form (./)
- file - the path to the file selected by the user, in relative form
- name - the name of the file selected by the user, including the extension
- extension - the extension for the file selected by the user, or blank if none
  - It is possible for this field to be blank but an extension still specified in the other fields, such as if the user selects the "Any (*.*)" option but types their own extension at the end of the file name

2. `options` (object)

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

path - string/path to folder, starting directory when dialog is opened
- %-variables, keywords, etc. are supported
- Defaults to %FLY.USER.PATH%
name - string, the default name for the file to be shown in the dialog's text box
- Defaults to "Untitled"
extensions - array, file extensions for file to be saved
- User can choose between any of the given extensions
- No extension (represented as "Any (*.*)") is always an available option
- Defaults to the first in the array, or none if none are given
- If the user gives a valid file name with the chosen extension at the end, the extension will not be appended (so that it does not appear twice)
confirmOverwrite - true/false, whether or not to confirm with the user before submitting a filename that already exists
- Defaults to false

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.

Defaults to function() {}

2. `options` (object)

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

path - path to folder, starting directory when dialog is opened
- %-variables, keywords, etc. are supported
- Defaults to %FLY.USER.PATH%

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:

method - string, the method that the content is encoded in
- Can be any of the following: (On the way - more encoding types)
  - text - content is encoded as plain text, no decoding will be necessary
  - base64 - content is encoded as base64, will be decoded before writing
    - When encoding as base64, data type strings (such as data:image/png;base64,) are not necessary and, if included, will be filtered out by the writer
    - File type is assumed from content and file name extension
- Defaults to text
content - string, the content to be written to the file
- Will be processed for writing based on the method specified in the method property
file - string, the file to write
- Supports %-variables and relative paths
- All directories on the path to the file must exist
overwrite - bool, if the file exists: true to overwrite and false to not overwrite
progress - function, called periodically as the data is transferred
- Receives the following arguments (listed in order):
  1. percent - number, the percent progress of the data transfer
  2. loaded - number, the amount of data transferred so far (in bytes)
  3. total - number, the total amount of data to be transferred (in bytes)
- Defaults to function() {}
ready - function, called when the file write has completed (call does not mean write was successful)
- Receives the following arguments (listed in order):
  1. status - bool, true if the write succeeded, false if not
  2. message - string, a description of the status; "Success" if true, an explanation of the error if false
- Defaults to function() {}

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:

method - string, the method that the content is encoded in
- Can be any of the following: (On the way - more encoding types)
  - text - content is returned as plain text
    - Recommended for text-only formats
  - base64 - content is returned as base64, will need to be decoded before working with
    - Recommended for binary formats
    - When encoding as base64, data type strings (such as data:image/png;base64,) are not returned with the contents
- Defaults to text
file - string, the file to read from
- Supports %-variables and relative paths
progress - function, called periodically as the data is transferred
- Receives the following arguments (listed in order):
  1. percent - number, the percent progress of the data transfer
  2. loaded - number, the amount of data transferred so far (in bytes)
  3. total - number, the total amount of data to be transferred (in bytes)
- Defaults to function() {}
ready - function, called when the file read has completed (call does not mean read was successful)
- Receives the following arguments (listed in order):
  1. result - contents of file, type depends on method
    - If successful, for each method:
      - text - string, text contents of file
      - base64 - string, base64-encoded contents of file
    - false if read fails
  2. message - string, a description of the status if read failed (not passed if read succeeded)
- Defaults to function() {}

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
		}
	}
});

Fly.File Reference - kitkatzecat/fly GitHub Wiki

get (method)

1. callback (function)

2. options (object)

Example call:

set (method)

1. callback (function)

2. options (object)

Example call:

dir (method)

1. callback (function)

2. options (object)

Example call:

string (object)

name (method)

path (method)

bname (method)

extension (method)

trimslashes (method)

write (method)

1. options (object)

Example call:

read (method)

1. options (object)

Example call:

`get` (method)

1. `callback` (function)

2. `options` (object)

`set` (method)

1. `callback` (function)

2. `options` (object)

`dir` (method)

1. `callback` (function)

2. `options` (object)

`string` (object)

`name` (method)

`path` (method)

`bname` (method)

`extension` (method)

`trimslashes` (method)

`write` (method)

1. `options` (object)

`read` (method)

1. `options` (object)