Sometimes a set of tiddlers has a particular order. For instance, this book is composed in TiddlyWiki with each section as a tiddler, and the sections should be read in a certain order. We need some way of telling TiddlyWiki what that order is.
We could simply create a tiddler that contained links to each of the tiddlers in order, but then we'd have to remember to manually change that tiddler every time we created a new one, and it wouldn't help TiddlyWiki display them in the correct order in tables of contents or tag pills. We need something more formal.
The tiddler list
TiddlyWiki uses tiddler lists, often called just lists, as a formal mechanism to order tiddlers. As you may recall, at its most basic, a list is simply a series of tiddler names written in a field, separated by spaces, or placed in double square brackets if the tiddler name itself contains a space. We first discussed the idea of a list way back in Contact Tiddlers, when we created a family field on our contact tiddlers that was a list. The participants field on our meetings is also a list.
One list on each tiddler is particularly special to TiddlyWiki. This list is stored in the field called, appropriately enough, list. If this field is populated on a tiddler that's serving as a tag, TiddlyWiki will peek into it when it's displaying a tag pill or a table of contents and list the tagged tiddlers in the order they appear in the list field. (If there is no list field, the tagged tiddlers will be shown in alphabetical order by title.)
Two related fields are available as well, list-before and list-after. These fields are stored on tagged tiddlers rather than tagging tiddlers, and they allow you to modify how TiddlyWiki reads the list field without actually changing that field. For example, suppose we have tag tiddler T tagging tiddlers A, B, C, and D. The list field of tiddler T is A B D. If we populate the list-before field of tiddler C with D, then when we see a list of the tiddlers tagged by T, we'll see A B C D. On the other hand, if we populate the list-after field of tiddler C with A, we'll see A C B D.
Right now, it is probably not obvious why you would ever do this rather than simply modify the list field. In most cases, it's indeed easier and clearer to change the list field. However, there may be some times when you prefer not to modify a tag tiddler – for instance, if it's a shadow tiddler that makes up part of TiddlyWiki's internals. We'll learn more about this in Chapter 6.
Corner cases
If you like finding problems with everything you read, you might have noticed a couple of possibilities not accounted for by the explanation above. Here's what happens in those:
- If a tiddler is in more than one of
list,list-before, andlist-after, the last one in that ordering wins (i.e.,list-aftertakes precedence overlist-before, andlist-beforeoverlist). - If a tiddler is tagged by T but doesn't appear in T's
listfield and doesn't have alist-beforeorlist-afterfield (i.e., no ordering information is available at all), TiddlyWiki puts it after all tiddlers that do have ordering information. If there are multiple tiddlers with no ordering information, they appear in alphabetical order by title.
See Order of Tagged Tiddlers in the TiddlyWiki documentation for even a couple more details that you probably don't need.
Changing the order of lists
So that's all well and good, but editing a list field to move things around sounds like a bit of a pain, doesn't it? Maybe it's all right if we have a couple of tiddlers that need ordering, but what if there are dozens? Editing a line of text that scrolls off the side of the screen isn't much fun.
Fortunately, TiddlyWiki offers us several ways to drag and drop tiddlers into the right order and automatically modify the list field to match. In fact, we've used one of these drag-and-drop views already: the Open tab in the sidebar. That one just happens to be reordering a list of open tiddlers rather than a list of tiddlers with a particular tag.
The easy way to reorder tiddlers with a particular tag is to find a tag pill for that tag, click on the pill, and drag and drop the entries in the list. If the tag tiddler doesn't currently have a list field, your first drag-and-drop will create it, with all the tiddlers in alphabetical order except the one you just moved.
You can also insert such a reorderable list anywhere you want using list-links-draggable:
<<list-links-draggable "MyTiddler">>This will produce a bulleted list with links to each of the tiddlers listed in the list field of MyTiddler, and if you drag and drop them, the field will be updated, just like if you drag and drop tiddlers within the tag pill. (As with the various table-of-contents incantations in the previous section, this is a built-in procedure, a statement that will make sense once we get to chapter 4.)
Exercises
Create several more meeting tiddlers under the OnboardingHr tag, then try dragging and dropping them around using the tag pill list. Have the OnboardingProcess tiddler open as you do so, so you can see the effects on the table of contents.
Repeat the previous exercise using a list-links-draggable reference of the form described in this section, inserted within the OnboardingHr tiddler.
Use the list-before field to make the OnboardingPeople tiddler appear first in the table of contents you created within the OnboardingProcess tiddler in the previous section.