This is a stripped-down version of a single section of Grok TiddlyWiki, optimized for fast loading and readability by search engines. Some features are missing.

For the full Grok TiddlyWiki experience, please visit the wiki version of this page.


9th April 2021 at 2:57pm

Field transclusions are much like variable references, except instead of being set to a specific value by a $set widget or a macro definition, their value comes from a tiddler.

Specifically, a field transclusion, as its name suggests, references the contents of a particular field of a tiddler. If we write {{JaneDoe!!phone}}, the contents of the phone field of the JaneDoe tiddler – namely, Jane's phone number – will appear in the output. Let's start a tiddler called PhoneNumbers and try that:

* JaneDoe -- {{JaneDoe!!phone}}

You should see:

  • JaneDoe – 888-555-1234

Either the left or the right side of the reference can be left off. Just {{JaneDoe}} refers to the text field of the JaneDoe tiddler, while just {{!!phone}} refers to the phone field of the current tiddler.

Just like you can use the value of a variable or the result of a macro call as an attribute of a widget, you can use the value of a field transclusion as an attribute of a widget. For example, suppose we had a field on the current tiddler called wikipedia-reference that contained the name of a Wikipedia article it was based on, and we wanted to create a link to it:

<$macrocall $name="wikipediaLink" article={{!!wikipedia-reference}} />

Notice the similarity in form between the three wikitext methods we've encountered for referring to other content:

  • [[double square brackets]] – to link to content
  • <<double angle brackets>> – to get content from a variable or macro
  • {{double curly braces}} – to get content from a tiddler field

Directly including entire tiddlers within other tiddlers, like {{My Other Tiddler}}, is uncommon in most wikis; linking is usually a more useful way of relating ideas. However, transclusion is invaluable in combination with filters for creating dynamic lists, tables, and other content. In fact, the whole interface of TiddlyWiki is actually created by transcluding a bunch of special tiddlers! Transclusion becomes even more useful once you understand templates, which we'll cover in the next section.

A note on terminology

Technically, the form <<double angle brackets>> is called a variable transclusion or macro transclusion. In the document-management-systems world, the word transclusion refers to including some other document or content at the location of the reference, and macros and variables do this just like field transclusions do.

However, in non-technical contexts, people often use the term transclusion by itself to refer to a field transclusion. We will try to explicitly state what kind of transclusion we mean if it might be unclear, but for the most part you should read transclusion without a modifier as field transclusion in the remainder of this book.


Exercise: (m) [Ex:JaneDataTransclusion]

One of the complaints we had about our Contact Tiddlers when we initially created them was that you couldn't see any of the fields on them without clicking on the info button. Remedy that by adding a section to the JaneDoe tiddler titled Information about Jane, containing a bulleted list or table that shows Jane's email address, phone number, family members, and manager.

go to answer

Exercise: (s) [Ex:FudgeTransclusion]

Our initial motivation for extracting the now-infamous fudge tiddler from the EmployeeProfileSetupMeeting tiddler was so that we wouldn't accidentally share that information with somebody. Suppose that everyone else at the company also uses TiddlyWiki, so we always share our notes as raw wikitext instead of rendered/formatted output so recipients can paste it directly into their own wikis. In this case, we can rely on transclusion to protect us provided that the fudge tiddler's title isn't too revealing: if we copy the whole tiddler without noticing this inclusion, the recipient won't get the transcluded tiddler and thus won't see our embarrassing notes.

All this is to say, transclude the fudge tiddler into the EmployeeProfileSetupMeeting tiddler. What are the advantages and disadvantages of doing it this way as opposed to linking or tagging?

go to answer

Exercise: (s) [Ex:SearchingInTransclusions]

In an exercise in the previous chapter, we observed that tiddlers referenced in fields did not appear in search. Now, however, we have transcluded these fields directly into the JaneDoe tiddler. Try searching for some of the text again (e.g., ChrisSmith). Has anything changed?

go to answer

Exercise: (s) [Ex:LinkingInTransclusions]

In general, if we reference ChrisSmith in the manager field of the JaneDoe tiddler, Jane does not show up as a backlink in ChrisSmith's Backlinks tab on the info page, because Backlinks shows only links in the text field. However, now we have a link in the text since we have transcluded the value of the manager field into the text. So now that we have a link, we should have a reference back to JaneDoe from ChrisSmith.

Test this hypothesis by looking in the Backlinks tab of ChrisSmith. What did you find? Why might this be?

go to answer

Exercise: (s) [Ex:MultipleTransclusion]

What happens if you transclude a tiddler that contains transclusions?

go to answer

Exercise: (s) [Ex:SelfTransclusion]

What happens if you transclude a tiddler into itself?

go to answer

Exercise: (s) [Ex:CircularTransclusion]

What happens if you transclude tiddler A into tiddler B, and tiddler B into tiddler A?

go to answer

Exercise: (M) [Ex:JaneManagerPhone]

Transclude a line into the text of Jane's tiddler that contains Chris Smith's phone number, in case she messes up so badly that you need to contact her manager immediately.

How would you make it so that it currently refers to Chris's phone number, but if the manager field is updated, the new manager's phone number will appear instead? (You might not be able to get this one, but at least spend some time thinking about it and experimenting before you look at the answer.)

Hint: Use a macro.

go to answer

Exercise: (s) [Ex:VariableTransclusion]

What happens if you set a variable in one tiddler, and transclude a tiddler that references that variable within the scope of the $set widget? You can start with a Tiddler 1 that looks something like this:

<$set name="myVariable" value="test">
    {{Tiddler 2}}
go to answer


Takeaways are not available in the static version of Grok TiddlyWiki. Visit the wiki version of this page to study takeaways.

↑ 4: Variables, Macros, and Transclusions