Hawksworx

The recent release of TiddlyWiki v2.5 included something rather exciting for me: JQuery, the popular Javascript library is now part of the TiddlyWiki core.

This is exciting for a number of reasons.

1. The TiddlyWiki core functions can now use jQuery to perform all manner of DOM inspection and DOM manipulation. We can refactor a ton of code to benefit from jQuery’s blistering Sizzle engine and pass the burden of maintaining lots of utility functions over to those clever jQuery bods. All of which will simplify the TiddlyWiki codebase and ultimately make it easier to read and easier to maintain.
2. TiddlyWiki plugin developers will now be able to make use of jQuery in their plugins. That’s great news for both hardcore plugin developers and people dabbling for the first time. jQuery is elegantly expressive, powerful, and superbly documented. All of this lowers the barriers to entry for a would be developer and smooths the way for exisiting developers.
3. There is a huge wealth of jQuery plugins which can now be utilised by TiddlyWiki. The quality of many of these plugins is tremendously high. Bring ‘em on!

But how does a TiddlyWiki plugin developer get started? How can we bring a jQuery plugin into TiddlyWiki and make it available via a Macro? Let’s take a look at an example.

Fred, my colleague at Osmosoft stumbled upon a plugin which creates a nice navigation structure from an HTML List element. The plugin has lots of examples and documentation and seemed like a good contender for bringing something useful into TiddlyWiki.

To include the plugin, all we need to do is copy it into a tiddler and then tag the tiddler with systemConfig. After saving the file and reloading, the plugin is available for us to use.

With the jQuery plugin availble, we can use it to provide a snazzy UI for any UL or LI elements on the page. The Javascirpt syntax for that is nice and simple:

// Turn the list element with an ID of 'myList' into a funky ListNav
$('#myList').listnav();

This is great, but we want people to be able to call this from TiddlyWiki without having to write Javascript. If we create a TiddlyWiki macro to call this for us, people can easily make a nice NavList anywhere. Let’s make a macro which turns the contents of a tiddler into a NavList like this:

<<listnav TiddlerTitle>>

To make that available, we should create a TiddlyWiki plugin which delivers this macro. We do this in a new tiddler. I created a tiddler called ‘ListNavPlugin’ and once again tagged it with systemConfig so that it becomes code that TiddlyWiki knows to interpret. To start with, let’s just create the macro and ensure that we can invoke it.

 
// create macro object
config.macros.listnav = { 
 
  // Add a handler function to be invoked by <<listnav TiddlerTitle>> 
  handler: function(place, macroName, params, wikifier, paramString, tiddler) {
 
    // do some magic...
    alert("I'm gonna make a funky listnav!");
 
  }
};

To see it working, I created two more new tiddlers. MyFruityList holds a list of items, and ExampleListNav holds a call to the new macro.

Saving the TiddlyWiki file and reloading will make the macro available to call. If we open the ExampleListNav tiddler, we should see our macro called like this:

All good, but not exciting yet. Let’s flesh out our TiddlyWiki macro a bit. We’ll use a TiddlyWiki function to get the text from our desired tiddler and then make a list from it. Where we might once have used some TiddlyWiki utility functions to help us create the HTML elements (like createTiddlyElement), we can now use jQuery’s helper functions to append elements to the document.

 
// create macro object
config.macros.listnav = {
 
  // Add a handler function to be invoked by <<listnav TiddlerTitle>> 
  handler: function(place, macroName, params, wikifier, paramString, tiddler) {
 
    // target tiddler passed in as macro parameter
    var title = params[0];
 
    // read list items from tiddler contents
    var text = store.getTiddlerText(title);
    if(text) {
 
      // generate list
      var items = text.split("\n");
      var list = jQuery("<ul />").attr("id", "listnav").appendTo(place);
      jQuery.each(items, function(i, itm) {
        jQuery("<li />").text(itm).appendTo(list);
      });
 
    }
  }
};

Now we’re getting somewhere. We’ve grabbed each line from our MyFruityList tiddler and used jQuery to turn them into an unordered list.

We can now call the jQuery plugin to render our list as a NavList. The plugin requires a little extra HTML so we can create that, and then call the listnav plugin.

 
// create macro object
config.macros.listnav = {
 
  // Add a handler function to be invoked by <<listnav TiddlerTitle>> 
  handler: function(place, macroName, params, wikifier, paramString, tiddler) {
 
    // target tiddler passed in as macro parameter
    var title = params[0];
 
    // read list items from tiddler contents
    var text = store.getTiddlerText(title);
    if(text) {
 
      // generate nav bar
      jQuery("<div />").attr("id", "listnav-nav").appendTo(place);
 
      // generate list
      var items = text.split("\n");
      var list = jQuery("<ul />").attr("id", "listnav").appendTo(place);
      jQuery.each(items, function(i, itm) {
        jQuery("<li />").text(itm).appendTo(list);
      });
 
      // apply listnav
      list.listnav();
    }
  }
};

When we save our plugin, reload the page and open up our ExampleListNav tiddler, we see the navlist. Cool! Hang on though, it looks a bit rubbish. Not like the examples we saw earlier. We have to include the CSS to style our new navlist. Easy enough, let’s use our TiddlyWiki plugin to create a sylesheet for our new HTML by adding this:

 
// add default styles (adapted from http://www.ihwy.com/labs/downloads/jquery-listnav/2.0/listnav.css)
config.shadowTiddlers.StyleSheetListNav = "/*{{{*/\n" +
  "#listnav-nav { margin: 20px 0 10px; }\n" +
  ".ln-letters { overflow: hidden; }\n" +
  ".ln-letters a { font-size: 0.9em; display: block; float: left; padding: 2px 6px; border: 1px solid #eee; border-right: none; text-decoration: none; }\n"+
  ".ln-letters a.ln-last { border-right: 1px solid #eee; }\n" +
  ".ln-letters a:hover, .ln-letters a.ln-selected { background-color: #eaeaea; }\n" +
  ".ln-letters a.ln-disabled { color: #ccc; }\n" +
  ".ln-letter-count { text-align: center; font-size: 0.8em; line-height: 1; margin-bottom: 3px; color: #336699; }\n" +
  "/*}}}*/";
store.addNotification("StyleSheetListNav", refreshStyles);

And we’re done. The jQuery plugin is turning our boring old list into a dynamic indexed list with navigation. Cool! For extra credit, we can make our jQuery a little more concise. Notice that we call jQuery by name rather than with the common idiom of $. We could simply replace each jQuery with $ in our code and that would work, but beware! There are other Javascript libraries that use the $ shortcut. we don’t want to introduce the possibility of a clash. Luckily, there is a simple way to get around that. All we need to do is wrap our TiddlyWiki plugin in a closure and pass jQuery in as an argument (as explained on the jQuery documentation site). Then we can use whatever shortcut for jQuery in our code that we like. The final code looks like this:

 
(function($) { // set up alias
 
  // create macro object
  config.macros.listnav = {
 
  // Add a handler function to be invoked by <<listnav TiddlerTitle>> 
  handler: function(place, macroName, params, wikifier, paramString, tiddler) {
 
    // target tiddler passed in as macro parameter
    var title = params[0];
 
    // read list items from tiddler contents
    var text = store.getTiddlerText(title);
    if(text) {
 
     // generate nav bar
     $("<div />").attr("id", "listnav-nav").appendTo(place);
 
     // generate list
     var items = text.split("\n");
     var list = $("<ul />").attr("id", "listnav").appendTo(place);
     $.each(items, function(i, itm) {
       $("<li />").text(itm).appendTo(list);
     });
 
     // apply listnav
     list.listnav();
    }
  }
};
 
  // add default styles (adapted from http://www.ihwy.com/labs/downloads/jquery-listnav/2.0/listnav.css)
  config.shadowTiddlers.StyleSheetListNav = "/*{{{*/\n" +
  "#listnav-nav { margin: 20px 0 10px; }\n" +
  ".ln-letters { overflow: hidden; }\n" +
  ".ln-letters a { font-size: 0.9em; display: block; float: left; padding: 2px 6px; border: 1px solid #eee; border-right: none; text-decoration: none; }\n"+
  ".ln-letters a.ln-last { border-right: 1px solid #eee; }\n" +
  ".ln-letters a:hover, .ln-letters a.ln-selected { background-color: #eaeaea; }\n" +
  ".ln-letters a.ln-disabled { color: #ccc; }\n" +
  ".ln-letter-count { text-align: center; font-size: 0.8em; line-height: 1; margin-bottom: 3px; color: #336699; }\n" +
  "/*}}}*/";
  store.addNotification("StyleSheetListNav", refreshStyles);	
 
})(jQuery);

You can explore the finished example in a TiddlyWiki.

Yesterday I was fortunate to be able to make the quick trip over to Paris to attend a meeting of TiddlyWiki enthusiasts at TiddlyParis. Arranged by long time TiddlyWiki community member and Una Mesa stalwart Saq Imtiaz, this event was a great chance to put some faces to the names of some of the TiddlyWiki developers and users whose work I have been enjoying and benefitting from for some time.

Gathering in a funky bar on the Champs Elysees, the 10 of us shared a beer or two and got to talk about what we were all doing with TiddlyWiki and get to know each other a little better.

The spectrum of TiddlyWiki experience was pleasingly broad.

Zap recently found TiddlyWiki and is using it to manage his notes and background material to support the effort in writing a novel. He is also tinkering with TeamTasks and made the observation that once you start experimenting with ways to customise and extend TiddlyWiki, you can easily find yourself absorbed in the endeavor. Ideas spring forth even faster than you can execute them.

At the other end of the spectrum we have Jacques, who has been working with TiddlyWiki since the very early days. Jacques showed us all his TiddlyWiki PIM on his 4 year old tablet PC. The file was well over 3MB in size (something of a beast in TiddlyWiki terms) chock full of content and heavily customised. I mean really heavily customised! Jacques had moulded it to fit his way of working and had borrowed from the best TiddlyWiki adaptations around the web. With advanced workflow management and various task lists, widgets and doohickies, I found it a bit hard to drink it all in, but it was a perfect fit for Jacques and goes everywhere with him. Jacques pledged to make a blank copy available at some point. You’ll need to speak French though as he had also carried out extensive translation.

I was delighted to learn that relative newcomer Pier, whose Google Maps / TiddlyWiki mashup gathers information about popular activities and movements around Paris, chose TiddlyWiki primarily because of its ease of use as a mashup platform. Score! (He was also attracted by the snazzy tiddler animations!)

Loic Dachary revealed several TiddlyWiki resources which have been around for a while, but I had failed to stumble upon. Perhaps targeted at the more techie geeks among us, they were impressive nonetheless. My favorite was TiddlyWiki_CP which is a ruby gem providing a library and a command line interface to copy TiddlyWiki tiddlers to files and vice versa. Incredibly useful for any developer who builds a variety of TiddlyWikis.

I was very keen to meet BidiX who has quietly been producing great TiddlyWiki assets for some time. Recent work includes iTW, the best iPhone TiddlyWiki that I know of. The TiddlyParis edition of iTW went with me in my pocket to help me find the venue and read about the agenda. BidiX is also the man behind TiddlyHome, a lovely and seemingly simple hosted TiddlyWiki resource which he recently deployed to Google App Engine for its next release (which we got to play with, but he insists isn’t quite ready for prime time yet).

For my part I spoke about TeamTasks, which I was happy to learn was being used to some degree by several people around the table. I also answered questions about BTs interest in TiddlyWiki and motives for being involved in such a project and community. I’ll not go over that again here, as it has already been well articulated by several of my colleagues on their blogs.

I went on to talk about a new pet project of mine which, following the TiddlyWiki convention for absurd names, has been dubbed JigglyWiki. (As it turns out, the French accent lends this name much more gravitas due to the soft ‘j’. Marvelous!) JigglyWiki deserves a blog post of its own. For now, through, let’s just describe it as and experiment to explore what TiddlyWiki 3.0 might be like if it were to be developed from the ground up with the use of the jQuery javascript library and adopt an unobtrusive Javascript approach.

JigglyWiki (I can only hear that in a French accent now!) created quite a bit of discussion. Proppy and Loic Dachary were particularly vocal about the potential for a TiddlyWiki implementation benefitting from unobtrusive javascript and built in a modular way with a library such as jQuery. Debate raged about the need for a javascript library to properly manage plugins and dependancies. A topic that I’m sure I will be discussing more in a later post.

My thanks go out to all of the folks I encountered at TiddlyParis. Not only for their passion about TiddlyWiki, but also for making me feel so welcome and for conducting the entire event in English rather than in French which I know required considerable effort from some. For what it’s worth, my French stretched far enough for me to order my meal (which was bloomin’ great) and a few drinks without totally shaming myself. Big thanks also to Saq Imtiaz for putting it all together. When’s the next one?!

A bientôt!

Once upon a time I was resistant to the idea of Javascript libraries. That was due to a couple of things. Firstly, I was comfortable with writing the Javascript for my projects myself and didn’t like the idea of relying on someone else’s code which I couldn’t easily inspect. Secondly, at the time there weren’t really any libraries. Then there were a few, but they were all, well, to be blunt, a bit pants.

That all changed for me when jQuery came along. jQuery is a lightweight, elegant but powerful Javascript library originally developed by John Resig. jQuery provides fast and efficient interrogation and manipulation of the DOM and borrows conventions from CSS and XPATH to provide concise and expressive queries to be constructed. It’s worth checking out if you haven’t already.

TiddlyWiki has been around since before the existence of Javascript libraries and long before jQuery came along, so it was never developed in a way to take advantage of such things. It could easily be argued that TiddlyWiki is itself, a Javascript library since it provides helper functions for many common Javascript tasks. The extent of this library though, is a little limited since it has evolved to serve a single purpose: To drive TiddlyWiki.

Recently I have been longing to experiment with replacing a lot of the TiddlyWiki core with code built to take advantage of jQuery. The idea of developing TiddlyWiki with a Javascript library turns out not to be a new one as similar discussions have occurred in the past and different libraries considered.

I then began to imagine other benefits from reengineering TiddlyWiki from first principles taking advantage of all of the lessons learned over its lifetime.

It became too hard to resist.

Over the course of 2 reasonably long train journeys, I set about building my own version of TiddlyWiki with jQuery at its core. I settled on a number of objectives:

1. To use jQuery to provide the core TiddlyWiki functions.
2. To make the code modular such that the core could be very small and additional functionality could easily be included via bespoke jQuery plugins.
3. To use unobtrusive Javascript.
4. For the document to be sensibly parsed by screen readers and web crawlers.
5. To allow navigation of the document even without Javascript
6. To use HTML and CSS which is valid according to the W3C.
7. To conform to the TiddlyWiki naming convention and adopt a suitably ridiculous working title for the project.

An important thing to note, is that I am not attempting to replace TiddlyWiki. I see JigglyWiki as an experimental prototype to explore ways that TiddlyWiki 3.0 might evolve.

I also hoped to keep this quiet for long enough to allow it to progress to the point that I was happy to reveal a working prototype for general discussion. That proved tricky thanks to my own excitement and the way that gossip spreads around the web and discussion groups!

In its current state, it provides some of the more basic TiddlyWiki functions in terms of displaying tiddlers and allowing editing. It also demonstrates how it might elegantly degrade when CSS or Javascript are not available. Below are a few different build which demonstrate those scenarios.

1. Just the HTML. I’ve not included CSS or any of the Javascript here. The data store is visible and you can navigate the document via the tiddler links.
2. The HTML and CSS. This will function just as the version above, only it will look a bit prettier. In environments where Javascript is not available or is slow to be initialised, this is how things look until the Javascript kicks in.
3. HTML, CSS and Javascript. Now the data store is hidden and the default content is displayed with additional, Javascript dependent functionality included.

I’d love to get comments on this approach. I’d also be very interested to get advise on TiddlyWiki issues that we might be able to avoid if the opportunity to develop this into TiddlyWiki 3.0 really did come about. I’m less interested in bug reports though. This is a very early proof of concept which will contain many bugs and glitches.

You can get to the source of this project via the TiddlyWiki subversion repository

More to come!

After a bit of a hiatus, I’ve recently been concentrating on developing my pet project, teamtasks again. Teamtasks is a simple application built using TiddlyWiki to provide a place to manage your tasks alongside other content in your very own personal wiki.

This little project is by no means new. I have been tinkering with it for quite a while but have been working on other projects so teamtasks has had to sit patiently in the corner and wait for me to get back to working on it.

Rather gratifyingly, quite a few people had seen the early work on teamtasks and expressed interest in using it for all manor of purposes. The attention made me realise that it was time to promote teamtasks from its place in my playground (version 0.3 can still be found there for those keen on glancing in the rear view mirror) to the big time! Or at least, a place of its own. And so getteamtasks.com was born. From there you can download the latest version (v0.4 at time of writing) and configure it to fit your task management habits.

This is an open source project and I’m doing my best to resist the urge to tinker with it until I think that it’s perfect before letting it out into the wild, so you may find things about teamtasks that don’t work perfectly or you just don’t like. If that’s the case, then please let me know, or better yet, fix it and then show me. I’m living by the old “Release early. Release often” mantra here and welcome contributions, in the form of suggestions, bug reports, bug fixes, enhancements, criticism, praise, sticky buns, pats on the back, or hugs.

Along with the new site and new release, there is a new way to get in touch and keep track of developments. Obviously, you can leave your comments here, but now you can also follow teamtasks on Twitter. You’d get to hear about teamtasks developments if you just followed me on Twitter too of course, but then you’d also be subject to other random utterances.

After just a few hours of launching getteamtasks.com, I have already had a nice response. This really helps to keep me motivated and on track. As the project gains a little momentum, it also gains more pairs of hands to do the work. We’ve spent some time here at Osmosoft today planning the next set of enhancements for teamtasks which will soon be listed on the site for you to inspect.

Roll on version 0.5!

Recently, we at Osmosoft have been trying to make good on one of our pledges: To introduce a unit testing framework to TiddlyWiki development.

Along the way we examined several Javascript testing frameworks and found that JSSpec suited our needs quite nicely. JSSpec resembles the popular RSpec testing framework popularly used by Ruby developers.

As a result, I have been dabbling away at writing tests in my favored text editor - the rather lovely Textmate. Since this is a repetitive task, I figured that it was worth creating some helper to speed things along. Textmate offers an easy to make powerful bundles to automate tasks and help you in your code development and so I quickly put together a JSSpec bundle. This simple bundle offers a set of snippets which can act as a quick reference of what methods are available in JSSpec and let you rapidly create your test code. Textmate users can download this bundle and just double-click it to make it available for use in Textmate.

I won’t go into the workings of testing with JSSpec here, rather, you can learn about that at the official site.

Feel free to take this bundle and modify it to fit your purpose. Enjoy.

Last week the entire Osmosoft team visited Paris to attend the LeWeb3 conference. Initially, we had intended to be attending simply as delegates, but as time went by, we decided that we might be able to build something handy to use at the conference, and that perhaps, others might find it useful too.

And so, RippleRap (then dubbed ‘TiddleLeWeb’) was conceived. We considered that building a tool based on TiddlyWiki where you could make notes on the conference and effortlessly share those notes with others, while being shielded from network hiccups, would be cool. To be ready, we had much to do, and little time to do it.

Read the rest of this entry »

Today I humbly release version 0.3 of TeamTasks to the world. TeamTasks is a simple tool for managing tasks and to-do list and is built on Tiddlywiki. Because of its TiddlyWiki foundation, it allows you to intertwine wiki content and task items, in order to build a meaningful set of notes and reminders, in a single, portable file.

Read the rest of this entry »

This week, we celebrated the 3rd Anniversary of TiddlyWiki arriving on the Internet. We were fortunate to be joined at Osmosoft Towers by a number of enthusiastic TiddlyWiki users and developers.

Personally I was excited to put faces to the names of people who I had only so far met in the various TiddlyWiki user groups and chat rooms. I have found that if I have a question about how to achieve something using TiddlyWiki, I could almost always get the answer from someone in one of the groups. Being able to get to know some of these folks has been great. Not only does it make it even easier to engage with them online when I have a stupid question, but also it drives home the fact that work done on TiddlyWiki has real value to real people, and that gives me a huge sense of satisfaction.

Read the rest of this entry »

The new look Osmosoft website is now live at www.osmosoft.com

After posting my initial doodling for this site, I received some great feedback and was keen to get the site built. It remains pretty close to the original design, but with a few deviations.

The site is simply a TiddlyWiki with some custom styling and was nice and easy to put together. I also plan to release the basic style as a theme on www.TiddlyThemes.com so that others can dip into it and use the bits that they like.

As ever, I’d love to here any comments people might have.

Recently, I have been wearing my UI designer hat and exploring ways to present TiddlyWiki in a more approachable way. I have blogged before about being surprised at how easy it is to give a TiddlyWiki site a new flavor, but my recent ventures have attempted to retain more of the existing TiddlyWiki functionality (rather than hiding it away), while providing a simpler and more user friendly view.

I’ll be setting some of this work free before too long, but for now, I thought I’d post a screenshot of my work in progress. You never know, it might generate some ideas via any discussion that ensues.

Some UI elements that I am working on include a revised tab view of the tiddler lists and timeline view. This uses the existing TiddlyWiki macro to display tabbed content, the gradient macro to create a subtle ‘paper’ feeling to the scrollable listing panel, and also the slider macro to make a nice collapsable section that appears across the top of the page.

I’m also planning on adding some large, friendly buttons in the currently blank space in the top panel to provide some help with getting started. I’d love to hear any comments or suggestions about the direction this is taking.

Once this theme has matured a little, I’ll be posting it the growing set of TiddlyWiki themes that can be found at TiddlyThemes.com