diff --git a/editions/tw5.com/tiddlers/widgets/ParametersWidget.tid b/editions/tw5.com/tiddlers/widgets/ParametersWidget.tid new file mode 100644 index 000000000..452a4a0ce --- /dev/null +++ b/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 diff --git a/editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid b/editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid index 6bc507cae..647b37716 100644 --- a/editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid +++ b/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 <> and my age is <>. +\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 | -|tiddler |The title of the tiddler to transclude (defaults to the current tiddler) | -|field |The field name of the current tiddler (defaults to "text"; if present takes precedence over the index attribute) | -|index |The index of a property in a [[DataTiddler|DataTiddlers]] | -|subtiddler |Optional SubTiddler title when the target tiddler is a [[plugin|Plugins]] (see below) | -|mode |Override the default parsing mode for the transcluded text to "block" or "inline" | +| !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 | -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 <> and <>. + +``` + +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 <> and <>. +``` + +! 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"> +

This is positive

+ + <$fill $name="negative"> +

This is negative

+ + +``` + +Here is the contents of the tiddler "Example": + +``` +
    +
  1. <$slot $name="positive"/>
    2. +
  2. <$slot $name="negative"/>
    3. +
+``` + +! 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 $name="other"> +This content is passed to the transclusion as the slot value `other` + + +``` + +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. + +``` ! Parsing modes