mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-11-04 00:56:17 +00:00
223 lines
8.3 KiB
Plaintext
223 lines
8.3 KiB
Plaintext
caption: transclude
|
||
created: 20130824142500000
|
||
modified: 20220917113915710
|
||
tags: Widgets
|
||
title: TranscludeWidget
|
||
type: text/vnd.tiddlywiki
|
||
|
||
! Introduction
|
||
|
||
The <<.wlink TranscludeWidget>> widget dynamically includes the content from another tiddler or variable, rendering it as if the transclude widget were replaced by the target content.
|
||
|
||
The <<.wlink TranscludeWidget>> 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 <<.wlink TranscludeWidget>> widget:
|
||
|
||
```
|
||
\procedure mymacro(name,age)
|
||
My name is <<name>> and my age is <<age>>.
|
||
\end
|
||
|
||
<$transclude $variable="mymacro" 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 <<.wlink TranscludeWidget>> widget specifies the variable to transclude, and values for the parameters.
|
||
|
||
! Legacy vs. Modern Mode
|
||
|
||
The <<.wlink TranscludeWidget>> widget can be used in two modes:
|
||
|
||
* <<.from-version "5.3.0">> ''Modern mode'' offers the full capabilities of the <<.wlink TranscludeWidget>> widget, and incorporates the functionality of the <<.wlink MacroCallWidget>> 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
|
||
|
||
| !Attribute |<| !Description |
|
||
| !(modern) | !(legacy) |~|
|
||
|$variable |- |Name of the variable to transclude |
|
||
|$tiddler |tiddler |The title of the tiddler to transclude (defaults to the current tiddler) |
|
||
|$field |field |The field name of the current tiddler (defaults to "text"; if present takes precedence over the index attribute) |
|
||
|$index |index |The index of a property in a [[DataTiddler|DataTiddlers]] |
|
||
|$subtiddler |subtiddler |Optional SubTiddler title when the target tiddler is a [[plugin|Plugins]] (see below) |
|
||
|$mode |mode |Override the default parsing mode for the transcluded text to "block" or "inline" |
|
||
|$type |– |Optional 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`) |
|
||
|$recursionMarker |recursionMarker |Set to ''no'' to prevent creation of [[Legacy Transclusion Recursion Marker]] (defaults to ''yes'') |
|
||
|//{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 <<.wlink TranscludeWidget>> 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 <<.wlink TranscludeWidget>> 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 <<.wlink ParametersWidget>> widget
|
||
* the [[Pragma: \parameters]]
|
||
* the [[Pragma: \procedure]] for declaring procedure
|
||
* the [[Pragma: \widgets]] for declaring custom widgets
|
||
* the [[Pragma: \define]] for declaring macros
|
||
|
||
An example of declaring parameters with the <<.wlink ParametersWidget>> widget:
|
||
|
||
```
|
||
<$parameters firstParameter="default" secondParameter="another default">
|
||
Parameters are available here as the variables <<firstParameter>> and <<secondParameter>>.
|
||
</$parameters>
|
||
```
|
||
|
||
The `\parameters` [[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 <<.wlink TranscludeWidget>> widget to fill those slots.
|
||
|
||
Slots work very similarly to parameters except that they can contain structured wikitext, and not just plain text.
|
||
|
||
For example, here we transclude the tiddler "Example" while using the <<.wlink FillWidget>> 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 <<.wlink SlotWidget>> 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>
|
||
```
|
||
|
||
|
||
! 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-body">
|
||
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 <<.wlink TranscludeWidget>> 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|WikiText Parser Modes]]:
|
||
|
||
* [[inline mode|Inline Mode WikiText]] recognises character formatting such as emphasis, links
|
||
* [[block mode|Block Mode WikiText]] 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 <<.attr 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:
|
||
|
||
# Item one
|
||
# # Item one - a # Item one - b
|
||
# Item two
|
||
|
||
This can be fixed by amending tiddler "A":
|
||
|
||
```
|
||
# Item one
|
||
#<$transclude tiddler="B" mode="block"/>
|
||
# Item two
|
||
```
|
||
See also these [[other examples|WikiText parser mode: transclusion examples]].
|
||
|
||
! ~SubTiddler Access
|
||
|
||
The transclude widget allows access to the individual tiddlers stored within a [[plugin|Plugins]].
|
||
|
||
The following example will transclude the core version of the tiddler [[$:/DefaultTiddlers]] even if it has been overridden:
|
||
|
||
<<wikitext-example-without-html """<$transclude tiddler="$:/core" subtiddler="$:/DefaultTiddlers"/>""">>
|