Introduction

Transclusion is the underlying mechanism for many higher level wikitext features, such as procedures, functions, custom widgets and macros.

The $transclude widget dynamically includes the content from another tiddler or variable, rendering it as if the transclude widget were replaced by the target content.

The $transclude widget can be used to render content of any type: wikitext, images, videos, etc.

Attributes

Legacy vs. Modern Mode

The $transclude widget can be used in two modes:

• New in v5.3.0 Modern mode offers the full capabilities of the $transclude widget, and incorporates the functionality of the $macrocall widget. It is indicated by the presence of at least one attribute starting with a dollar sign $
• Legacy mode offers a more limited set of capabilities. It is indicated by the absence of any attributes starting with a dollar sign $

Modern mode is recommended for use in new applications.

Example

Here is a complete example showing the important features of the $transclude widget:

\procedure myproc(name,age)
My name is <<name>> and my age is <<age>>.
\end

<$transclude $variable="myproc" name="James" age="19"/>

• \procedure defines a variable as a procedure with two parameters, name and age
• The content of the procedure refers to the parameters as variables
• The $transclude widget specifies the variable to transclude, and values for the parameters.

Basic Operation

The basic operation of the $transclude widget is as follows:

Transclusion Parameters

Named string parameters can be passed to the $transclude widget. They are made available as variables within the transcluded text. Parameters are only supported in modern mode.

When invoking a transclusion, parameters are specified as additional attributes that do not start with a dollar sign $:

<$transclude $tiddler="MyTiddler" firstParameter="One" secondParameter="Two"/>

To pass parameters whose names start with a dollar sign $, prefix them with an extra $. For example, to pass a parameter called $tiddler:

<$transclude $tiddler="MyTiddler" $$tiddler="One"/>

There are several different ways to declare parameters within a transclusion:

• the $parameters widget
• the Pragma: \parameters
• the Pragma: \procedure for declaring procedure
• the Pragma: \widget for declaring custom widgets
• the Pragma: \define for declaring macros

An example of declaring parameters with the $parameters widget:

<$parameters firstParameter="default" secondParameter="another default">
    Parameters are available here as the variables <<firstParameter>> and <<secondParameter>>.
</$parameters>

The Pragma: \parameters can be used as a shortcut syntax for declaring parameters. For example:

\parameters (firstParameter:"default",secondParameter:"another default")
Parameters are available here as the variables <<firstParameter>> and <<secondParameter>>.

Transclusion Slots

Transcluded content can define special named locations called slots. At the point of transclusion, blocks of wikitext can be passed to the $transclude widget to fill those slots.

Slots work very similarly to parameters except that they can contain structured wikitext, and not just plain text. The primary advantage of slots over parameters is that the contents do not need to be wrapped in quotation symbols, making it much simpler to pass complex structures.

For example, here we transclude the tiddler "Example" while using the $fill widget to pass wikitext blocks to fill the slots called "positive" and "negative":

<$transclude $tiddler="Example">
  <$fill $name="positive">
    <h1>This is positive</h1>
  </$fill>
  <$fill $name="negative">
    <h3>This is negative</h3>
  </$fill>
</$transclude>

The tiddler "Example" uses the $slot widget to specify the slots to be filled:

<ol>
  <li><$slot $name="positive"/></li>
  <li><$slot $name="negative"/></li>
</ol>

The output will be equivalent to:

<ol>
  <li>
    <h1>This is positive</h1>
  </li>
  <li>
    <h3>This is negative</h3>
  </li>
</ol>

See $slot for more examples.

Missing Transclusion Targets

The TranscludeWidget uses the special slot ts-missing to specify the content to be rendered if the transclusion target is not defined (i.e. a missing tiddler or a missing field).

For example:

<$transclude $tiddler="MissingTiddler">
<$fill $name="ts-missing">
This content is displayed if `MissingTiddler` is missing.
</$fill>
<$fill $name="other">
This content is passed to the transclusion as the slot value `other`
</$fill>
</$transclude>

If no slots values are specified within the $transclude widget then the entire content of the widget is used as the missing content.

For example:

<$transclude $tiddler="MissingTiddler">
This content is displayed if `MissingTiddler` is missing.
</$transclude>

Parsing modes

TiddlyWiki parses text in two modes:

• inline mode recognises character formatting such as emphasis, links
• block mode recognises all the inline formatting, and adds block formatting such as tables, headings and lists

Usually, the mode is determined by whether the transclude widget itself has been parsed in block or inline mode. This can be overridden with the mode attribute.

For example, consider tiddler "A" with this content:

# Item one
#<$transclude tiddler="B"/>
# Item two

And a tiddler "B" with this content:

# Item one - a
# Item one - b

The result will be something like this:

1. Item one
2. # Item one - a # Item one - b
3. Item two

This can be fixed by amending tiddler "A":

# Item one
#<$transclude tiddler="B" mode="block"/>
# Item two

See also these other examples.

SubTiddler Access

The transclude widget allows access to the individual tiddlers stored within a plugin.

The following example will transclude the core version of the tiddler $:/DefaultTiddlers even if it has been overridden:

<$transclude tiddler="$:/core" subtiddler="$:/DefaultTiddlers"/>