This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

TranscludeWidget

 11th May 2023 at 2:26am

Introduction

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.

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

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.

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.

Attributes

AttributeDescription
(modern)(legacy)
$variable-Name of the variable to transclude
$tiddlertiddlerThe title of the tiddler to transclude (defaults to the current tiddler)
$fieldfieldThe field name of the current tiddler (defaults to "text"; if present takes precedence over the index attribute)
$indexindexThe index of a property in a DataTiddler
$subtiddlersubtiddlerOptional SubTiddler title when the target tiddler is a plugin (see below)
$modemodeOverride the default parsing mode for the transcluded text to "block" or "inline"
$typeOptional ContentType used when transcluding variables, indexes or fields other than the text field
$output-ContentType for the output rendering (defaults to text/html, can also be text/plain or text/raw)
$recursionMarkerrecursionMarkerSet to no to prevent creation of Legacy Transclusion Recursion Marker (defaults to yes)
$fillignore-Set to yes to make this transclusion invisible to the $depth attribute of the $slot widget (defaults to no)
{attributes not starting with $}Any other attributes that do not start with a dollar are used as parameters to the transclusion
{other attributes starting with $}Other attributes starting with a single dollar sign are reserved for future use
{attributes starting with $$}Attributes starting with two dollar signs are used as parameters to the transclusion, but with the name changed to use a single dollar sign

Basic Operation

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

<$transclude/>Transcludes the text field of the current tiddler
<$transclude $variable="alpha"/>Transcludes the variable "alpha" (note that procedures, custom widgets and macros are all special types of variable)
<$transclude $tiddler="foo"/>Transcludes the text field of the tiddler "foo"
<$transclude $field="bar"/>Transcludes the field "bar" of the current tiddler
<$transclude $index="beta"/>Transcludes the index "beta" of the current tiddler
<$transclude $tiddler="foo" $index="beta"/>Transcludes the index "beta" of the tiddler "foo"

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:

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"/>

That renders as:

GettingStarted