Docs update

editions/tw5.com/tiddlers/variables/Global Definitions.tid

@@ -0,0 +1,69 @@
+title: Global Definitions
+created: 20220909111836951
+modified: 20220909111836951
+tags: Concepts Reference Variables
+
+!! Introduction
+
+<<.from-version "5.3.0">> Globals are [[variables|Variables]] that are available everywhere, without needing a [[<$set>|SetWidget]], [[<$vars>|SetWidget]] or [[<$let>|SetWidget]] widget.
+
+!! Defining Globals
+
+Previously, definitions of procedures, widgets, functions and macros were made available globally by tagging them with `$:/tags/Macro`. While this mechanism is still supported, it suffers from several disadvantages and so is not recommended for new applications:
+
+* Performance is poor because 
+
+THe new way to define global procedures, widgets, functions and macros is to place them in tiddlers titled with the name of the global prefixed with `$:/global/`.
+
+For example, the global variable `foo` would be defined in a tiddler called `$:/global/foo`. Accessing the variable `<<foo>>` then acts as a shortcut for accessing the underlying global variable tiddler.
+
+!! Special Fields
+
+The following special fields are used to define the behaviour of the global:
+
+* `_parameters` defines the parameters expected by procedures, widgets and functions
+* `_is_procedure`, `_is_widget`, `_is_function`, `_is_macro`: any one of these fields may be set to `yes` to indicate the type of the definition
+
+<<.note """The `_parameters` field is only strictly necessary for functions and macros. Procedures and widgets can instead choose to use the <<.wlink ParametersWidget>> widget (or a pragma) within the body of the definition""">>
+
+!! Viewing Globals
+
+The current global definitions are listed in the sidebar in the "More" -> "Globals" tab.
+
+By default, global definition tiddlers are displayed with a custom template that makes it easier to see the full definition.
+
+!! Local Variables within Globals
+
+Note that global definitions can include local variables that are defined before the body of the global. These local variables will not be visible externally.
+
+For example:
+
+```
+title: $:/globals/foo
+_is_procedure: yes
+_parameters: (param1:"value",param2:"value")
+
+\procedure renderTitle(title)
+<div class="mytitle"><$text text=<<title>>/></div>
+\end
+
+\function myfn(a)
+[[a]getvariable[]addprefix[!]]
+\end
+
+<$list filter=<<param1>>>
+
+<<renderTitle "first">>: <$text text=<<param2>>/>
+
+<<renderTitle "second">>: <$text text=<<myfn param2>>/>
+
+</$list>
+```
+
+It is possible to allow the caller to override these local definitions by using the new syntax for conditional definitions. For example, here we only define the function `myfn` if the variable `myfn` is not already defined:
+
+```
+\?function myfn(a)
+[[a]getvariable[]addprefix[!]]
+\end
+```

editions/tw5.com/tiddlers/variables/Variables.tid

@@ -1,5 +1,5 @@
 created: 20141002133113496
-modified: 20150221215644000
+modified: 20220909111836951
 tags: Concepts Reference
 title: Variables
 type: text/vnd.tiddlywiki
@@ -10,6 +10,8 @@ A new variable is defined using a <<.wlink SetWidget>> widget, and is then avail
 
 The <<.wlink ListWidget>> widget also sets a particular variable (<<.var currentTiddler>> by default) to each listed title in turn.
 
+Variables can also be defined as [[Global Definitions]].
+
 For an overview of how to use variables, see [[Variables in WikiText]].
 
 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.

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

@@ -25,15 +25,27 @@ The content of the <<.wlink ParametersWidget>> widget is the scope within which
 
 |!Attribute |!Description |
 |$depth |The index of the parent transclusion from which to obtain the parameters (defaults to 1). See below |
-|//{attributes not starting with $}// |– |Any attributes that do not start with a dollar are used as parameters, with the value specifying the default to be used for missing parameters |
-|//{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 value specifies the default to be used for missing parameters |
+|$parseMode |Optional name of a variable in which is made available the parse mode of the content of the parent transclusion (the parse mode can be "inline" or "block") |
+|$parseTreeNodes |Optional name of a variable in which is made available the JSON representation of the parse tree nodes contained within the parent transclusion |
+|$slotFillParseTreeNodes |Optional name of a variable in which is made available the JSON representation of the parse tree nodes corresponding to each fill widget contained within the parent transclusion (as an object where the keys are the slot names and the values are the parse tree nodes) |
+|$params |Optional name of a variable in which is made available the JSON representation of the parameters passed to the parent transclusion (as an object where the keys are the parameter names and the values are the coresponding values) |
+|//{attributes not starting with $}// |Any attributes that do not start with a dollar are used as parameters, with the value specifying the default to be used for missing parameters |
+|//{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 value specifies the default to be used for missing parameters |
 
 <<.note "Note the special treatment required for parameters names that start with a `$`; this can be avoided by using one of the pragmas">>
 
 !! `$depth` Attribute
 
-By default, the <<.wlink ParametersWidget>> widget retrieves parameters from the immediate parent transclusion. The `$depth` attribute permits access to the parameters of parent transclusions by specifying an index to the parent to be inspected. This is useful in some situations where an intervening transclusion prevents immediate access to desired parameters.
+By default, the <<.wlink ParametersWidget>> widget retrieves parameters from the immediate parent transclusion. The `$depth` attribute permits access to the parameters of parent transclusions by specifying an index to the parent to be inspected ("1" is the immediate parent, "2" is the parent of that parent, etc.). This is useful in some situations where an intervening transclusion prevents immediate access to desired parameters.
+
+!! `$parseMode`, `$slotFillParseTreeNodes` and `$params` Attributes
+
+These attributes provide low level access to the contents of the transcluding widget:
+
+* The `$params` attribute provides access to the raw parameters provided to the transcluding widget. Represented in JSON as an object with keys of the parameter names and values of the corresponding parameter values
+* The `$parseMode` attribute provides access to the raw parse tree nodes that represent the contents of the transcluding widget. Represented in JSON as an array of parse tree nodes
+* The `$slotFillParseTreeNodes` attribute provides access to the raw parse tree nodes corresponding to the filled slots within the contents of the transcluding widget. Represented in JSON as an object with keys of the slot name and values being an array of parse tree nodes
 
 ! Examples
 

editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid

@@ -1,13 +1,13 @@
 caption: Variables
 created: 20141002141231992
-modified: 20150221221850000
+modified: 20220909111836951
 tags: WikiText
 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 in WikiText]] with no parameters. You can also use a <<.wlink MacroCallWidget>> widget.
+To transclude the value of a variable, use the [[macro call syntax|Macro Calls in WikiText]] 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.