As we've seen, TiddlyWiki offers a wide variety of ways to reuse wikitext, among them:

• Variables
• Procedures
• Field Transclusions, optionally with templates and/or parameters
• Functions
• Macros
• Custom Widgets

It's usually obvious when to use a function – when the thing you're trying to reuse is a filter expression, or can be easily retrieved by a filter expression. The other options are less clear, so let's briefly talk about those.

We should start out by noting that there aren't many wrong answers, and to a large extent the choice is personal preference. All of the options work just fine in most cases, and they usually have similar performance as well.

Field transclusions vs. something else

The main question here is what makes the most sense semantically. That is, even though the two methods have the same effect, one might feel easier for a person to read and understand. For instance, the Summary of Transclusion Syntax and Updated Summary of Transclusion Syntax in Grok TiddlyWiki are both made almost entirely of a parameterized transclusion of another tiddler called CommonTransclusionSyntax, the parameter indicating how many of the features we've talked about so far. I could have implemented CommonTransclusionSyntax as a procedure, but that would feel less natural, since it feels more like we're including another document/section than that we're getting a snippet of text. On the other hand, implementing our wikipediaLink procedure as a transclusion of a tiddler would feel unnatural; there isn't really any content in a link to a Wikipedia page, so a transclusion that makes it look like you're getting legitimate content from your wiki is confusing.

Another case where procedures are often more convenient than parameterized field transclusions or templates is when you want to create several closely related snippets, especially snippets that refer to each other. For instance, there are two related global procedures used internally by Grok TiddlyWiki, gtw.link-chapter-name and gtw.link-chapter-number. These can be used separately in wikitext, and link-chapter-number calls link-chapter-name to achieve its goal. It's handy to be able to keep these in the same tiddler ($:/sib/ReferenceMacros) and be able to see their definitions right next to each other, rather than having them spread over several tiddlers.

Of course, you can put a procedure, function, macro, etc., inside a tiddler that you transclude, if that proves the easiest way to achieve something.

There is one thing that variables (and their brethren, procedures, functions, and macros) can achieve that field transclusions cannot, which is to have the same name refer to different things depending on context. Since variables have scopes, you could, for instance, define the procedure toc to create one kind of table of contents in some places, and an entirely different kind in others, and use, say, the \import pragma to select the appropriate one for each tiddler. This is not possible with field transclusions, since a tiddler field always has the same contents in a given wiki until you edit it. This is not something you're likely to want to do frequently, but once in a long while it could come in handy when digging deep into customizations of TiddlyWiki, so it seems worth mentioning.

Procedures vs. variables

It's perfectly fine to use a procedure (or a macro definition with \define – there's no difference if there are no parameters) to define a variable that you want to scope to the entire tiddler. Sometimes this feels neater than having the whole tiddler wrapped in a $let widget.

Of course, variables don't allow you to include parts that change in their wikitext, so they won't work at all in some cases.

Procedures vs. custom widgets

A custom widget actually is a procedure internally – the only difference is the syntax you see in your wikitext. Typically, we prefer using a custom widget when some parameter we need to pass into the procedure is multiple lines long or contains quotes, making it awkward to pass using normal procedure-call syntax.

If you want to override a built-in widget, as we'll learn about in the next chapter, you need to use the custom widget syntax to do that; a procedure won't do.

Procedures vs. Macros

In new wikitext, it's usually recommended that macros only be used when text substitution makes life much easier, because procedures are safer and clearer.