Wednesday, March 5, 2014

TiddlyWiki 5 - How Does This Work?

A few years ago, I wrote a two part tutorial on using TiddlyWiki (part 1 and part 2). Time marches on, and there's a new version of TiddlyWiki available in beta form, TiddlyWiki 5. I decided it was time to check it out, because it's pretty and modern and has a huge amount of functionality out of box. This post is an ongoing collection of summary notes about my experiences switching over to TW5 from classic. It'll be updated as I work through various features.

To drive this, I'm going to be keeping all my notes on my Nameless Coast sandbox project in TW5, and I'll be hitting the features covered in those old tutorials, since they're what I use for this type of project.
Get It
This is easy. Go to http://tiddlywiki.com/ and follow the instructions. I'm going to be working in Chrome, so I've set it up to always prompt for a save location, which works for me. I used to use Firefox, but recent versions have felt very sluggish to me, so I'm sticking with Chrome for now.
Useful Links
Startup Features
  • Backstage bar - replaced with the nicely packaged settings cog on the right.
  • Title area - moved to top right above the side tabs and settings / search buttons.
  • MainMenu - gone! Looks like we can add our own sidebars though, so we'll try that.
  • Tiddlers - now called story area (I guess). Tags are a little more fiddly, requiring a button click. Pretty color tags though, which is nice. Wonder if I can change them?
Sidebar Menu
So, first thing, I want my Main Menu back, so let's try to build a custom sidebar tab. According to TW5 Mall we just create a tiddler and tag it with $:/tags/SideBar and that works. Since this new tiddler is just a tiddler, we can put whatever we want in there too.

Most of the sidebar stuff is pretty similar to classic, lists of recent, missing, orphans, and system tiddlers. There's a convenient shortcut list to open tiddlers too, which is nice.

Default Tiddlers
What shows on startup is now set via Control Panel / Basics: Default tiddlers. Easy. I'm leaving GettingStarted in for now, and not messing with the weird last line. Instead, I'm going to add a master [[Nameless Coast]] tiddler to this section. Now we restart... Oh, that [!is[system]sort[modified]limit[25]] line opens the last 25 non-system tiddlers too.

Self-linking Tiddlers
One thing I do all the time is self-link tiddler titles, meaning the title is a link to the containing tiddler. This is highly useful for working on a tiddler that's transcluded within another. It used to be:
    <<view link title>>
Now it seems this is the way:
    <$link><$view field="title"></$view></$link>
I can live with that.

Markup
  • Headers: Still the same !, !!, or !!!.
  • Lists: Still * or # for unordered / ordered lists. Looks like nesting is the same too.
  • Bold & Italic: Same.
  • Links: [[This Still Works]] [[So Does|This]]
Transclusion
Used to be:
    <<tiddler [[Some Tiddler]]>>
Now it's:
    {{SomeTiddler}}

Note that square brackets within curly brackets don't work. If you use spaces in tiddler names like I do, then {{Some Tiddler}} does transclusion as you expect.

Automatic Tag Lists
I used tags extensively, but once you hit a couple hundred tiddlers with one tag (like the 'turn' tag in my Labyrinth Lord campaign wiki), the pop-up list is a little unwieldy. You can easily create a list of all tiddlers with a tag (turn in this case) like this:
    <<list-links filter:"[tag[turn]] +[sort[title]]" >>
The +[sort[title]] bit is an optional sorting field.

Update: To take this one step further, create a tiddler with the same name as a tag (easy, since the tiddler list sidebar includes an option to open a tag-named tiddler), Then use the following:
    !! <$link><$view field="title"></$view></$link>
    <<list-links filter:"[tag<currentTiddler>] +[sort[title]]" >>
The new tiddler will always be the first entry in the tag pop-up list, and it contains a list of all tiddlers with the given tag. Note the use of <currentTiddler>. The angle brackets treat their contents as a variable as use its value. The variable currentTiddler always contains the name of the current tiddler (duh).

More Tagging
If you create a tiddler for each tag you use, add a new tag named tag, and use the technique above to create a tiddler named tag listing all tags. You can then create an automated table of contents like so:
    <div class="tc-table-of-contents">
    <<toc "tag">>
    </div>
This creates a list of links to each tiddler tagged with tag, which is all the tags in your wiki. For each entry, it recursively lists items tagged with those names. If you're thorough with your tagging, that's pretty much everything in your wiki. Add this bit to catch all untagged tiddlers:
    <$list filter="[!is[system]] +[!has[tags]]" type="ul"/>
The end result is a complete listing of your wiki's contents.

Title Lists
I was playing around with filtering and found this, which may or may not be useful.
    <<list-links filter:"[regexp[Batch]] +[sort[title]]" >>
That creates a list of links (just like automatic tag lists) that includes all tiddlers with "Batch" in the title. In my case, it's all my beer recipes since they're all titled Batch X - Recipe Name.

Obviously, you can sub in a regular expression to match your own title conventions.

Cloning
Hey, no more code-block cut paste. There's an actual CLONE button:
    <$button message="tw-new-tiddler" param=<<currentTiddler>>>Clone It</$button>
Yeah, that's going in every tiddler ever written.
Update: And now there's a built-in clone button, so this isn't even needed.

Fields
Each tiddler can have fields added to it, which are named text bits. Then you can use the field name as a reference elsewhere to get to the text associated with it. I'm still trying to figure this part out, but my new template for hexes now looks like this:
When I clone this I change the title, delete the template tag, fill in the field entries, and end up with a basic hex description with minimal work.

There's also this construct:
    <$link to={{!!race}}><$view field="race"></$view></$link>
Which creates a link to the tiddler named by the race field and wraps it around the field text. If I'm grokking this right, {{}} is a shortcut transclusion, and !! is contents of field.

Folding Tiddlers
There are now built-in buttons for tiddlers that collapse them to just a title line. There are also global buttons that do the same for all open tiddlers. Tiddlers remember their state too, so if you close one completely it reopens with its previous collapsed/expanded appearance.

Cite/Code Blocks
Triple backticks before/after a block of text apply code-block style formatting.

Escaping Special Characters
As far as I can tell, there is no straightforward mechanism for inserting special characters in Tiddlywiki5. I discovered this when trying to insert "<" and ">" characters into some notes. The easiest way seems to be using the appropriate HTML entity.

8 comments:

  1. Nice overview! I think your original tiddly wiki posts are how I stumbled across your previous blog back in the day. I believe I was searching for something tiddly wikish and google led me there, and there led me here. In case anyone cares. :P

    ReplyDelete
    Replies
    1. Huh. Funny. Those posts still get a very high hit-rate compared to the rest of the posts in that blog.

      Delete
  2. TW5 Mall is no longer available. David Gifford wrote on his site (http://www.giffmex.org/aboutus/index.html#TiddlyWiki) that he no longer had time to support it) and referred people to Tobias Beer's site of solutions at http://tobibeer.github.io/tb5/#Solutions

    ReplyDelete
    Replies
    1. Thanks for the information! I'll update the main post with the new link.

      Delete
  3. TW5 uses much more resources, looks ugly on desktop, adds virtually nothing, supports storing of images inside - but converts them into PNG, there is no WYSIWYG editor which would be a must have once your document grows. TW classic had EasyEditPlugin, but it output as HTML, not in TW format - which is okay, but still weird. They added preview, which is actually useless. I don't know, I don't know - I spent whole day trying it out and it simply looks as it got worse.

    ReplyDelete
  4. I was looking again for something to organize my priorities, my thoughts and my data (sounds funny in English but in French: mes données sounds OK to me). Anyway, I remembered that when I was working as a consultant (20014-3008) I used to use Tiddlywiki. I saw that TW5 was available and went for it BUT... I like using treeview and work with complicated tables so I needed FND's mediawiki table formatting; like to create reminders, what no reminder macro! and where is the calendar? I also missed inline javascript and my favourite showClock, which I extended so I could display the time in Newfoundland. So, while waiting for TW5 to mature and get equivalents to my favourite plugins, I am back to classic tiddlywiki. With all my kitchen sink stuff it is still under 1.3MB and it runs on my Linux computer and Android using a slim clone of Firefox called Pale Moon and on the iPod Touch do I can carry it around with me - I am 72 and am not a mobile/cell phone person.

    ReplyDelete
  5. Thank you! This was really helpful! One of the problems I've always had with TiddlyWiki is that there just wasn't enough documentation. I learned most of what I did by looking at example implementations (which was very time-consuming). Now, with the new version, it hasn't been easy, but your post here certainly helped a lot! :)

    ReplyDelete
    Replies
    1. Glad it was helpful! FWIW, there is a lot of really useful info on the main TW site, but it can be hard to dig out details and concrete examples.

      Delete

Note: all comments are moderated to block spammers. Please be polite.