From 6be996a8580eb45c19814be7216deb9f4b093baf Mon Sep 17 00:00:00 2001 From: "jeremy@jermolene.com" Date: Thu, 6 Oct 2022 21:37:14 +0100 Subject: [PATCH] Docs update --- .../tw5.com/tiddlers/variables/Variables.tid | 138 ++++++++++++++++-- .../wikitext/Variables in WikiText.tid | 35 +---- 2 files changed, 130 insertions(+), 43 deletions(-) diff --git a/editions/tw5.com/tiddlers/variables/Variables.tid b/editions/tw5.com/tiddlers/variables/Variables.tid index 1df1cb677..f586141e8 100644 --- a/editions/tw5.com/tiddlers/variables/Variables.tid +++ b/editions/tw5.com/tiddlers/variables/Variables.tid @@ -1,24 +1,140 @@ created: 20141002133113496 -modified: 20220930195819232 -tags: Concepts Reference +modified: 20221006124708656 +tags: Concepts Reference WikiText title: Variables type: text/vnd.tiddlywiki -A <<.def variable>> is a snippet of text that can be accessed by name within a particular branch of the [[widget tree|Widgets]]. The snippet is known as the variable's <<.def value>>. +!! Introduction -A new variable is defined using a <<.wlink SetWidget>> widget, and is then available to any of the children of that widget, including transcluded content. A <<.wid set>> widget can reuse an existing name, thus binding a different snippet to that name for the duration of the widget's children. +A <<.def variable>> is a snippet of text that can be accessed by name. The text is referred to as the variable's <<.def value>>. -The <<.wlink ListWidget>> widget also sets a particular variable (<<.var currentTiddler>> by default) to each listed title in turn. +Variables are defined by [[widgets|Widgets]]. Several core widgets define variables, the most common being the <<.wlink SetWidget>>, <<.wlink LetWidget>> and <<.wlink ListWidget>> widgets. -For an overview of how to use variables, see [[Variables in WikiText]]. +The values of variables are available to descendant widgets, including transcluded content. For example, within each tiddler in the main story river the variable "currentTiddler" is set to the title of the tiddler. -Despite the term <<.word variable>>, each snippet is a constant string. The apparent variability is actually the result of the presence of multiple variables with the same name in different parts of the widget tree. +Variables can also be overwritten by descendent widgets defining variables of the same name, thus binding a different snippet to that name for the scope of the children of the widget. -[[Macros]] are a special form of variable whose value can contain placeholders that get filled in with parameters whenever the macro is used. +!! Special Kinds of Variables -By themselves, the snippets are <<.em not>> parsed as WikiText. However, a variable reference will transclude a snippet into a context where ~WikiText parsing <<.em may>> be occurring. Within a snippet, the only markup detected is `$name$` for a macro parameter transclusion and `$(name)$` for a variable transclusion. +There are several special kinds of variable that extend their basic capabilities: -The <<.mlink dumpvariables>> macro lists all variables (including macros) that are available at that position in the widget tree. +* [[Procedures]] are snippets of text that can be passed parameters when wikified +* [[Functions]] are snippets of text containing [[filters|Filters]] with optional named parameters +* [[User Defined Widgets]] are snippets of text containing definitions of custom [[widget|Widgets]] +* [[Macros]] are snippets of text that can contain placeholders that are filled in with parameters whenever the macro is used -~TiddlyWiki's core has [[several variables|Core Variables]] built in. +Note that these special kinds of variable can only be created with the associated shortcut definition syntax. + +!! Defining Variables + +The following core widgets are commonly used to define variables: + +* <<.wlink LetWidget>> widget -- the easiest way to define multiple variables +* <<.wlink SetWidget>> widget -- the most flexible way to define a single variable +* <<.wlink ParametersWidget>> widget -- used to declare parameter variables within [[procedures|Procedures]] and [[user defined widgets|User Defined Widgets]] +* <<.wlink ListWidget>> widget -- defines a loop variable and optional counter variable +* <<.wlink SetMultipleVariablesWidget>> widget -- allows creation of multiple variables at once where the names and values are not known in advance + +!! Using Variables + +Once a variable is defined there are several ways to access it. + +!!! Transcluding Variables + +Transcluding a variable renders the text contents of the variable as if it replaced the call. It is a shortcut syntax for the <<.wlink TranscludeWidget>> widget with the `$variable` attribute. + +``` +<> +``` + +Parameters can be passed to the transclusion as follows: + +``` +<> +<> +<> +``` + +The handling of these parameters depends on the kind of variable: + +* [[Procedures]] assign the parameters to variables that are available within the procedure +* [[Macros]] replace the text of the special markers `$param$` with the values passed to the macro for those parameters (see [[Macro Parameter Handling]] for the details) + +The parameters are ignored for other kinds of variable. + +!!! Macro Variable Substitutions + +Before the text of a macro is used, the special markers `$(variable)$` are replaced with the values of the named variable. + +!!! Variable Attributes + +Variables can be used as the value of attributes of widgets or HTML elements: + +``` +
>> +``` + +Parameters can be passed: + +``` +
>> +... +
>> +... +
>> +... +``` + +The handling of these parameters depends on the kind of variable: + +* [[Functions]] assign the parameters to variables that are available within the function +* [[Macros]] replace the text of the special markers `$param$` with the values passed to the macro for those parameters (see [[Macro Parameter Handling]] for the details) + +The parameters are ignored for other kinds of variable. + +!!! Variables in Filters + +Variables can be accessed within [[Filters]] using angle brackets to quote the name: + +``` +[] +``` + +Parameters can be passed in the usual way: + +``` +[] +[] +[] +... +``` + +!! See Also + +* The <<.mlink dumpvariables>> macro lists all variables that are available at that position in the widget tree +* Complete listing of ~TiddlyWiki's built-in [[Core Variables]] + +!! Examples + +!!! Example of Defining a Variable + +<$macrocall $name=".example" n="1" +eg="""<$set name=animal value=zebra> +<> +"""/> + +!!! Example of Defining a Macro + +The `\define` pragma below [[defines a macro|Macro Definitions]] called <<.var tags-of-current-tiddler>>. The macro returns the value of the tiddler's <<.field tags>> field, and can be accessed from anywhere else in the same tiddler (or in any tiddler that [[imports|ImportVariablesWidget]] it). + +<$importvariables filter="$:/editions/tw5.com/macro-examples/tags-of-current-tiddler"> +<$codeblock code={{$:/editions/tw5.com/macro-examples/tags-of-current-tiddler}}/> +<$macrocall $name=".example" n="2" eg="""The tags are: <>"""/> + + +!!! Example of Using a Variable as a Filter Parameter + +This example uses the <<.olink backlinks>> [[operator|Filter Operators]] to list all tiddlers that link to this one. + +<$macrocall $name=".example" n="3" eg="""<backlinks[]]">>"""/> diff --git a/editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid b/editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid index 9fda21f04..f462dd3bf 100644 --- a/editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid +++ b/editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid @@ -1,37 +1,8 @@ caption: Variables created: 20141002141231992 -modified: 20220930195709700 -tags: WikiText +modified: 20221005153734979 +tags: title: Variables in WikiText type: text/vnd.tiddlywiki -See also the [[introduction to the concept of variables|Variables]]. - -To transclude the value of a variable, use the [[macro call syntax|Macro Calls]] or the <<.wlink TranscludeWidget>> widget with the `$variable` attribute. - -A [[macro|Macros]] snippet can contain `$(name)$` as a [[placeholder|Macro Definitions in WikiText]] for which the value of the variable of that name will be substituted. - -A variable's value can be used as a [[filter parameter|Filter Parameter]], or as a [[widget attribute|Widgets in WikiText]]. The latter supports macro parameters. - -!! Example: defining a variable - -<$macrocall $name=".example" n="1" -eg="""<$set name=animal value=zebra> -<> -"""/> - -!! Example: defining a macro - -The `\define` pragma below [[defines a macro|Macro Definitions]] called <<.var tags-of-current-tiddler>>. The macro returns the value of the tiddler's <<.field tags>> field, and can be accessed from anywhere else in the same tiddler (or in any tiddler that [[imports|ImportVariablesWidget]] it). - -<$importvariables filter="$:/editions/tw5.com/macro-examples/tags-of-current-tiddler"> -<$codeblock code={{$:/editions/tw5.com/macro-examples/tags-of-current-tiddler}}/> -<$macrocall $name=".example" n="2" eg="""The tags are: <>"""/> - - -!! Example: using a variable as a filter parameter - -This example uses the <<.olink backlinks>> [[operator|Filter Operators]] to list all tiddlers that link to this one. - -<$macrocall $name=".example" n="3" eg="""<backlinks[]]">>"""/> - +See [[Variables]]. \ No newline at end of file