File loading

All file loading in xJSFL is handled through xjsfl.file.load(), which has the following advantages over using FLfile:

1. Different types of file (settings, libraries, etc) can be found in the framework structure automatically
2. Absolute or relative paths can be used
3. Platform or URI-format paths can be used
4. {placeholder} variables can be used in path names
5. XML files are returned as actual XML objects
6. Errors are handled by the framework

The end result is cleaner code and a more flexible way of working with URIs or paths. Here are 5 examples of loading the same file:

Load an absolute path

xjsfl.file.load('d:/projects/xJSFL/user/config/settings/snippets.xml');

Load an absolute URI

xjsfl.file.load(xjsfl.uri + 'user/config/settings/snippets.xml');

Automatically find a file in the framework structure

xjsfl.file.load('config/settings/snippets.xml');

Automatically find a particular type of file in the framework structure

xjsfl.file.load('snippets.xml', 'settings');

Use a placeholder variable

xjsfl.file.load('{xjsfl}user/config/settings/snippets.xml');

Automatic file-finding

As you've seen in the examples above, xJSFL seems to be able to magically find files in the framework structure when only a partial path to a file is supplied:

xjsfl.file.load('config/settings/snippets.xml');

This is because xJSFL has a set of rules it follows in order in cases of relative paths:

1. It looks first in the user folder:
1. xJSFL/user/...
2. If not found, it then looks in each of the installed modules paths:
1. xJSFL/modules/ModuleA/...
2. xJSFL/modules/ModuleB/...
3. xJSFL/modules/ModuleC/...
3. Finally it looks in the xJSFL core:
1. xJSFL/core/...

If the file is found, it is loaded and the contents returned if necessary, if not, the method returns undefined.

The purpose of this is to two-fold:

1. To place the focus on loading files, rather than building URIs
2. To allow settings files to consecutively override each other in favour of core > modules > user.

URI juggling

Internally, Flash uses a special URI format to handle paths and files transparently between operating systems:

var file = 'file:///drive|some/path/to/file/with%20spaces%20in%20the%20name.txt';

Whilst this is great for Flash, it's fairly cumbersome for the average developer, and using the native methods to convert to and from URI format is tedious and makes debugging file paths more difficult than it should be.

xJSFL allows you to supply paths in whatever format suits you, and will convert internally to URI format. This includes:

• xjsfl.file.load()
• xjsfl.file.find()
• File and Folder classes
• Config class

xJSFL also has a couple of utility methods to help you build URIs or paths.

xjsfl.file.makeURI()

xjsfl.file.makeURI() is the same method used internally by xJSFL to build paths, and it includes the following features:

• The following folder {placeholder} variables are replaced:
• {xjsfl} - the xJSFL/ folder
• {core} - the xJSFL/core/ folder
• {modules} - the xJSFL/modules/ folder
• {user} - the xJSFL/user/ folder
• {flash} - the user's Flash Configuration/ folder
• {swf} - the user's Flash Configuration/WindowSWF/ folder
• Relative paths are resolved to the xJSFL root
• Windows backslashes are replaced with forward slashes
• Erroneous multiple slashes are replaced with single slashes
• Ancestor  paths (../) are resolved
• Another file can be used as the context for finding the supplied path

The last point is particularly useful, as you can find files relative to other files, like so:

var uri = xjsfl.file.makeURI('../a file one level up.txt', fl.scriptURI);

xjsfl.file.makePath()

xjsfl.file.makePath() is the opposite of makeURI() and converts URIs to platform paths, with the addtional option to shorten core paths for debugging purposes:

xjsfl.file.makePath(fl.scriptURI, true); // xJSFL/user/jsfl/some-file.jsfl

File and Folder classes

The last weapon in the xJSFL file handling arsenal is proper File and Folder classes.

Instead of mucking about with FLfile methods, you can now just create a new File or Folder object and call methods and properties on it. File and Folder objects are instantiated simply by passing in any of the path formats specified above.

var file = new File('user/temp/text.txt');

Once you have a reference to the file, you can save, read, move or copy as you would a normal file:

var contents = file.copy('user/temp/copy.txt').write('I am a copy').contents;

Folders are similar, with the contents property returning an Array of File and Folder instances:

var contents = new Folder('user/temp/').contents;
Output.list(contents);

List: Array (depth:1, objects:0, values:2, time:0.0 seconds)
------------------------------------------------------------------------------
array => Array
	 0: "[object File name="text.txt"]"
	 1: "[object File name="copy.txt"]"

For a full breakdown of all File and Folder functionality see the Filesystem section of the API reference.

Next steps

• Core functionality