Final Checks Before Release of v5.3.2

TiddlyWiki v5.3.2 is due to be released on 11th December 2023. Before that happens we would appreciate everyone helping with testing the new release.

The new release includes some improvements that have very wide ranging implications:

  • New conditional shortcut syntax for more concisely expressing if-then-else logic within wikitext
  • New “join” attribute for the list widget that allows a fragment of wikitext to be inserted between each list entry
  • Much more readable way to avoid packing wikitext into the “emptyMessage” attribute of the list widget

Other changes include:

  • Support for data-* and style.* attributes on all the applicable core widgets
  • New jsonset operator for setting values within JSON objects
  • Improve QR code plugin with the ability to scan QR codes and other barcodes
  • Extended the scrollable widget to allow the scroll position to be monitored and controlled
  • Extended the JSON operators to allow negative indexes into arrays to be counted from the end of the array
  • Fixed a serious bug in the client-server synchronisation process
  • Nearly 20 bug fixes

The prerelease is available at:

There are several ways you can help:

Any feedback is welcome here, or on GitHub.

Please wait until the official release before updating your day-to-day wikis, and remember the first rule of TiddlyWiki: to make sure to take (and verify) backups before doing anything risky.

Best wishes



@jeremyruston – Cool stuff! :slight_smile:

I would also like to add some points.

Please test the functionality of new and fixed features and report bugs here OR at: Issues · Jermolene/TiddlyWiki5 · GitHub

For general discussions, here at “Talk”, please create a new threads. One thread per new feature, if possible.
May be prefixed [v5.3.2-pre]

Documentation Tiddlers

To see list the doc tiddlers, that have been changed since the TW release of v5.3.1 form 20. Aug. 2023, this filter can be used:

[!is[system]!sort[modified]] :filter[get[modified]subtract[20230820112855583]sign[]match[1]]

At the time of writing it returns 25 titles.


Many changed doc tiddlers are related to the new data- and .style attributes, which are useful for passing data to the eventcatcher widget. So if the eventcatcher is a thing for you, this may be interesting.

If not, there is still a lot to help with – continue reading :wink:

A shorter list with 12 doc tiddlers without the eventcatcher changes.

I think from special interest will be the

  • Conditional <% if [<filter>] %> Shortcut Syntax
    • Which internally is “reduced” to a list-widget
  • Explicit Templates for the ListWidget
    • <$list-template>
    • <$list-empty>
  • Joiners for the ListWidget


For all of the contributors of translations – Translations will still be merged even if there is a merge freeze active!

Upgrade Mechanism

Does the upgrade mechanism still work for you?

Backup and use a “throw a way” copy for testing!!

  • Please also report if it works for you!
  • We usually get feedback for this one, when it’s too late.


Full Details

Full details and links to the GH pull requests can be found at: if you click the colored “added”, “extended”, “updated” and “improved” badges

That’s it from my side

Have fun!


Everything works for me, but I have discovered a small detail: the link to forum shown after performing the upgrade links to the Google Group, not here. I made PR that updates it (and also updates the forum links in es-ES and de-AT editions, if that’s worth anything): Update forum link in update wizard by mateuszwilczek · Pull Request #7865 · Jermolene/TiddlyWiki5 · GitHub

Edit: it has likely nothing to do with v5.3.2, just an overlook in the upgrade wizard.

1 Like

Thanks @oeyoews for the very clear bug report with easy reproducibility. A fix has now been merged and confirmed.

The first thing I incorrectly tried is just opening the AdvancedSearch tiddler and trying [jsonset[a],[aa]] to see if it would just generate a string from scratch. I get the RSOE. Doing [[]jsonset[a],[aa]] worked as expected though. Maybe some protection is missing from that first attempt.

1 Like

Thanks @stobot I can confirm the bug, and I’ve just pushed a fix here. It should be available on the prerelease in 5-10 minutes.

1 Like

I’ve managed to test converting five of my larger wikis and a handful of smaller ones, and found no issues on upgrade. Most of these I tested comprehensively, but two of the larger ones got only partial attention.

But I found no issues (beyond the fact that TW>5.2.x is actually blocked in my corporate environment; I’m afraid of calling attention to it only to be told that TW is not allowed!)

I will start trying out the new features—several of which are very exciting!—over the next few days…

1 Like

What’s the point of <$list-template>?

Is this like with <$slot fill="anything-but-ts-raw">, where the introduction of any slots (in this case, <$list-empty>) means that the body of the widget has to be wrapped in a fill of its own? (In this case, <$list-template>)

If that’s the case, then why does this example on the wiki not have that?

<$list filter=<<filter>> variable="item">
<$text text=<<item>>/>
<$list-join>, and <em>also</em> let's not forget </$list-join>

That <$text text=<<item>> />, isn’t wrapped in <$list-template>, which makes it inconsistent to how the other slots and fills work.

Is there an unfinished discussion about whether <$fill> widgets should render at all? Shouldn’t that be sussed out before we go adding even more features built upon that idea?

Also, doesn’t the whole <%if ... %><%elseif ... %><%else%>...<%endif%> fly in the face of how people are supposed to use TiddlyWiki?

TiddlyWiki is about modules and templates and declarative programming? Do we really want dedicated syntax for imperative programming. That stuff looks like PHP got drunk with a bash shell script. Let me ask, who is going to use this feature? I don’t see end-users using it. It’s a miracle if they can understand filters to begin with. These seem like syntactic sugar by power-users for power-users.

The list-widget has an emptyMessage parameter, which expects a string. It’s hard to use and hard to debug. There also is a template parameter, wich expects a tiddler title, that contains a template. – That’s inconsistent.

list-empty and list-template are 2 new widgets that can only live within a list-widget body. They provide a consistent additional way to deal with “emptyMessage” and the “template” parameters.

From time to time users demanded an easy way to “conditionally” show or hide content without using 2 $reveal or the 2 $list widgets if there is an if-then-else construction needed.

During the discussion about implementation details of the <%if syntax there was a possibility to improve the list-widget, since in the background the <%if syntax is internally converted into list-widgets.

<$slot> and <$fill> are 2 new widgets that are used by the transclusion mechanism to allow a more fine grained control in templates. A best practice to use those widgets has jet to be developed and there is a lot of room for documentation improvements. They are not directly related to if-then-else or the list-widget


I understand how the old emptyMessage parameter was bad. I don’t have complaints about something like <$list-empty>, but I still contend that <$list-template> IS inconsistent. It looks like the way its being done is that either the ts-raw-like body of the <$list> is the template, or the content of the <$list-template> is inconsistent. Pick a lane!

It’s the same problem with slots and fill, where ts-raw becomes useless the second you use any custom slots in your widget. I admit that the template attribute is a pain to use, but I don’t see anything inconsistent about it. If it’s present. Use it. If it’s not, then use the <$list> body. Super simple.

…But also sometimes use <$list-template> under some conditions. How is this straight-forward? How do you explain this to new-users? How many threads are going to open up because people don’t understand when they are and aren’t supposed to use a very specific nested widget?

I would have said that the body of the <$list> would always be fine, sans any <$list-empty> or <$list-join> or whatever. There was a similar discussion about this concerning slots and fills here, but that conversation just trailed off. Pity, because I would have thought the outcome of that discussion would have directly impacted this.

But I guess not. I guess this is all already done. And every rebuttal I have just gets with “this was already discussed. Please catch yourself up with the chats here and there”. As somebody who maintains plugins for TiddlyWiki that routinely require me to thoroughly update myself with both the documentation AND source code of every new feature (As well as write tons of tests to tease out their every subtle interaction), it’s getting really old getting these releases thrown at me through the form of bug reports from people telling me my plugins don’t work anymore.

I know this syntax. I know more about it’s subtle tricks than anyone. I would bet money that I understand the subtleties of inline/block behavior better than @jeremyruston. There are parts to some of these releases that leave me completely baffled. I believe I have insights into some of these features, and I see how some of them will produce headaches down the line in ways no one else is seeing right now.

So is there an email thread that I can subscribe to so I can provide input on these things. Maybe I get sulky about this, but I would LOVE to be able to point out some basic things before it’s too late. Like how the $depth attribute from v5.3.0 is something you will all regret in two years. Or how <$list-join> should just be a parameter for now. And maybe pump the breaks on making it its own widget, since that can’t be walked back, and all these <$list> changes should have to to settle and be tested first. There was no rush.

Also, I read that thread about why you guys don’t want <$else>. It sounds like you guys went to a lot of trouble not to upset an old plugin by some guy named Evan, and literally sculpted these features to work AROUND him. Was that really a good idea? In theory, this release should deprecate his plugin, right?

And where the hell was this attitude back when v5.3.0 was being designed? :stuck_out_tongue_winking_eye:

Yes. It was. There is more scope now to extend the shortcut syntax (that is Jeremy’s intention, mentioning a few times the possibility of fostering switch/case down the line).

Look, @Flibbles, I get that you’re smarting over this and some of your reasoning (from where I’m sitting) sounds “sound”. But, for better or worse, this ship has sailed. We don’t have a time machine available to rewind several months so you can join in the discussions. Would that we did, but we are where we are.

I sincerely hope you can find a way to absorb and maybe (just maybe) get comfortable with these changes. :+1:

That’s my point. I’m not lurking in these forums, and I don’t peruse the github issues. So these ships have always sailed.

Do you mean you hope I’ll get familiar enough with these changes to implement updates for my plugins and write the usual battery of tests? We’ll see.

All right. I’ll piss off.

Hey, you know that was never my intention.

1 Like

@Flibbles, @jeremyrustonNow is the time to raise your concerns. It should be easy to delay the release, but if it is released we need to stick with it.

That’s the reason why: Final Checks Before Release of v5.3.2 is globally pinned.

Not quite. That’s what final checks are for.

But there is a great deal of momentum, and it would take a pretty powerful argument to change the direction.

It’s difficult when people knowledgeable about the system are not involved in the early discussions and then want to put on the brakes near the end. And to me @Flibbles is clearly knowledgeable; if nothing else, he’s responsible for my most essential plugin. But it’s important to listen to such folks and take their concerns seriously.

I don’t agree with Flibbles here, but I do recognize that anything adding a major new style of syntax is going to come with its own downside. The biggest one is the expanding conceptual space required to understand TW, which already has a great deal of syntax to understand.

But this syntax is a powerful simplification, and will be much more beginner-friendly than <$list ...> / <$reveal ...>. I wouldn’t agree with codifying an <$if ...>...</$if><$else ...>...</$else> ; to me that’s too fraught with peril. If we could do <$if ...>...<$elseif ...>...</$elseif><$elseif ...>...</$elseif><$else ...> ... </$else></$if>, which would then allow proper nesting, it would be useful. But this isn’t compatible with Evan’s plugin (I hear) and conflicting with all the wikis using a popular plugin would be shooting ourselves in the foot. (Note that this is somewhat different from conflicting with the plugin itself; as that has a centralized solution.)

I would love to have a way for interested people (such as @Flibbles) to subscribe to discussions of important core changes especially on GitHub, but also here. But I can’t really imagine how that might work.

Yeah, I muddled up shortcut syntax and the list extensions. Sentiment’s okay-ish though.

Callouts/shoutouts. But that involves forgetful humans ← fully payed up, card carrying member. :confused:

I meant more that 5.3.2 is not out the door yet, and this “final call” is a last chance to find holes important enough to require delays/alterations before release.

Exactly. Anything I can imagine automating still has a human judgement somewhere about whether this change is substantial enough to send up the smoke signals. And I can’t see any way to bring that question to the right person’s attention at the right time.

Trying the upgrade today, noticing that the icon for Tiddler Commander spacing changed.



I confirmed this also happens on my system with empty.html (Edge on Windows)