125 lines
3.7 KiB
HTML
Executable File
125 lines
3.7 KiB
HTML
Executable File
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<title>jQuery.twFile</title>
|
|
<link rel="stylesheet" type="text/css" href="styles/main.css">
|
|
</head>
|
|
|
|
<body>
|
|
<h1>jQuery.twFile</h1>
|
|
<p>
|
|
This <a href="http://jquery.com">jQuery</a> plugin provides access to
|
|
the local file system (for documents loaded from a <code>file://</code>
|
|
URI) to load and save file contents from the browser.
|
|
</p>
|
|
|
|
<p>
|
|
The code is based on <a href="http://tiddlywiki.com">TiddlyWiki</a>'s
|
|
self-saving capabilities.
|
|
</p>
|
|
|
|
<p id="TiddlySaver">
|
|
Note that the <a href="http://www.tiddlywiki.com/TiddlySaver.jar">TiddlySaver</a>
|
|
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.
|
|
</p>
|
|
|
|
<h2>Source</h2>
|
|
<p>
|
|
The source code is currently hosted in TiddlyWiki's
|
|
<a href="http://svn.tiddlywiki.org/Trunk/core/jquery/plugins/jQuery.twFile.js">Subversion repository</a>.
|
|
</p>
|
|
<p>
|
|
<a href="http://groups.google.com/group/TiddlyWikiDev/">Feedback</a> is welcome.
|
|
</p>
|
|
|
|
<h2>API Summary</h2>
|
|
<ul>
|
|
<li>
|
|
<p><code>$.twFile.load(filePath)</code>: load contents from file</p>
|
|
</li>
|
|
<li>
|
|
<p><code>$.twFile.save(filePath, content)</code>: save contents to file</p>
|
|
</li>
|
|
<li>
|
|
<p><code>$.twFile.copy(dest, source)</code>: duplicate existing file</p>
|
|
<p><strong>N.B.:</strong> This is not supported on all browsers.</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<code>$.twFile.convertUriToLocalPath(filePath)</code>:
|
|
normalizes specified absolute file path
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
<strong>N.B.:</strong> All file paths must be absolute (e.g.
|
|
<code>/tmp/foo.txt</code> or <code>C:\temp\foo.txt</code>).
|
|
</p>
|
|
<p>(full documentation in the code comments)</p>
|
|
|
|
<h2>Limitations</h2>
|
|
<ul>
|
|
<li>
|
|
plugin unavailable until
|
|
<a href="http://docs.jquery.com/Events/ready">document.ready</a>
|
|
handlers have completed
|
|
<p>
|
|
Since the TiddlySaver applet cannot be injected synchronously
|
|
into the document, this is done asynchronously during
|
|
<code>document.ready</code> processing.
|
|
</p>
|
|
<p>
|
|
This means that the plugin is not guaranteed to work properly
|
|
until after all these handlers have completed.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
currently unreliable UTF-8 support on Internet Explorer
|
|
<p>
|
|
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.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h2>Internals</h2>
|
|
<p>
|
|
Internally, the plugin uses four separate drivers to implement the functionality on different browsers:
|
|
<ul>
|
|
<li>
|
|
<code>activeX</code>: uses the <code>FileSystemObject</code> built into Internet Explorer 5 and above
|
|
</li>
|
|
<li>
|
|
<code>mozilla</code>: uses the XUL libraries built into Firefox
|
|
</li>
|
|
<li>
|
|
<code>tiddlySaver</code>: uses a custom Java applet that works on Safari, Chrome and Opera
|
|
</li>
|
|
<li>
|
|
<code>javaLiveConnect</code>: uses an ancient (and slow) binding technology to call Java runtime library routines directly - only works on Opera
|
|
</li>
|
|
</ul>
|
|
</p>
|
|
|
|
<h2>Demo</h2>
|
|
<p>
|
|
Download <a href="twFileDemo.html">this document</a> (and
|
|
<a href="#TiddlySaver">TiddlySaver</a> if necessary) and open it from
|
|
the local disk.
|
|
</p>
|
|
<p>
|
|
This demo illustrates self-saving capabilities by passing
|
|
<code>document.location.href</code> to <code>$.twFile.convertUriToLocalPath</code>,
|
|
using the return value in load and save functions.
|
|
</p>
|
|
|
|
</body>
|
|
|
|
</html>
|