Field transclusions are much like variable or procedure transclusions, but their value comes from the contents of a field of another tiddler in your wiki.

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 in our example wiki 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.

As soon as you update a field of a tiddler, any open tiddlers or parts of the interface that transclude that field will be automatically re-rendered – just like with the results of a filter, or the formulas in a spreadsheet. Because of the draft mechanism, though, if you're editing a tiddler within the story river, you have to save that tiddler before the changes appear – while you edit a tiddler in the story river, you're not actually editing that tiddler itself, but rather a draft copy of it, and your changes only go into the actual tiddler when you save.

Just like you can use the value of a variable or the result of a procedure 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 using the wikipediaLink procedure:

<$transclude $variable="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 transclude content from a variable or procedure
• {{double curly braces}} – to transclude content from a tiddler field

Directly transcluding 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, field 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! Field transclusion becomes even more useful once you understand templates, which we'll cover in the next section.

A note on terminology

In non-technical contexts, people sometimes use the term transclusion by itself to refer specifically to a field transclusion. Grok TiddlyWiki used to do this too, but with the introduction of new features in recent versions of TiddlyWiki that have made all kinds of transclusion more like each other (e.g., the parameterization of tiddlers), it now seems better to instead use transclusion to mean any or all kinds of transclusion, and explicitly say field transclusion when we mean that. It's possible there may be a few traces of the old way still hanging out throughout the book – please use the send feedback link to let me know if you spot one!

The $transclude widget

In the previous section, The Finer Points of Procedures we mentioned that you can use the $transclude widget with the $variable parameter to call a procedure (transclude the value of the procedure/variable). You can use the $transclude widget to do field transclusion as well, using its $tiddler and $field parameters. These are the same thing:

* {{JaneDoe!!phone}}
* <$transclude $tiddler="JaneDoe" $field="phone"/>

You can leave out one or both of the parameters if appropriate. If not supplied, $tiddler defaults to the current tiddler and $field defaults to text.

Exercises

<$let myVariable="test">
    {{Tiddler 2}}
</$let>

Takeaways