1
0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-10-30 06:36:17 +00:00
TiddlyWiki5/editions/tw2/source/tiddlywiki/jquery/plugins/doc/twFile.html
2012-11-16 21:20:27 +00:00

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>