144 lines
5.5 KiB
Plaintext
144 lines
5.5 KiB
Plaintext
created: 20141002133113496
|
|
modified: 20230422150445336
|
|
tags: Concepts Reference WikiText
|
|
title: Variables
|
|
type: text/vnd.tiddlywiki
|
|
|
|
!! Introduction
|
|
|
|
* 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>>.
|
|
|
|
Variables are defined by [[widgets|Widgets]]. Several core widgets define variables, the most common being the <<.wlink LetWidget>>, <<.wlink SetWidget>> and <<.wlink ListWidget>> widgets.
|
|
|
|
The values of variables are available to descendant widgets, including transcluded content. For example, within each tiddler in the main story river the variable <<.var currentTiddler>> is set to the title of the tiddler.
|
|
|
|
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.
|
|
|
|
!! Special Kinds of Variables
|
|
|
|
There are several special kinds of variable that extend their basic capabilities:
|
|
|
|
* [[Procedures]] are snippets of text that can be passed parameters when wikified
|
|
* [[Functions]] are snippets of text containing [[filters|Filters]] with optional named parameters
|
|
* [[Custom 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
|
|
|
|
Note that these special kinds of variable can only be created with the associated shortcut definition syntax.
|
|
|
|
For a more detailed comparison of these special kinds of variables, see [[Variable Usage]].
|
|
|
|
!! 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 [[custom widgets|Custom 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.
|
|
|
|
```
|
|
<<varname>>
|
|
```
|
|
|
|
Parameters can be passed to the transclusion as follows:
|
|
|
|
```
|
|
<<varname "This is a parameter">>
|
|
<<varname param:"This is a parameter">>
|
|
<<varname param:"This is a parameter" second:"Another parameter">>
|
|
```
|
|
|
|
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:
|
|
|
|
```
|
|
<div class=<<varname>>>
|
|
```
|
|
|
|
Parameters can be passed:
|
|
|
|
```
|
|
<div class=<<varname "This is a parameter">>>
|
|
...
|
|
<div class=<<varname param:"This is a parameter">>>
|
|
...
|
|
<div class=<<varname param:"This is a parameter" second:"Another parameter">>>
|
|
...
|
|
```
|
|
|
|
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:
|
|
|
|
```
|
|
[<varname>]
|
|
```
|
|
|
|
Parameters can be passed in the usual way:
|
|
|
|
```
|
|
[<varname "This is a parameter">]
|
|
[<varname param:"This is a parameter">]
|
|
[<varname param:"This is a parameter" second:"Another parameter">]
|
|
...
|
|
```
|
|
|
|
!! 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>
|
|
<<animal>>
|
|
</$set>"""/>
|
|
|
|
!!! 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: <<tags-of-current-tiddler>>"""/>
|
|
</$importvariables>
|
|
|
|
!!! 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="""<<list-links filter:"[<currentTiddler>backlinks[]]">>"""/>
|
|
|