mirrors/TiddlyWiki5
1
0
Fork 0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-11-30 05:19:57 +00:00
Code Issues Releases Wiki Activity

Improve docs for TranscludeWidget and Transclusion tiddler (#8282)

Browse Source
This commit is contained in:
Mario Pietsch 2024-06-21 10:07:41 +02:00 committed by GitHub
parent 14c5628d35
commit 02ccec7ea8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 44 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
editions/tw5.com/tiddlers/concepts/Transclusion.tid
View File

@ -1,9 +1,15 @@
created: 20141129194651420
modified: 20141130195444237
tags: Concepts
modified: 20240621074019077
tags: Concepts Definitions
title: Transclusion
[[Transclusion|https://en.wikipedia.org/wiki/Transclusion]] is the process of referencing one tiddler "A" from another tiddler "B" such that the content of "A" appears to be a part of "B".
! Definition
<<< Wikipedia: [[Transclusion|https://en.wikipedia.org/wiki/Transclusion]]
In computer science, transclusion is the inclusion of part or all of an electronic document into one or more other documents by reference via hypertext.
<<<
In ~TiddlyWiki: ''Transclusion'' is the process of referencing one tiddler "A" from another tiddler "B" such that the content of "A" appears to be a part of "B".
Copying and pasting content creates multiple copies of the same content in several different places. With transclusion, there can be a single copy and a special instruction in "B" which indicates the point at which content should be inserted from tiddler "A".

70
editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid
View File

@ -1,21 +1,48 @@
caption: transclude
created: 20130824142500000
modified: 20230511022612458
modified: 20240621073236430
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.
Transclusion is the underlying mechanism for many higher level wikitext features, such as ''procedures'', ''functions'', ''custom widgets'' and ''macros''.
The <<.wlink TranscludeWidget>> widget can be used to render content of any type: wikitext, images, videos, etc.
The <<.wid transclude>> widget dynamically includes the content from another ''tiddler'' or ''variable'', rendering it as if the transclude widget were replaced by the target content.
Transclusion is the underlying mechanism for many higher level wikitext features, such as procedures, custom widgets and macros.
The <<.wid transclude>> widget can be used to render content of any type: wikitext, images, videos, etc.
! Attributes
| !Attribute |<| !Description |
| !(modern) | !(legacy) |~|
|$variable |- |Name of the variable to transclude. Eg: Name of <<.dlink procedures Procedures>>, <<.dlink functions Functions>>, <<.dlink "custom widgets" Widgets>> and <<.dlink macros Macros>> |
|$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'') |
|$fillignore |- |Set to ''yes'' to make this transclusion invisible to the <<.attr $depth>> attribute of the <<.wlink SlotWidget>> 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 |
! Legacy vs. Modern Mode
The <<.wid transclude>> widget can be used in two modes:
* <<.from-version "5.3.0">> ''Modern mode'' offers the full capabilities of the <<.wid transclude>> 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.
! Example
Here is a complete example showing the important features of the <<.wlink TranscludeWidget>> widget:
Here is a complete example showing the important features of the <<.wid transclude>> widget:
```
\procedure myproc(name,age)
@ -29,36 +56,9 @@ My name is <<name>> and my age is <<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'') |
|$fillignore |- |Set to ''yes'' to make this transclusion invisible to the <<.attr $depth>> attribute of the <<.wlink SlotWidget>> 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 <<.wlink TranscludeWidget>> widget is as follows:
The basic operation of the <<.wid 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) |
@ -69,7 +69,7 @@ The basic operation of the <<.wlink TranscludeWidget>> widget is as follows:
! 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.
Named string parameters can be passed to the <<.wid 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 `$`:
@ -108,7 +108,7 @@ Parameters are available here as the variables <<firstParameter>> and <<secondPa
! 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.
Transcluded content can define special named locations called slots. At the point of transclusion, blocks of wikitext can be passed to the <<.wid 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.