Docs: Transclude widget

editions/tw5.com/tiddlers/widgets/ParametersWidget.tid

@@ -0,0 +1,6 @@
+caption: parameters
+created: 20220718192846556
+modified: 20220718192846556
+tags: Widgets
+title: ParametersWidget
+type: text/vnd.tiddlywiki

editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid

@@ -1,24 +1,164 @@
 caption: transclude
 created: 20130824142500000
-modified: 20220513114759336
+modified: 20220718192846556
 tags: Widgets
 title: TranscludeWidget
 type: text/vnd.tiddlywiki
 
 ! Introduction
 
-The TranscludeWidget dynamically imports content from another tiddler.
+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 |
+| !Attribute |<| !Description |
-|tiddler |The title of the tiddler to transclude (defaults to the current tiddler) |
+| !(modern) | !(legacy) |~|
-|field |The field name of the current tiddler (defaults to "text"; if present takes precedence over the index attribute) |
+|$variable |- |Name of the variable to transclude |
-|index |The index of a property in a [[DataTiddler|DataTiddlers]] |
+|$tiddler |tiddler |The title of the tiddler to transclude (defaults to the current tiddler) |
-|subtiddler |Optional SubTiddler title when the target tiddler is a [[plugin|Plugins]] (see below) |
+|$field |field |The field name of the current tiddler (defaults to "text"; if present takes precedence over the index attribute) |
-|mode |Override the default parsing mode for the transcluded text to "block" or "inline" |
+|$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 |
 
-The TranscludeWidget treats any contained content as a fallback if the target of the transclusion is not defined (ie a missing tiddler or a missing field).
+! 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 then 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 `\parameters` [[pragma|Pragma]]
+* the `\procedure` [[pragma|Pragma]] for declaring procedure
+* the `\widgets` [[pragma|Pragma]] for declaring custom widgets
+* the `\define` [[pragma|Pragma]] 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|Pragma]] 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 passing 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>
+```
+
+Here is the contents of the tiddler "Example":
+
+```
+<ol>
+  <li><$slot $name="positive"/></li>
+  <li><$slot $name="negative"/></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