Including HTML Files from Other HTML Files, on the File:// System

“I wont be sending an officer because your not in any danger at all. You have obviously just put a blanket on a dog while it is sitting in your car and taken a photo. “

I still have a passion for web apps that run on the file system. It’s an extremely easy development model and extremely flexible. You can send a file (or set of files) to anyone and be confident they can open the files and run your web app, regardless of their operating system and without imposing on them the requirement of setting up a server. Furthermore, they can stick it on a share drive and BAM, guerilla multi-user system. I’ve had the habit long before I developed for TiddlyWiki but my time with TiddlyWiki focused my attention on the benefits and taught me a number of Single-Page App (SPA) hacks which most web developers are still oblivious to.

And let the SPA hacks roll on …

As I start to think about resetting the slideshow framework I’ve been randomly sniping at conferencesrecently, one thing I’d like to do is the idea of a file per Master Slide, containing all of the HTML, JavaScript, and CSS. This is more or less how TiddlyWiki themes work, and a very neat modularisation tactic.

Unfortunately, HTML – bless it – can include JavaScript (<script src="something.js">) and CSS (<link href="something.css"> etc), but not HTML (which would look something like <div src="something.html"> in my dreams). So what are the options for pulling in one HTML file from another HTML file:

  • Server-side includes: We’ve long had server-side includes. I powered my homepage from this less-than-stellar technique for modularisation around 15 years ago. The problem is none too hard to derive from their name. Server, I don’t want one.
  • XMLHttpRequest: We could make a XHR call and actually this is possible from file to file. Unfortunately, Google Chrome (and maybe others?) sees each file as belonging to a separate domain, making it impossible, and other browsers may issue a warning or confirmation, making it obtrusive.
  • File APIs: Again, we could use the magic of $.twFile to read the other file. But this relies on browser-specific hacks and they have to be degraded to a separate Java applet, which requires a proper Java installation, in the case of Chrome, Safari, Opera, and others. Firefox uses Moz-specific API and IE uses ActiveX, which are good but also incur warnings and may be blocked by firewalls. Still, it’s not a bad solution. The extra Java applet is a big downside in TiddlyWiki, because you suddenly need to send around two files instead of one, but here I’m already assuming there’s a bundle of files to be sent around.
  • Outputting HTML inside JavaScript: Since we can read Javascript, we could just spit out the HTML from JavaScript. The benefit here is it works, and works for the most ancient of browsers. But it would require a lot of string manipulation, which would look minging and be unmaintainable, and I massively value elegant code (or at least, the possibility of it). Many times I have wished JavaScript supported Here Docs, but alas, it doesn’t :(. The best you get is a long sequence of lines ending in . Unacceptable. You can also achieve this kind of thing with E4X, but that’s not widely supported.
  • Hiding HTML in JavaScript or CSS: I’ve considered tricks like embedding the entire HTML inside a JavaScript or CSS comment, but the problem is the same reason we need JSONP; when you source a JS or CSS file, your app feels the effects of it, but your code doesn’t get to see the source. I’m still holding a candle for the possibility of some CSS hack, like based on computed style, which would let you trick the browser into thinking the background colour of a button is an entire HTML document or something…which would be worth doing just for the sake of being insanely ace.
  • Or. iFrames.

Thinking it through, I decided iFrames are your friend. You embed the file to be included as a (hidden) child iFrame. This can work in a couple of ways.

The parent could read the DOM directly:

< view plain text >
  1. var dom = document.querySelector("iframe").contentWindow.document;
  2.     document.querySelector("#messageCopy").innerHTML = dom.querySelector("#message").innerHTML;
(The child contains message element, the parent contains messageCopy.)

This works on Firefox, but not Chrome, because Chrome sees each file as belonging on a separate domain (as I said above, wrt XHR). So we need to make a cross-domain call. We could be AWESOME and use the under-loved Cross-Origin Resource Sharing (CORS) capability to make cross-domain XHR calls, but in this case, it doesn’t work because it involves HTTP headers, and we’re doing this with pure files.

The solution, then, is another kind of iFrame technique: Cross-domain iFrames. It’s been possible to do cross-domain iFrame communication for a while, but fortunately, modern browsers provide an explicit “HTML5″ API for cross-domain iframe communication. I tested it in Chrome, and it works. On Files. Yay.

Under this paradigm, “index.html” contains:

  1. <script>
  2.   window.onload = function() {
  3.     window.addEventListener("message", function(e) {
  4.       document.querySelector("#messageCopy").innerHTML =;
  5.     }, false);
  6.    document.querySelector("iframe").contentWindow.postMessage(null, "*");
  7.   };
  8. </script>
  9. <h1>Test parent</h1>
  10. <div id="messageCopy"></div>
  11. <iframe src="included.html"></iframe>

while “included.html” contains:

  1. <script>
  2.   window.addEventListener("message", function(e) {
  3.     e.source.postMessage(document.getElementById("message").innerHTML, "*");
  4.   }, false);
  5. </script>
  6. <div id="message">This is the message</div>

Point your spiffy HTML5 browser to index.html and watch in glee as the message gets copied from included to includer. I wasn’t sure it would work, because certain other things – like Geolocation and Workers – simply don’t work in all browsers against the File:// URI, even though they probably should. (Probably because the browsers keep mappings of permissions to each domain, and these systems assume the domain is served with HTTP(s).)

This technique will also degrade to older browsers using those “pre-HTML5 hacks. (As the Romans used to say, Omnis enim API HTML V, aequivalet HTML V pre-furta..)

So I’m glad this technique works and intend to use it in the future, nicely abstracted with a library function or two.

SPA Hacks: Hacks Emerging From the World of Single-Page Web Apps

This is a permalink for my JSConf.US talk. Full slides are online here:

THE LOST HACKS: Ridiculous browser tricks from the world of single-page Applications

The talk will overview TiddlyWiki and Single-Page Apps, and then cover eight specific hacks:

  • File access without browser extensions
  • Javascript-HTML chameleon files
  • SVG-VML chameleon files
  • Inline SVG
  • iFrame squriting
  • Script islands
  • Embedded images
  • Fragment IDs

I’ll be posting a link to the slideshow notes from here. I’m pleased to say the nascent TiddlySlidy app has been a pleasure to dogfood it in.

[Image credits]

TiddlyWiki Screencast: Forum in 15 Minutes

TiddlyWiki Screencast: Multi-User Forum in 15 Minutes from Michael Mahemoff on Vimeo.

This screencast is how I finished up the 12Days project, as it captures a lot about what I have come to appreciate in TiddlyWiki. It shows how you can do some simple hacking in the browser, in a single-page web app, reusing and configuring existing plugins from the community. And you can then “turn the handle” to deploy it into a multi-user environment, through the magic of TiddlyWeb. The deployment process in the video uses Hoster, which provides lower-level functionality, but it will be even simpler when TiddlySpace is mature.

This is a screencast showing the evolution of a tiddlywiki, starting from a freshly-minted TiddlyWiki downloaded from, and transforming it into a viable multi-user forum. The steps shown in this screencast:
  • Customising the forum’s look-and-feel by updating shadow tiddlers (SiteTitle, SiteSubtitle, ColorPalette, StyleSheet, DefaultTiddlers, MainMenu).
  • Using tags, the list macro, and the newTiddler macro to show and create new topics.
  • Reusing components with backstage (CommentsPlugin, SinglePageMode, TaggedTemplateTweak)
  • Building a custom macro (taggedCount)
  • Transforming into a multi-user forum (Hoster)
  • TWelve Days of TiddlyWiki, TWelve Days of Osmosoft

    I’m going to be moving on from Osmosoft soon. It’s been 18-odd months since joining and 3 years at BT. I’ve had a wonderful time here, worked alongside so much dedicated talent and energetic passion, and learned a ton about working according to the principles of open source, as well as new ways of working and thinking about things in a large enterprise. What I’m doing next is the subject of a subsequent post … this one’s about Osmosoft and TiddlyWiki and a new site I’ve set up for the occasion: 12 Days of TiddlyWiki.

    I have to echo much of Jon Lister’s sentiments. I, too, am extremely grateful to Jeremy and JP for being brave enough to set up Osmosoft. It’s an organisation within BT that works predominately on the public internet and produces open source for everyone to use, but not in the mould of a “pure research outpost” or an “isolated skunkworks initative”. Osmosoft directly supports BT through the applications and components it produces, its involvement in open source policy, and its general involvement in BT’s software community, among other things. We just operate very differently to a conventional IT department. Oh, and we also make world class stock photos …

    To celebrate my time here and to gently encourage myself to get a few things wrapped up, I decided to make a little microsite: 12 Days of TiddlyWiki. It will feature a new product for each of my final 12days at Osmosoft. And of course, it’s dogfooding: it’s powered by TiddlyWiki and if you peek under the RESTful hood, you’ll see it’s just another view into the main Osmosoft server, and could easily be mashed up however you please.

    There’s one more benefit of Osmosoft working in an open source way to mention: Leaving is not leaving. And here I’ll echo another friend, Dion, who mentioned a similar effect when he moved on from the Bespin project … the code’s out there and I’m still able to remain part of the TiddlyWiki community. I had no idea how powerful TiddlyWiki was when I first joined. It’s a story that still needs to be told in full, but the bottom line for me is it scratches plenty of itches, and on that basis, I’ll still be using it and contributing back.

    The Tiddly* Universe Leading Up to TiddlySpace

    There have been a dizzying array of Tiddly* products spun off recently. I’m talking merely about the core infrastructure stuff rather than applications like TiddlyPocketBook. We’re starting to get some convergence within the team, as we’re working on a high-level product called TiddlySpace. It’s basically the manifestation of earlier discussion too.the ideas we were discussing earlier. Similar to WordPress MU or Wikia, you’ll be able to spin off new TiddlyWikis at the click of a button. The server itself is open source, so you can host it in your own enterprise or on your own server. And because TiddlyWiki is nowadays an application framework, not just a wiki thing, spinning off new instances means composing new applications.

    Pretty much all the applications we’re working on right now are intended to run on this infrastructure. Many will run in standalone, file-based TiddlyWiki, as well; i.e. the whole server-sidedness and user authorisation is a completely separate deployment concern. Which is an awesome way to develop. I recently realised we’re about the only people in the world who primarily develop file:// based web apps! That they will magically work as multi-user, server-hosted, apps too is certainly a boon for the Tiddly* model.

    Anyway, what are all these Tiddly* products Osmosoft’s been working on, and how do they lead up to TiddlySpace? Below is the universe of products we’ve been working on – if all this seems horrendously complicated at first glance, note that most users will only ever see one thing: either TiddlyWiki or TiddlySpace, and even that may be invisible to them if they are using certain high-level applications. Here, I’m just describing the various components we’re working on to pave that path. It’ll all be nice for users. Trust.

    TiddlyWiki – This is the original client UI. It’s a web app fitting inside a single HTML file – HTML, CSS and Javascript all together. It can run on a file:/// URI, which means you can store TiddlyWikis on your local drive, a USB drive, or a share drive … or a http:// URI. In the former case, thanks to some very clever and still-obscure browser hacks, you can make edit the TiddlyWiki and save changes. TiddlyWiki is, at its heart, a personal scrapbook, where you can easily gather and manage free-form bits of content (“tiddlers”). However, some of these bits can include CSS or Javascript, meaning that you can actually start building powerful applications with it and using the underlying tiddlers as a kind of scaffolding. These applicatons can be useful for individuals, but we’re still limited to a single user working on their own hard drive. Hence the need for server-side products (see below).

    TiddlyWiki 5 – This is a major in-progress upgrade of TiddlyWiki, a complete rewrite, the biggest overhaul in its 5 year existence. There are some much-requested features: follows graceful degradation principle so that the TiddlyWiki5 presents nicely to search engine bots and users with Javascript turned off; includes rich text editing control; SVG graphics; embedded images (with the IE6-compatible MHTML hack); better readiness for server-side integration (e.g. the possibility to track revisions). And yes, all of this in a single HTML file.

    TiddlyWeb (low-level) – This is new RESTful server-side component we’ve been building at Osmosoft for persistence, where each Tiddler has its own URI; it’s similar to CouchDB and other NOSQL frameworks; the main difference is it provides extreme flexibility on all manner of things like authentication and storage and presentation formats, and will mostly be invisible to users as we’re building higher-level abstractions on top of it. Also, the underlying data model is that of tiddlers, which means a title, text, list of tags, creation/modification info, and key-value fields (many NOSQL frameworks will have similar document models, but none exactly matching the Tiddler data structure that has always been present in the TiddlyWiki client UI). For most people, TiddlyWeb is best considered as a powerful component further down the stack than what you actually interact with. You’d only need to know about it in detail if you were trying to do powerful admin things, or change the code, on something higher-level like TiddlySpace; or if you wanted to build something equivalent to TiddlySpace; or you were trying to use it in a kind of NOSQL server capacity.

    TiddlyWebWiki (low-level) – This is a set of plugins for TiddlyWiki that help it talk to TiddlyWeb. It “hijacks” (intercepts) calls like store.saveTiddler() so that instead of saving to the local drive, it will upload to the TiddlyWeb server.

    TiddlyHoster and TiddlyConsole These products will probably converge. TiddlyHoster is a first-cut at the TiddlySpace concept, an inspiring product mostly built by @cdent and cobbling together various plugins. You can try it out now at It’s a fairly direct exposure of the TiddlyWeb bags and recipes model. TiddlyConsole (formerly TiddlyRecon) is similarly a bag and recipe and user mangement tool, with more emphasis on admin usage than that from end-users. We hope the essence of these tools can be incorporporated into TiddlySpace to support power users.

    TiddlySpace – This is a higher-level web app, building on TiddlyWeb, to make it easy for folks to spin off new multi-user (or single-user) TiddlyWiki instances. This is really the most important piece, and the one everything’s been leading up to, when it comes to Osmosoft’s mission to get all manner of web apps running inside the enterprise, and will hopefully be just as useful for other enterprises as well as ad hoc groups working on the broader internet. With TiddlySpace, you have an application running at for example. You click a “clone” button, type in “CameraGuide”, and suddenly you have a clone of that web app running at The neat thing is that the new space has copies of all the pocketbook tiddlers, which you can happily hack. The application tiddlers are “copied by reference” from a master application space, say, so you will inherit any future changes made to the application. All this sounds complicated, but will be seamless to the user, and is also easy for us to implement while building TiddlySpace, thanks to TiddlyWebs’ flexible bags and recipes model for containment of tiddlers. (See my earlier discussion too.) Pretty much all of TiddlySpace is driven by client-side code TiddlyWiki plugins, connecting to the TiddlyWeb server.

    We’ve spent a while talking about the design of TiddlySpace and tomorrow we have a hackday with the goal of getting a v0.1 running.

    Multi-User TiddlyWiki

    TiddlyWiki MU is what I’m calling – in the absence of an official name – an effort within Osmosoft to pull together a bunch of work into something that will be very useful in the enterprise and beyond. You could also call it “tiddlywiki as a service” or “multi-room tiddlywiki”. Similar to Wikia or WordPress MU, you can spin off a new multi-user instance with a “single click”. This is “MU” in the sense that there’s already a TiddlyWeb-backed TiddlyWiki product (TiddlyWebWiki). The value-add of TiddlyWiki MU (or whatever it ends up being called) is that you can make a new instance of such a thing without being a system administrator and without going through the effort of building it on the server. This is exactly like the way WordPress MU lets you spin off a new blog without having to set up a new instance of WordPress on the server.

    In addition to the ease of spinning off new instances, there’s an important side benefit from this architectural pattern: synergy. From a user’s perspective, they only have one URL to remember/bookmark/share/link; once at that URL, the system can helpfully guide them through the different instances they have access to. Also, it would be possible to make content that’s used across different rooms. For example, give each user a private bag of tiddlers and they could use it to set their global preferences (with the right UI).

    The whole thing is an open-source server, so an enterprise can just download it, deploy it, and let a thousand flowers bloom as users spin off new instances and do what they will. The really important thing here is that tiddlywiki is not just a wiki, but a framework for web apps. Room admins can easily perform customisations like changing the stylesheet; or go so far as coding up Javascript plugins to radically alter look-and-feel. More importantly, they can update the room’s recipe to include a bags of tiddlers sitting elsewhere on the system. That bag might be the TiddlyDocs system for instance, if they are interested in collaborative document publication, or it might be TiddlyGuv if they want an open-source governance system. They can then fine-tune those systems according to their own needs.

    Here is a rich user story (a rich user story is like a regular user story, but it deliberately includes detail that a “pure agile” developer might object to as “getting ahead of yourself” , You-Ain’t-Gonna-Need-It, or unverifiable; while those objections are valid reasons not to use the story as a direct input to coding or task breakdown, and while rich visions are inevitably too premature to turn out into accurate forecasts, they do help to prove you’re heading in the right direction, to motivate user-centric developers like myself, and to illustrate what you’re doing to people outside the project) …

    (cue dream sequence)

    Jimmy is a moderately experienced TiddlyWiki user and wants to make a room for the enterprise’s music club to collaborate on compositions. So he logs into TiddlyWiki MU, hits “New Room”, and creates a room called “musicians”. He then sees the new room – a vanilla TiddlyWiki with a list of users down the side: currently, just Jimmy, with an Admin icon beside his name. He ignores the “Invite Users” button for now so he can concentrate on setting up the room. The groups wants to put out compositions as collective anthologies, so he decides TiddlyDocs will form the basis of this room. Thus, he clicks on “Manage Room” and a lightbox appears. It shows him the technical detail of the room on one side of the dialog – the bags that make up the room’s recipe. And on the other side, he can search and browse for new bags. He navigates to “tiddlydocs” bag and hits the “Add” button beside it. It now appears on the top of the room recipe.

    Dismissing the lightbox and reloading, the “musicians” room is now a vanilla TiddlyDocs. He clicks on the backstage button on the top of the page and edits a few tiddlers – SiteTitle, SiteSubTitle, and ColorPalette, to give the room its own identity. He also needs a way for the participants to enter musical compositions. Luckily, he already has a standalone TiddlyWiki for music composition, with a Music plugin in it. From backstage, he pulls up the Import dialog and uploads the Music plugin from there. For each imported tiddler, there’s a dropdown showing the bags he can import it into (“musicians-config”, “musicians-comments’ etc). He indicates it should go in the musicians-config bag. On reloading the page, he finds something is broken – he can’t add musical notes from the TiddlyDocs editor. It’s time to call a friend …

    He clicks “Invite Users” and up pops a modal dialog where he enters the email address of Dwight Doomore, a TiddlyWiki expert he’s fortunate to know. He checks the “make this user an admin” box and in the optional message area, explains the problem he’s having. Dwight clicks on a link in the subsequent email and he’s up and running inside the slightly broken “musicians” room. Donning his cyber-shades with Matrix-like precision, he proceeds to create a new plugin tiddler and monkey patches the Music plugin functionality so it plays nicely with TiddlyDocs. Then he tests it by writing up the first new composition, pulls up the user admin panel to remove himself from the room, and replies to Jimmy that it’s all taken care of.

    Pleased with the result, Jimmy writes a few compositions, re-arranges them using TiddlyDocs’ tree control, and adds a little text. Instead of using “Invite Users”, he just mails his colleagues the URL of the “musicians” room. They each visit the URL, indicate they wish to join, and a few days later, Jimmy jumps into the user admin panel, where he can accept their requests to join. Now they can all work together on different documents within the one room, and TiddlyDocs provides enough functionality to control how the final copies will be published.

    Six months later, the first “enterprisey musicians” composition book is printed and bound.

    A single TiddlyWiki MU server has the capacity to facilitate a thousand stories like this, each of them with its own unique characters and quirks. There are plugins for voting, blogging, commenting, structured writing, quizzes, graphics, social bookmarking … it will be fun to see how users deal with all that. Most likely, it will follow the usual pyramid structure:

    • Many users will just create a vanilla room – plain old (multi-user) tiddlywiki. Of these, some will just make it a private scratchpad for themselves and never invite anyone at all.
    • Some users will make the room become a vanilla edition of a specialised application for their group to work on. e.g. collaborate on publication-ready docs with TiddlyDocs; collect and annotate websites with Scrumptious; brainstorm and vote on innovations with New Ideas.
    • A smaller number of users will customise the config tiddlers; pull in extra plugins; build new room-specific plugins; or attempt to combine multiple bags.
    • An even smaller number of users will have to deploy a standalone customised server, perhaps deploying a customised edition of TiddlyWiki MU with certain server-side plugins and configurations. This is the kind of thing you might do if using TiddlyWiki MU for a hardcore, full-fledged, 110% uptime, supported to the teeth, enterprise web app. You’d perhaps run a pilot on the regular TiddlyWiki MU server and then perform a (relatively effortless) migration onto its own dedicated server. Or a power user might just hand-configure a TiddlyWeb instance from parts. (This is where we get into “TiddlyWeb as a generic RESTful server” territory.)

    The first case is already well-supported by other wiki platforms, so it’s nice and all being open-source and TiddlyWiki-based, but not really the killer app. The second is really the sweet spot when it comes to optimising user experience in the short term. We’ve spent a lot of time at Osmosoft thinking about how to deploy “TiddlyDocs” as a standalone package. That’s still interesting, but I think it’s a lot more interesting to ask how to deploy TiddlyWiki MU as a standalone package, and then let users go into web app and make a new “TiddlyDocs” instance with one click. The third case is supported by the general TiddlyWeb model and doesn’t need any special optimisation at this stage.

    [There's a thread about some of this stuff on the mailing list, so I've switched off comments to keep the conversation in one place.]

    Embedded Images in TiddlyWiki Under IE6 via MHTML – Proof-of-concept

    tiddlywiki mhtml images (by mahemoff)

    I only came across the MHTML image hack over the weekend, while listening to @jeresig on the new jQuery podcast (incidentally not the only jQuery podcast to be launched in the past week or two).

    The MHTML image hack lets you embed images with text, just like ye olde data: URI hack, but in a way that works for IE6. MHTML is MIME for HTML.

    Of course, I immediately wondered if it could work in a single-page web app like tiddlywiki, and it turns out it can, though my quick exercise still has some problems.

    IE6 TiddlyWiki images demo here

    As I wrote on the demo itself:

    Normally, images are contained in a separate location, pointed at from HTML IMG tags or from CSS background-image properties. However, Tiddlywiki is a style of web app where everything resides in one file. So how to include images?

    The usual hack is to embed data: URIs ( However, no go for IE6 and IE7. Hence, a “newer” technique – newer meaning recently discovered. That is, MHTML (

    I was curious if MHTML worked in single-file HTML pages, reading off a file URI, and to my surprise it does. That said, it’s not perfect at all. Firstly, I had to hard-code the location, because I don’t know how to refer to “the current file” within the MHTML link. (I suppose a workaround would be to output the image file and refer to that with a relative URL, but we lose the benefit of everything being in one file.) Secondly, I played around with various base-64 images and this arrow one (from the demo) was the only that worked :(.

    So it’s a proof-of-concept with many gaps left for the reader to fill!

    Hopefully people play with this further. At 3002 days old and counting, your grandpa’s browser isn’t going anywhere fast.

    InfoBoxPlugin: A TiddlyWiki Plugin for InfoBoxen

    InfoBoxPlugin - Lists tiddlers in a table (by mahemoff)

    G’Day, here’s a new tiddlywiki plugin I’ve been working on: InfoBoxPlugin. It’s based on the equally-monikered infoBox in MediaWiki/Wikipedia, which you’ll see in any article that is marked “current event” or “controversial”, for example, on the big W. I find infoBoxes elegant, as they are unobtrusive enough to let you get on reading the article, and are easily ignored in the same way as web ads, but when you do focus on them, they are clear in meaning and support pattern recognition, with each type of infoBox having its own look and distinct icon.

    The infoBox macro makes infoBoxen that look as shown in the diagram above. In the simplest case, you type this into a tiddler:

    <<infoBox>>This is good stuff – pay attention mkay.>>

    Pretty straightforward. One funniness here is the bracket asymmetry. We’re trying to do something similar to XML tags, what with their start tag and attribs, followed by body, followed by closing tag, so you’d expect to see:

    <<infoBox>>This is good stuff – pay attention mkay.<</infoBox>>

    or sumptink like dat. But one of my lessons was that tiddlywiki has a somewhat unusual convention, enshrined only in the gradient macro to my knowledge, for the former syntax. The only way to do something else would be to refactor or replicate or hijack the core code, and I don’t fancy it, and in any event it would go against the standard already set by gradient. In any event, I was pleased enough when Jeremy showed me the example of the gradient tag, which shows that this kind of “macro body” is even possible, so I settled with that.

    Okay, so that’s nice, you can do a simple message, but where it gets more to the point is where you build up a family of infoBox types for your TiddlyWiki, each having a separate definition tiddler. For example, you will often want a “warning” infoBox to appear in various places. So you make a “warningInfoBox” tiddler, with the following text:

    |heading|Danger, Will Robinson!!!|
    |message|Please follow these instructions carefully.|

    And then in a tiddler, you just write <<infoBox warning>>>> The association between “warning” and “warningInfoBox” is an enforced convention; my macro just appends “InfoBox” to the type you declare. The double-double closing bracket is a consequence of what I said above, combined with the fact that the definition has a pre-defined “message”. This is often going to be what we want, but not always. In fact, all of the fields above are optional, so you could leave out “message” and then the warning macro would have to specify it (if you wanted a message, that is). i.e. <<infoBox warning>>This Is Serious Mum.>> (… because the undeniably-talented, always-controversial, Aussie band This Is Serious Mum – aka TISM – popped into my head as an instructive example for this warning.)

    Some other things to say

    • This plugin is part of a greater effort to pull out the goodies from TiddlyGuv into reusable modules. TiddlyGuv was the first thing I worked on upon joining Osmosoft, and when I looked it at with fresh eyes recently, I realised how much of what I built is just generic TiddlyWiki functionality. I now have a better understanding of what makes an independent TiddlyWiki plugin, and indeed I have a much greater respect for the whole modularity concept in TiddlyWiki, because it really satisfies all the traditional software engineering principles of encapsulation, orthogonality, etc etc in a neat bite-size way, which I will have to explain more about elsewhere. infoBox is the first of several plugins that need to be exorcised from the TiddlyGuv base.
    • The “macro body” thing is actually quite easy – you just call wikifier.subWikify(domEl, ">>"); where domEl is some DOM element. This will keep reading from the end of the macro definition to the next occurrence of >>, and fill domEl with the results of wikifying that content. It would be nice if there was a function to let you just get the string, instead of sticking it in the DOM, but you could still achieve that yourself by shoving it into a hidden element and capturing its innerHTML. The only complication for me was a common one these days of jumping between JQuery-land and traditional DOM-land, since TiddlyWiki now ships with JQuery, but much of the infrastructure has not (yet) been retrofitted to talk JQuery. Once I did a JQuery-to-DOM conversion, it worked fine.
    • Another interesting detour that happened here concerned cross-referencing tiddlers. Something you will want often want to do with infoBoxes is use icons. In a single-file TiddlyWiki, often intended to be offline, the icons would need to be data: URIs. This applies to other plugins too, so I dedcided to look into it a bit. I wanted a way for the “iconURL” slice in the InfoBox definition to either be a regular URL, or a reference to another tiddler containing the data: URI, so as to isolate it away. This led me to learn more about transclusion. With thanks to @FND, and after some experimentation, I found the easiest way was to support linking to sections of another tiddler. See how it works in the demo tiddlywiki, where an “icons” tiddler contains the data:URI icons.

    Wow, I didn’t expect to say so much about what is not a major plugin. It comes at a time when I’ve been making some realisations about tiddlywiki, hence the verbeage.

    SimpleMessagePlugin: Unobtrusive TiddlyWiki Status Message

    To simplify TiddlyGuv message rendering, I made “SimpleMessagePlugin”. It removes the message box 1 second after a message was shown (using displayMessage). In the event another message appears in that time, it appends the message (as it normally does) and extends the message box’s lifetime by a second. In other words, it always closes a second after the last message was shown. The algorithm is a pretty similar throttling deal as Ajaxagram.

    Demo here.

    Latest version from SimpleMessagePlugin.

    Towards A Single Page Application Framework

    Tonight, I was thinking of making a Twitter app to manage my various accounts (I have ~dormant accounts related to projects like @webwait and @listoftweets). The app would be holding username and password details for each of these accounts, so it made sense to build it as a Single Page Application (SPA). This way, a more paranoid user could always keep the app in their local file system, while a less paranoid user could always stick the file on a protected server somewhere, having configured all the username-password details.

    TiddlyWiki is a framework for developing SPAs. One might say it’s the framework for developing SPAs, since there are no prominent alternatives. So my obvious choice was a TiddlyWiki. However, not too long ago, the TiddlyWiki core guys extracted out the secret sauce for SPAs: the ingenius bit of code that saves files without requiring any browser extensions. (I’ve tried to explain this to people and it always leaves even the most brilliant minds a little dumbstruck, but yes TiddlyWiki demonstrates there are pragmatic hacks that can be used to read a file into the browser and then write it out again.) I was keen to explore this saving mechanism, so experimentation ensued.

    The file management techniques ship conveniently in a JQuery plugin, jQuery.twFile. There is a basic demo which lets you edit the entire text and save it. The demo confused me at first – because it was editing the entire body of the file, I wasn’t sure how to translate that info into what I, as an application developer needed. The demo is useful for framework developers understanding the plugin, but less so for application developers. So I extracted it into a demo that is still minimalistic, but closer to the kind of thing you’d do in an application.

    The SPA demo is here.

    Once I did that, I realised what’s required is a SPA framework. In practice, most developers using twFile will be keeping all the HTML, CSS, and Javascript in a single file, so it’s possible to build a higher-level abstraction on twFile, so that developers can focus only on the content. I built the demo in a way that distinguished what was boilerplate framework code and what was application-specific HTML, CSS, and Javascript.

    It was all still in one file, and that’s fine for many developers – you can give the developer the file, tell them “edit these bits”, and they can come up with something functional. I decided to extract things further though, and found the Jinja templating framework to be useful here. Jinja has a concept of template inheritance, so you can easily build up an “include” system. The net effect is I was able to encapsulate SPA logic in a single file, which was passed through a Jinja processor to produce the executable HTML document.

    The basic SPA logic is shown below:

    1. {% extends "spa-template.html" %}
    2. {% block title %}JQuery SPA demo{% endblock %}
    3. {% block css %}
    4.   etc etc
    5.   body { background: black; padding: 0; margin: 0; font-family: Gill Sans, sans-serif; }
    6.   h1 { background: white; color: black; padding: 10px 10px 0; margin: 0; height: 52px; }
    7. {% endblock %}
    8. {% block html %}
    9.   <h1>
    10.   <img id="logo" src="data:image/jpeg,%FFetc etc"/>
    11.     <span id="title">JQuery-SPA Demo</span>
    12.   </h1>
    14.   <div id="main">
    16.     <ol>
    17.       <li>Save this file to your local file system and open your local copy in the browser (using a file:/// URI). The browser might ask for special permission for this document, and you will need to grant it.</li>
    19.       <li>Type your message: <input id="message" value="change me"></input></li>
    21.       <li>Save this page: <input id="saveButton" value="Save" type="button"></li>
    23.       <li>Hit shift-reload to perform a clean reload the page and observe that your message has been saved.</li>
    24.     </ol>
    26.     <h3>What is this?</h3>
    28.     <p>This is a demo of an experimental Single Page Application I am building atop <a href="">jQuery.twFile</a>, the file saving plugin extracted from TiddlyWiki. Forked from <a href="">this twFile Demo</a>. Only tested on Firefox for now.</p>
    30.   </div>
    31. {% endblock %}
    32. {% block javascript %}
    33.     $ = function(text) {
    34.       return text.replace(/<input id="message".*?></input>/,
    35.               '<input id="message" value="'+$("#message").val()+'"></input>');
    36.     }
    37. {% endblock %}

    So it contains separate HTML/CSS/Javascript blocks. Probably not a good engineering practice (though it doesn’t impact on the end-user experience, which is always a single file), but it’s convenient for now. The key SPA logic is here:

    1. <li>Type your message: <input id="message" value="change me"></input></li>
    2.       ....
    3.     $ = function(text) {
    4.       return text.replace(/<input id="message".*?></input>/,
    5.               '<input id="message" value="'+$("#message").val()+'"></input>');
    6.     }

    As an app developer, all you have to do is override $ (which in retrospect should be renamed as it doesn’t actually perform the save). This function receives the text of the file as it was stored on disk when the page loaded. It must then return the text that should be saved to disk. Thus, it must store application state in HTML, probably by performing some kind of substitution.

    Having put this together, I’m keen to proceed with the envisioned Twitter app. It’s not yet clear if there’s any mileage here over a regular TiddlyWiki, but as someone who is more familiar with starting apps from a blank HTML page (or a simple Project Deploy* template), it might end up being a more familiar way to kick an app off. Watch this space.