Note: An alternative skin, TW4MW (work in progress), is available from the user preferences.

TiddlyWiki Community Wiki

This page explains the rationale and plan for integrating jQuery into TiddlyWiki.

[edit] History

TiddlyWiki includes big swathes of code that smooth out the differences between different browsers. For example, the doHttp function neatly wraps up the browsers native XMLHttpRequest, hiding some of the peculiar incompatibilities. Similarly, the setStyleSheet function that applies a CSS stylesheet contains separate code paths for different browsers. Much of this code is completely generic, but because it's TiddlyWiki-specific it's also rather brittle.

In the time since TiddlyWiki was first published, we've seen the rise of several standardised JavaScript libraries that smooth out these browser quirks, and typically also include features to make the DOM easier and more efficient to work with. Leading examples are jQuery, Dojo, Prototype and Mootools. At various times in the past, the TiddlyWiki community has considered adopting one of these libraries to replace TiddlyWiki's homegrown code. Now that these libraries have stabilised and become pretty much commoditised, we believe that it is appropriate to revisit the issue.

[edit] Why Use a Standard JavaScript Library?

• allows us to reuse existing work on the intricacies of browser quirks (TiddlyWiki's own code has far fewer eyeballs on it)
• makes it easier for developers familiar with that library to work on TiddlyWiki
• allows us to benefit from more sophisticated libraries of UI widgets that come with each library

[edit] Why Choose jQuery (and not Dojo/Prototype/Mootools etc.)?

• jQuery has a clear, disciplined scope (unlike say Dojo) which means it's stayed small and lean
• the jQuery chaining idiom has turned out to be cool and productive
• the jQuery community is booming, and has generated an impressive library of plugins and themes etc

[edit] jQuery Integration Steps

• make jQuery available via the window.jq global variable
• replace calls in the core to certain TiddlyWiki DOM-related functions with the equivalent calls to jQuery
  For example, find all calls to doHttp and replace them with ajax. equivalent from jQuery
• re-implement shorter versions of certain TiddlyWiki functions to utilise jQuery
  For example, story.createTiddler does a bunch of DOM manipulation that would be better done with jQuery
• re-implement all event handlers in the core to use jQuery
• re-implement certain TiddlyWiki functions as jQuery plugins
  For example, setStylesheet doesn't exist in jQuery, but could be packaged as a jQuery plugin for wider consumption/testing etc
• provide a mechanism for invoking compatible jQuery plugins directly from wikitext
  For example, a new <<jQuery ...>> macro that allows any jQuery plugin to be invoked

[edit] What Else?

It would also be extremely cool to copy the chaining paradigm from jQuery. Specifically, there might be a window.tw object such that:

tw("HelloThere", "MyTiddler") // returns a map of the two named tiddlers
tw({ tag: "systemConfig" }) // returns a map of tiddlers tagged "systemConfig"

And then there would be chaining functions like:

.display() // display a tiddler
.close() // close a tiddler if it is displayed
.meta({ modified: "13 Dec 2008", modifier: "Simon" }) // modify the metadata of all the matching tiddlers

Further possibilities:

• use custom events to avoid the need for hijacking core functions
• improve the plugin contract
• unify commands and macros
• etc.

[edit] What about jQuery UI?

jQuery UI is a library of themeable UI components built on top of jQuery, including tabs, accordions, date pickers etc. TiddlyWiki has its own implementation of some of these things at the moment, but it remains to be seen whether its usage is high enough to warrant the inclusion of jQuery UI in every instance of TiddlyWiki.

TiddlyWiki 2.5.0 will be a simplistic release without any core changes apart from the jQuery integration - the actual refactoring (along with the usual fixes/enhancements) will begin with release 2.5.1.