# jQuery.twFile

This jQuery plugin provides access to the local file system (for documents loaded from a `file://` URI) to load and save file contents from the browser.

The code is based on TiddlyWiki's self-saving capabilities.

Note that the TiddlySaver applet is required on Opera and WebKit-based browsers (Safari, Chrome). The applet has to be present in the same folder as the respective HTML document.

## Source

The source code is currently hosted in TiddlyWiki's Subversion repository.

Feedback is welcome.

## API Summary

- `$.twFile.load(filePath)`: load contents from file

- `$.twFile.save(filePath, content)`: save contents to file

- `$.twFile.copy(dest, source)`: duplicate existing file

  N.B.: This is not supported on all browsers.

- `$.twFile.convertUriToLocalPath(filePath)`: normalizes specified absolute file path

N.B.: All file paths must be absolute (e.g. `/tmp/foo.txt` or `C:\temp\foo.txt`).

(full documentation in the code comments)

## Limitations

- plugin unavailable until document.ready handlers have completed

  Since the TiddlySaver applet cannot be injected synchronously into the document, this is done asynchronously during `document.ready` processing.

  This means that the plugin is not guaranteed to work properly until after all these handlers have completed.

- currently unreliable UTF-8 support on Internet Explorer

  The plugin is designed to work with UTF-8 encoded text files. However, support in Internet Explorer is broken, and can only reliably save files that are encoded with the ANSI subset of UTF-8. In the case of HTML files, this problem can often be avoided by using HTML entity encodings.

## Internals

Internally, the plugin uses four separate drivers to implement the functionality on different browsers:

- `activeX`: uses the `FileSystemObject` built into Internet Explorer 5 and above
- `mozilla`: uses the XUL libraries built into Firefox
- `tiddlySaver`: uses a custom Java applet that works on Safari, Chrome and Opera
- `javaLiveConnect`: uses an ancient (and slow) binding technology to call Java runtime library routines directly - only works on Opera

## Demo

Download this document (and TiddlySaver if necessary) and open it from the local disk.

This demo illustrates self-saving capabilities by passing `document.location.href` to `$.twFile.convertUriToLocalPath`, using the return value in load and save functions.