Once in a while you may end up with a bunch of simple data composed of key-value pairs, where you have one piece of information and want to look up the other. For instance, let's suppose we want to create a display of what holiday today is, if it is a holiday. We have a list of the months and days of some common United States holidays (we'll pretend for the moment that no holidays exist that don't fall on the same date every year!):
Date | Holiday name |
---|---|
01/01 | New Year's Day |
07/04 | Independence Day |
10/31 | Halloween |
12/25 | Christmas Day |
If we have lots of other information about these holidays, it would make sense to create a tiddler for each holiday and use fields to store the different data points we wanted to track about each holiday. However, if the names and dates above are all we care about, and we just want to be able to see if a particular day is a holiday, that might be overkill.
We might also find the approach of creating tiddlers annoying if we have a way to import this data from somewhere outside the wiki – we can likely get a list of holidays in some standard format, but TiddlyWiki tiddlers are not likely to be one of those standard formats!
In these situations, data tiddlers can come in handy. A data tiddler is a tiddler with a special content type whose text
field contains a series of key-value pairs, like the date-name pairs shown in the table above. There are two ways to format a data tiddler: TiddlyWiki's built-in dictionary format, and JSON (JavaScript Object Notation, a standard data interchange format). If you're familiar with JSON, be aware that only very simple JSON files with a single level of key-value pairs are supported (no arrays or objects).
Dictionary data tiddlers can't contain colons :
in their keys, or newlines anywhere. JSON data tiddlers allow you to include all characters, provided they are properly escaped.
Each key-value pair in a data tiddler is called a property, and the key of each property is called its index.
Creating a data tiddler
Let's create a data tiddler called UsHolidays
for these holidays. The tiddler's content will look like this:
01/01: New Year's Day
07/04: Independence Day
10/31: Halloween
12/25: Christmas Day
You can see that the keys (the month and day) are separated from the values (the name of the holiday) by a colon. Spaces before or after the colon don't affect the value TiddlyWiki sees.
Paste this content into a new tiddler, then from the Type drop-down underneath the text field, pick application/x-tiddler-dictionary
and save the tiddler.
To work with data tiddlers, we use a special addition to the normal transclusion syntax: to get the value for the index 07/04
from the UsHolidays
data tiddler, we write {{UsHolidays##07/04}}
. You can also use the getindex
filter operator, like [[UsHolidays]getindex[07/04]]
.
{{UsHolidays##07/04}}
<$text text={{{ [[UsHolidays]getindex[07/04]] }}}/>
Independence Day
Independence Day
Exercises
Create a tiddler called TodaysHoliday
which says It's ''The Day'' today!
, where The Day
is the name of the holiday that is occurring today, according to the data tiddler. Unless you happen to be doing this exercise on one of the four holidays listed above, you'll need to make up and add your own holiday with today's date so you can check the result.
You may need to look at the documentation for the now
procedure to figure out how to get today's date in the month/day
format.
The TodaysHoliday
tiddler has a problem: if today isn't a holiday, it says “It's today!”. While true, that sounds a little silly, doesn't it? Change the tiddler so that if today is not a holiday, it instead says, “Sadly, it's a very ordinary day today.”
Tip: An attribute to the $list
widget called emptyMessage
may come in handy.
Create another data tiddler called UsHolidaysJson
using the same data in a JSON format, and change your TodaysHoliday
tiddler to look the holiday up in there instead. Everything should continue to work the same way on the transclusion side. The table looks like this in JSON:
{
"01/01": "New Year's Day",
"07/04": "Independence Day",
"10/31": "Halloween",
"12/25": "Christmas Day"
}