tiddlywiki 5.2.0 → 5.2.3

package/editions/tw5.com/tiddlers/widgets/CheckboxWidget.tid

@@ -1,7 +1,10 @@
 caption: checkbox
 created: 20131024141900000
-modified: 20201109090732190
-tags: Widgets
+modified: 20220402023600000
+tags: Widgets TriggeringWidgets
+colors: red orange yellow blue
+fruits: bananas oranges grapes
+vegetables: carrots potatoes
 title: CheckboxWidget
 type: text/vnd.tiddlywiki
 
@@ -21,11 +24,15 @@ The content of the `<$checkbox>` widget is displayed within an HTML `<label>` el
 |tag |The name of the tag to which the checkbox is bound |
 |invertTag |When set to ''yes'', flips the tag binding logic so that the absence of the tag causes the checkbox to be checked  |
 |field |The name of the field to which the checkbox is bound |
+|listField |<<.from-version "5.2.3">> The name of the field that contains the list to which the checkbox is bound |
 |index|<<.from-version "5.1.14">> The index of the //tiddler//, a [[DataTiddler|DataTiddlers]], to which the checkbox is bound<<.tip "be sure to set the //tiddler// correctly">>|
+|listIndex |<<.from-version "5.2.3">> Like <<.attr index>>, but treats the value as a list the same way that <<.attr listField>> does |
+|filter |<<.from-version "5.2.3">> A filter whose output determines the checked state of the checkbox |
 |checked |The value of the field corresponding to the checkbox being checked |
 |unchecked |The value of the field corresponding to the checkbox being unchecked |
 |default |The default value to use if the field is not defined |
-|class |The class that will be assigned to the label element |
+|indeterminate |Whether ambiguous values can produce indeterminate checkboxes (see below) |
+|class |The class that will be assigned to the label element <$macrocall $name=".tip" _="""<<.from-version "5.2.3">> `tc-checkbox` is always applied by default, as well as `tc-checkbox-checked` when checked"""/> |
 |actions |<<.from-version "5.1.14">> A string containing ActionWidgets to be triggered when the status of the checkbox changes (whether it is checked or unchecked) |
 |uncheckactions |<<.from-version "5.1.16">> A string containing ActionWidgets to be triggered when the checkbox is unchecked |
 |checkactions |<<.from-version "5.1.20">> A string containing ActionWidgets to be triggered when the checkbox is checked |
@@ -45,7 +52,19 @@ Using the checkbox widget in field mode requires the ''field'' attribute to spec
 
 This example creates a checkbox that is checked if the field ''status'' is equal to ''open'' and unchecked if the field is equal to ''closed''. If the field is undefined then it defaults to ''closed'', meaning that the checkbox will be unchecked if the ''status'' field is missing.
 
-<<wikitext-example-without-html """<$checkbox field="status" checked="open" unchecked="closed" default="closed"> Is it open?</$checkbox><br>''status:'' {{!!status}}""">>
+<<wikitext-example-without-html """<$checkbox field="status" checked="open" unchecked="closed" default="closed"> Is it open?</$checkbox><br />''status:'' {{!!status}}""">>
+
+!! List Mode
+
+Using the checkbox widget in list mode requires the ''listField'' attribute to specify the name of a field containing a list. The ''checked'' attribute specifies the value that should be present or absent in the list when the checkbox is checked or unchecked respectively. If ''checked'' is absent (or empty) but ''unchecked'' is present, then the logic will be inverted: the checkbox will be checked when the "unchecked" value is missing from the list, and unchecked when the "unchecked" value is found in the list. If both ''checked'' and ''unchecked'' are present, the checkbox will work like a toggle, replacing the ''checked'' value with the ''unchecked'' value and vice-versa. Finally, if neither ''checked'' nor ''unchecked'' is specified, the checkbox will be checked if the field has anything in it, but unchecked if the field is missing or empty. (This is rarely useful; most of the time you'll want to specify ''checked'' or ''unchecked'' or both.)
+
+The ''default'' attribute is used as a fallback for the checkbox state if the field is not defined.
+
+This example creates a checkbox that is checked if the list field named ''colors'' contains ''green'' and unchecked if the field contains ''red''. If the field is undefined, or if neither ''green'' nor ''red'' appears in the field, then it defaults to ''green'', meaning that the checkbox will be checked.
+
+<<wikitext-example-without-html """<$checkbox listField="colors" checked="green" unchecked="red" default="green"> Is it green?</$checkbox><br />''colors:'' {{!!colors}}""">>
+
+Try editing the ''colors'' field of this tiddler to see how the example changes.
 
 !! Index Mode
 
@@ -54,3 +73,58 @@ To use the checkbox widget in index mode set the ''index'' attribute to the inde
 The example below creates a checkbox that is checked if the index by the name of this tiddler in the tiddler ExampleData is equal to ''selected'' and unchecked if the index is an empty string. If the index is undefined then it defaults to an empty string, meaning the checkbox will be unchecked if the index is missing.
 
 <$macrocall $name="wikitext-example-without-html" src="""<$checkbox tiddler="ExampleData" index=<<currentTiddler>> checked="selected" unchecked="" default=""> Selected?</$checkbox>"""/>
+
+!! Index List Mode
+
+Using the checkbox widget in index list mode requires the ''listIndex'' attribute to specify the the index of a [[DataTiddler|DataTiddlers]] containing a list. The ''checked'' attribute specifies the value that should be present or absent in the list when the checkbox is checked or unchecked respectively. If ''checked'' is absent (or empty) but ''unchecked'' is present, then the logic will be inverted: the checkbox will be checked when the "unchecked" value is missing from the list, and unchecked when the "unchecked" value is found in the list. If both ''checked'' and ''unchecked'' are present, the checkbox will work like a toggle, replacing the ''checked'' value with the ''unchecked'' value and vice-versa. Finally, if neither ''checked'' nor ''unchecked'' is specified, the checkbox will be checked if the field has anything in it, but unchecked if the field is missing or empty. (This is rarely useful; most of the time you'll want to specify ''checked'' or ''unchecked'' or both.)
+
+The ''default'' attribute is used as a fallback for the checkbox state if the index is undefined.
+
+The example below creates three checkboxes that each control a different value in an index field of the ExampleData tiddler.
+
+<$macrocall $name="wikitext-example-without-html" src="""
+<$set name=indexName filter="[<currentTiddler>addsuffix[ Colors]]" >
+<$checkbox tiddler="ExampleData" listIndex=<<indexName>> checked="green" unchecked="red" default="red"> Green or red?</$checkbox> <br/>
+<$checkbox tiddler="ExampleData" listIndex=<<indexName>> checked="yellow" unchecked="blue" default="blue"> Yellow or blue?</$checkbox> <br/>
+<$checkbox tiddler="ExampleData" listIndex=<<indexName>> checked="orange" unchecked="purple" default="purple"> Orange or purple?</$checkbox> <br />
+Colors list: {{{ [[ExampleData]getindex<indexName>] }}}
+</$set>
+"""/>
+
+!! Filter Mode
+
+Using the checkbox widget in filter mode requires the ''filter'' attribute to contain a filter whose output will determine the checked state of the checkbox. In filter mode, checking the checkbox will not automatically make changes to any field of any tiddler. Instead, you can use the ''actions'' attribute (or ''checkactions'' and ''uncheckactions'') to specify what should happen when the checkbox is toggled. It is your responsibility to make sure the actions cause changes to the tiddlers or fields that the filter results depend on, so that the checkbox becomes properly checked or unchecked after the actions have triggered.
+
+If the filter returns an empty result, the checkbox will be unchecked. Otherwise, if the filter result is non-empty, the checkbox will be checked. However, if either the ''checked'' or ''unchecked'' attributes (or both) are specified, then their values will be looked for in the filter result, instead of considering any non-empty value to mean "checked".
+
+This example creates the same checkbox as in the list mode example, selecting between ''red'' and ''green'' in the ''colors'' list field, but using filters and actions to make the change.
+
+<<wikitext-example-without-html """\define checkActions() <$action-listops $field="colors" $subfilter="-red green"/>
+\define uncheckActions() <$action-listops $field="colors" $subfilter="red -green"/>
+<$checkbox filter="[list[!!colors]]" checked="green" unchecked="red" default="red" checkactions=<<checkActions>> uncheckactions=<<uncheckActions>> > Is "green" in colors?</$checkbox><br />''colors:'' {{!!colors}}
+""">>
+
+!! Indeterminate checkboxes
+
+If both the ''checked'' and ''unchecked'' attributes are specified, but neither one is found in the specified field (or index), the result can be ambiguous. Should the checkbox be checked or unchecked? Normally in such cases the checkbox will be unchecked, but if the ''indeterminate'' attribute is set to "yes" (default is "no"), the checkbox will instead be in an "indeterminate" state. An indeterminate checkbox counts as false for most purposes &mdash; if you click it, the checkbox will become checked and the ''checkactions'', if any, will be triggered &mdash; but indeterminate checkboxes are displayed differently in the browser.
+
+This example shows indeterminate checkboxes being used for categories in a shopping list (which could also be sub-tasks in a todo list, or many other things). If only some items in a category are selected, the category checkbox is indeterminate. You can click on the category checkboxes to see how indeterminate states are treated the same as the unchecked state, and clicking the box checks it and applies its check actions (in this case, checking all the boxes in that category). Try editing the <<.field fruits>> and <<.field vegetables>> fields on this tiddler and see what happens to the example when you do.
+
+<<wikitext-example-without-html """\define check-all(field-name:"items") <$action-listops $field="selected-$field-name$" $filter="[list[!!$field-name$]]" />
+\define uncheck-all(field-name:"items") <$action-listops $field="selected-$field-name$" $filter="[[]]" />
+
+<$checkbox filter="[list[!!selected-fruits]count[]]" checked={{{ [list[!!fruits]count[]] }}} unchecked="0" checkactions=<<check-all fruits>> uncheckactions=<<uncheck-all fruits>> indeterminate="yes"> fruits</$checkbox>
+<ul style="list-style: none">
+<$list variable="fruit" filter="[list[!!fruits]]">
+<li><$checkbox listField="selected-fruits" checked=<<fruit>>> <<fruit>></$checkbox></li>
+</$list>
+</ul>
+<$checkbox filter="[list[!!selected-vegetables]count[]]" checked={{{ [list[!!vegetables]count[]] }}} unchecked="0" checkactions=<<check-all vegetables>> uncheckactions=<<uncheck-all vegetables>> indeterminate="yes"> veggies</$checkbox>
+<ul style="list-style: none">
+<$list variable="veggie" filter="[list[!!vegetables]]">
+<li><$checkbox listField="selected-vegetables" checked=<<veggie>>> <<veggie>></$checkbox></li>
+</$list>
+</ul>
+
+<p>Selected veggies: {{!!selected-vegetables}}<br/>
+Selected fruits: {{!!selected-fruits}}</p>""">>

package/editions/tw5.com/tiddlers/widgets/DraggableWidget.tid

@@ -1,7 +1,7 @@
 caption: draggable
 created: 20170406081938627
-modified: 20210912141544224
-tags: Widgets
+modified: 20220715120213777
+tags: Widgets TriggeringWidgets
 title: DraggableWidget
 type: text/vnd.tiddlywiki
 
@@ -16,8 +16,11 @@ See DragAndDropMechanism for an overview.
 |!Attribute |!Description |
 |tiddler |Optional title of the payload tiddler for the drag |
 |filter |Optional filter defining the payload tiddlers for the drag |
-|class |Optional CSS classes to assign to the draggable element. The class `tc-draggable` is added automatically, and the class `tc-dragging` is applied while the element is being dragged |
-|tag |Optional tag to override the default "div" element |
+|tag |Optional tag to override the default "div" element created by the widget|
+|selector|<<.from-version 5.2.2>> Optional CSS Selector to identify a DOM element within the widget that will be used as the drag handle |
+|class |Optional CSS classes to assign to the DOM element created by the widget. The class `tc-draggable` is added to the the DOM element created by the widget unless the <<.param selector>> attribute is used. The class `tc-dragging` is applied to the DOM element created by the widget while the element is being dragged |
+|enable |<<.from-version 5.2.3>> Optional value "no" to disable the draggable functionality (defaults to "yes") |
+
 |startactions |Optional action string that gets invoked when dragging ''starts'' |
 |endactions |Optional action string that gets invoked when dragging ''ends'' |
 |dragimagetype |<<.from-version "5.2.0">> Optional type of drag image: `dom` (the default) or `blank` to disable the drag image |
@@ -28,5 +31,22 @@ The [[actionTiddler Variable]] is accessible in both //startactions// and //enda
 
 <<.tip """Note that the [[actionTiddler Variable]] holds a [[Title List]] quoted with double square brackets. This is unlike the DroppableWidget which uses the same variable to pass a single unquoted title.""">>
 
+<<.tip """When specifying a DOM node to use as the drag handle with the <<.param selector>> attribute, give it the class `tc-draggable` in order for it to have the appropriate cursor and the attribute `draggable` with the value `true` to make it draggable.""">>
+
 
 The LinkWidget incorporates the functionality of the DraggableWidget via the ''draggable'' attribute.
+
+<<.from-version 5.2.3>> The following variables are accessible in the //startactions// and the //endactions//:
+
+|!Variables |!Description |
+|`modifier` |The [[modifier Variable]] contains the Modifier Key held while dragging |
+|`dom-*` |All DOM attributes of the node being dragged are made available as variables, with the prefix `dom-` |
+|`tv-popup-coords` |A co-ordinate string that can be used with the ActionPopupWidget to trigger a popup at the DOM node that's being dragged where the event originated |
+|`tv-selectednode-posx` |`x` offset position of the dragged DOM node |
+|`tv-selectednode-posy` |`y` offset position of the dragged DOM node  |
+|`tv-selectednode-width` |`offsetWidth` of the dragged DOM node |
+|`tv-selectednode-height` |`offsetHeight` of the dragged DOM node |
+|`event-fromselected-posx` |`x` position of the event relative to the dragged DOM node |
+|`event-fromselected-posy` |`y` position of the event relative to the dragged DOM node |
+|`event-fromviewport-posx` |`x` position of the event relative to the viewport |
+|`event-fromviewport-posy` |`y` position of the event relative to the viewport |

package/editions/tw5.com/tiddlers/widgets/DroppableWidget.tid

@@ -1,7 +1,7 @@
 caption: droppable
 created: 20170406082820317
-modified: 20200317142604572
-tags: Widgets
+modified: 20211009122023265
+tags: Widgets TriggeringWidgets
 title: DroppableWidget
 type: text/vnd.tiddlywiki
 

package/editions/tw5.com/tiddlers/widgets/DropzoneWidget.tid

@@ -1,7 +1,7 @@
 caption: dropzone
 created: 20131024141900000
-modified: 20210506115809131
-tags: Widgets
+modified: 20211009122205481
+tags: Widgets TriggeringWidgets
 title: DropzoneWidget
 type: text/vnd.tiddlywiki
 

package/editions/tw5.com/tiddlers/widgets/EditTextWidget.tid

@@ -1,6 +1,6 @@
 caption: edit-text
 created: 20131024141900000
-modified: 20210519154352055
+modified: 20211104200554064
 tags: Widgets
 title: EditTextWidget
 type: text/vnd.tiddlywiki
@@ -28,34 +28,23 @@ The content of the `<$edit-text>` widget is ignored.
 |autocomplete |<<.from-version 5.1.23>> An optional string to provide a hint to the browser how to handle autocomplete for this input |
 |tag |Overrides the generated HTML editing element tag. For a multi-line editor use `tag=textarea`. For a single-line editor use `tag=input` |
 |type |Overrides the generated HTML editing element `type` attribute |
-|size |The size of the input field (in characters) |
+|size |The size of the input field (in characters). This exact result depends on browser and font. Use the `class` attribute to style width for precise control |
 |autoHeight |Either "yes" or "no" to specify whether to automatically resize `textarea` editors to fit their content (defaults to "yes") |
 |minHeight |Minimum height for automatically resized `textarea` editors, specified in CSS length units such as "px", "em" or "%" |
 |rows|Sets the rows attribute of a generated textarea |
 |cancelPopups |<<.from-version "5.1.23">> if set to "yes", cancels all popups when the input gets focus |
-|inputActions |<<.from-version 5.1.23>> Optional actions that are triggered every time an input event occurs within the input field or textarea |
+|inputActions |<<.from-version 5.1.23>> Optional actions that are triggered every time an input event occurs within the input field or textarea.<br><<.from-version "5.2.1">> The variable `actionValue` is available to the `inputActions` and contains the value of the input field. |
 |refreshTitle |<<.from-version 5.1.23>> An optional tiddler title that makes the input field update whenever the specified tiddler changes |
 |disabled|<<.from-version "5.1.23">> Optional, disables the text input if set to "yes". Defaults to "no"|
 |fileDrop|<<.from-version "5.2.0">> Optional. When set to "yes" allows dropping or pasting images into the editor to import them. Defaults to "no"|
 
-! Notes
 
-One trap to be aware of is that the edit text widget //cannot be used// to edit a field of the tiddler that contains it. Each keypress results in the tiddler being re-rendered, which loses the cursor position within the text field.
+! Example
 
-Instead, place the edit text widget in a [[template|TemplateTiddlers]] that references the tiddler you want to modify.
+If you wanted to change the field //myconfig// of the tiddler //AppSettings//, you could use an EditTextWidget to edit the field, and then show the result anywhere else by using `{{AppSettings!!myconfig}}`. Note that this will create tiddler AppSettings if it doesn't already exist.
 
-For example, if you wanted the tiddler GettingStarted to edit the value of the "myconfig" field of the tiddler "AppSettings", you might do so by creating a separate tiddler "ChangeAppSettings" that contains the following:
+<$macrocall $name=".example" n="1"
+eg="""<$edit-text tiddler="AppSettings" field="myconfig"/><p/>
+Value of ''myconfig'' : {{AppSettings!!myconfig}}
+"""/>
 
-```
-<$edit-text tiddler="AppSettings" field="myconfig"/>
-```
-
-And reference the template in any other tiddler (e.g. GettingStarted) with `{{ChangeAppSettings}}`.
-
-This works when your use of the tiddler //is not// the AppSettings itself which would cause a recursion problem. In this latter case you have to save the fields to a temporary (or alternative) tiddler (sort of the reverse of above) like so:
-
-```
-<$edit-text tiddler="StoreAppSettings" field="myconfig"/>
-```
-
-In short the EditTextWidget //can not// change properties of the tiddler it is embedded in or part of. It can only change fields of //other// tiddlers. One could use ShadowTiddlers to accomplish the field storage if needed.

package/editions/tw5.com/tiddlers/widgets/EditWidget.tid

@@ -1,7 +1,7 @@
 caption: edit
 created: 20131024141900000
-modified: 20201130184647904
-tags: Widgets
+modified: 20211009121634055
+tags: Widgets TriggeringWidgets
 title: EditWidget
 type: text/vnd.tiddlywiki
 

package/editions/tw5.com/tiddlers/widgets/EventCatcherWidget.tid

@@ -1,6 +1,6 @@
 created: 20201123113532200
-modified: 20210805083352068
-tags: Widgets
+modified: 20220507184043398
+tags: Widgets TriggeringWidgets
 title: EventCatcherWidget
 type: text/vnd.tiddlywiki
 
@@ -12,11 +12,12 @@ type: text/vnd.tiddlywiki
 
 The event catcher widget traps DOM-initiated Javascript events dispatched within its child content, and allows invoking a series of ActionWidgets in response to those events. 
 
-In order for the events to be trapped they must:
+In order for the events to be trapped:
 
-* be of one of the events specified in the event catcher widget's `events` attribute
-* arise within a DOM node specified by the widget's `selector` attribute
-* support event bubbling
+* The event must be of one of the events specified in the event catcher widget's `events` attribute
+* The event must target a DOM node with an ancestor that matches the widget's `selector` attribute
+* <<.from-version "5.2.2">> Optionally, the DOM node targetted by the event must also match the widgets `matchSelector` attribute
+* The event must support event bubbling
 
 Use of the event catcher widget is beneficial when using large numbers of other trigger widgets such as the ButtonWidget is causing performance problems. The workflow it enables is akin to what is referred to as "event delegation" in JavaScript parlance.
 
@@ -25,8 +26,8 @@ Use of the event catcher widget is beneficial when using large numbers of other
 The content of the `<$eventcatcher>` widget is displayed normally.
 
 |!Attribute |!Description |
-
 |selector |A CSS selector. Only events originating inside a DOM node with this selector will be trapped |
+|matchSelector |<<.from-version "5.2.2">> An optional CSS selector. Only events targetting DOM nodes matching this selector will be trapped |
 |//{any attributes starting with $}// |<<.from-version "5.2.0">> Each attribute name (excluding the $) specifies the name of an event, and the value specifies the action string to be invoked. For example: `$click=<<clickActions>>`  |
 |tag |Optional. The HTML element the widget creates to capture the events, defaults to:<br>» `span` when parsed in inline-mode<br>» `div` when parsed in block-mode |
 |class |Optional. A CSS class name (or names) to be assigned to the widget HTML element |
@@ -47,6 +48,8 @@ The following variables are made available to the actions:
 |`event-type` |The type property of the JavaScript event |
 |`event-detail-*` |Any properties in the detail attribute of the event are made available with the prefix `event-detail-` |
 |`tv-popup-coords` |A co-ordinate string that can be used with the ActionPopupWidget to trigger a popup at the DOM node matching the selector where the event originated |
+|`tv-widgetnode-width` |<<.from-version "5.2.3">> `offsetWidth` of the DOM node created by the eventcatcher widget |
+|`tv-widgetnode-height` |<<.from-version "5.2.3">> `offsetHeight` of the DOM node created by the eventcatcher widget |
 |`tv-selectednode-posx` |`x` offset position of the selected DOM node |
 |`tv-selectednode-posy` |`y` offset position of the selected DOM node  |
 |`tv-selectednode-width` |`offsetWidth` of the selected DOM node |

package/editions/tw5.com/tiddlers/widgets/FieldManglerWidget.tid

@@ -1,9 +1,9 @@
+caption: fieldmangler
 created: 20131024141900000
-modified: 20150220161229000
-tags: Widgets
+modified: 20211009122821085
+tags: Widgets MessageHandlerWidgets
 title: FieldManglerWidget
 type: text/vnd.tiddlywiki
-caption: fieldmangler
 
 ! Introduction
 

package/editions/tw5.com/tiddlers/widgets/ImageWidget.tid

@@ -1,8 +1,9 @@
-title: ImageWidget
+caption: image
 created: 20140416160234142
-modified: 20140820100234142
+modified: 20220721102303815
 tags: Widgets
-caption: image
+title: ImageWidget
+type: text/vnd.tiddlywiki
 
 ! Introduction
 
@@ -19,9 +20,18 @@ Any content of the `<$image>` widget is ignored.
 |tooltip |The tooltip to be displayed over the image |
 |alt |The alternative text to be associated with the image |
 |class |CSS classes to be assigned to the `<img>` element |
+|loading|<<.from-version "5.2.3">>Optional. Set to `lazy` to enable lazy loading of images loaded from an external URI |
 
 The width and the height can be specified as pixel values (eg "23" or "23px") or percentages (eg "23%"). They are both optional; if not provided the browser will use CSS rules to size the image.
 
+! Image Status Classes
+
+<<from-version "5.2.2">> The following CSS classes are automatically added to the `<img>` element to indicate the status of the image. Note that only one of these classes will be added at the same time.
+
+|''tc-image-loading'' |When the image is being loaded |
+|''tc-image-loaded'' |The image has been loaded successfully |
+|''tc-image-error'' |The image could not be loaded |
+
 ! External Images and the ''_canonical_uri'' field
 
 When used to display tiddler-based images, the image widget operates in two distinct modes:

package/editions/tw5.com/tiddlers/widgets/JSONTiddlerWidget.tid

@@ -1,14 +1,15 @@
-title: JSONTiddlerWidget
+caption: jsontiddler
 created: 20210630100923398
-modified: 20210630100923398
+modified: 20220427171128693
 tags: Widgets
-caption: jsontiddler
+title: JSONTiddlerWidget
+type: text/vnd.tiddlywiki
 
 ! Introduction
 
 The jsontiddler widget renders the fields of a tiddler to display as a JSON object. The fields of the tiddler can be customised or excluded.
 
-The jsontiddler widget is used in system templates to generate JSON representations of tiddlers for saving.
+The jsontiddler widget is used in system templates to generate JSON representations of tiddlers for saving. See [[JSON in TiddlyWiki]] for an overview.
 
 ! Content and Attributes
 

package/editions/tw5.com/tiddlers/widgets/KeyboardWidget.tid

@@ -1,7 +1,7 @@
 caption: keyboard
 created: 20140302192136805
-modified: 20210612101618855
-tags: Widgets
+modified: 20211009121239821
+tags: Widgets TriggeringWidgets
 title: KeyboardWidget
 type: text/vnd.tiddlywiki
 

package/editions/tw5.com/tiddlers/widgets/LetWidget.tid

@@ -0,0 +1,57 @@
+title: LetWidget
+created: 20211028115900000
+tags: Widgets
+caption: let
+
+! Introduction
+
+<<.from-version "5.2.1">> The <<.wid let>> widget allows multiple variables to be set in one operation. In some situations it can result in simpler code than using the more flexible <<.wlink SetWidget>> widget. It differs from the <<.wlink VarsWidget>> widget in that variables you're defining may depend on earlier variables defined within the same <<.wid let>>.
+
+! Content and Attributes
+
+The content of the <<.wid let>> widget is the scope for the value assigned to the variable.
+
+|!Attribute |!Description |
+|//{attributes not starting with $}// |Each attribute name specifies a variable name. The attribute value is assigned to the variable |
+
+Attributes are evaluated in the order they are written. Attributes with the same name are allowed. Each time a duplicate attribute is encountered, it will replace the existing value set by the earlier duplicate.
+
+! Examples
+
+Consider a case where you need to set multiple variables, where some depend on the evaluation of others.
+
+Using the <<.wid let>> widget, this situation may be handled in the following way:
+
+```
+\define helloworld() Hello world!
+
+<$let target="MyTiddler" currentTiddler={{{ [<target>prefix[$:/settings/for/]] }}} settings={{!!text}} currentTiddler=<<target>> >
+  The settings for <<currentTiddler>> are: <<settings>>
+</$let>
+```
+
+In contrast, here is the same example using the <<.wid set>> widget:
+
+```
+<$set name="target" value="MyTiddler" >
+<$set name="currentTiddler" value={{{ [<target>prefix[$:/settings/for/]] }}} >
+<$set name="settings" value={{!!text}} >
+<$set name="currentTiddler" value=<<target>> >
+  The settings for <<currentTiddler>> are: <<settings>>
+</$set>
+</$set>
+</$set>
+</$set>
+```
+
+! Remarks
+
+This widget differs from <<.wid vars>> in the following way:
+
+* Each variable's definition will be immediately available to all proceeding variables in the same let widget. This differs from vars, in which definitions which depend on some variable will always look to the widget's outer scope for a value.
+
+This widget differs from <<.wid set>> in the following ways:
+
+* A fallback (also known as "emptyValue") cannot be specified
+* Filters cannot be used to produce a conditional variable assignment
+* Variable names must be literal strings

package/editions/tw5.com/tiddlers/widgets/LinkCatcherWidget.tid

@@ -1,7 +1,7 @@
 caption: linkcatcher
 created: 20131024141900000
-modified: 20170707111536556
-tags: Widgets
+modified: 20220226121122574
+tags: Widgets MessageHandlerWidgets TriggeringWidgets
 title: LinkCatcherWidget
 type: text/vnd.tiddlywiki
 
@@ -25,3 +25,4 @@ The content of the `<$linkcatcher>` widget is displayed normally.
 |setTo |Value to be assigned by the `set` attribute |
 |actions |Actions to be performed when a link is caught. Within the action string, the variable "navigateTo" contains the title of the tiddler being navigated. <<.from-version "5.1.23">> the <<.def "modifier">> variable lists the modifier keys that are pressed when the action is invoked. The possible modifiers are ''ctrl'', ''ctrl-alt'', ''ctrl-shift'', ''alt'', ''alt-shift'', ''shift'' and ''ctrl-alt-shift'' |
 
+<<.tip """<<.from-version "5.2.0">> For more complex use cases involving trapping the <<.param tm-navigate>> message consider the MessageCatcherWidget which provides greater flexibility""">>

package/editions/tw5.com/tiddlers/widgets/ListWidget.tid

@@ -1,6 +1,6 @@
 caption: list
 created: 20131024141900000
-modified: 20210416175333981
+modified: 20220718120325494
 tags: Widgets Lists
 title: ListWidget
 type: text/vnd.tiddlywiki
@@ -117,7 +117,7 @@ Displays as:
 </$list>
 <<<
 
-Note that using the `counter` attribute can degrade the performance of the list widget in certain circumstances. In particular, it prevents an optimisation that normally occurs when dynamically adding or removing entries.
+Note that using the `counter` attribute can reduce performance when working with list items that dynamically reorder or update themselves. The best advice is only to use it when it is really necessary: to obtain a numeric index, or to detect the first or last entries in the list.
 
 !! Edit mode
 

package/editions/tw5.com/tiddlers/widgets/ListopsData.tid

@@ -3,5 +3,6 @@ daysoftheweek: four three Fri Thu Wed Tue Mon
 modified: 20151108041839747
 title: ListopsData
 type: application/x-tiddler-dictionary
+tags: [[Operator Examples]]
 
 DataIndex: 

package/editions/tw5.com/tiddlers/widgets/MacroCallWidget.tid

@@ -1,6 +1,6 @@
 caption: macrocall
 created: 20131024141900000
-modified: 20200928102843275
+modified: 20220122193731433
 tags: Widgets
 title: MacroCallWidget
 type: text/vnd.tiddlywiki
@@ -38,6 +38,8 @@ You can see several examples of the macro call widget within the core:
 * Listing field information: [[$:/snippets/allfields]]
 * Generating `data:` URIs: [[$:/themes/tiddlywiki/starlight/styles.tid]]
 
+See also [[WikiText parser mode: macro examples]]
+
 ! Content and Attributes
 
 The content of the `<$macrocall>` widget is ignored.

package/editions/tw5.com/tiddlers/widgets/MessageCatcherWidget.tid

@@ -1,6 +1,6 @@
 created: 20210309133636211
-modified: 20210711193113104
-tags: Widgets
+modified: 20211222153049771
+tags: Widgets MessageHandlerWidgets TriggeringWidgets
 title: MessageCatcherWidget
 type: text/vnd.tiddlywiki
 
@@ -37,7 +37,7 @@ The message catcher widget sets the following variables within each action strin
 <$action-log/>
 \end
 
-<$messagecatcher type="tm-navigate" actions=<<actions>>>
+<$messagecatcher $tm-navigate=<<actions>>>
 
 Click on [[this link]] to fire an action. See the browser JavaScript console for the output
 

package/editions/tw5.com/tiddlers/widgets/MessageHandlerWidgets.tid

@@ -0,0 +1,13 @@
+created: 20211031174746965
+modified: 20211113163856255
+tags: Widgets
+title: MessageHandlerWidgets
+type: text/vnd.tiddlywiki
+
+Message handler widgets are those widgets which can react to one or more [[widget messages|Messages]].
+
+<<.tip "Widget messages are similar to low-level DOM events, except they are higher-level and specific to TiddlyWiki. To handle DOM events see the EventCatcherWidget">>
+
+The following message handler widgets are provided:
+
+<<list-links "[tag[MessageHandlerWidgets]]">>

package/editions/tw5.com/tiddlers/widgets/NavigatorWidget.tid

@@ -1,7 +1,7 @@
 caption: navigator
 created: 20131024141900000
-modified: 20170629074415261
-tags: Widgets
+modified: 20211127023932158
+tags: Widgets MessageHandlerWidgets
 title: NavigatorWidget
 type: text/vnd.tiddlywiki
 
@@ -39,3 +39,6 @@ The following [[Variables]] are assigned by the navigator widget:
 * <<.vlink tv-story-list>>, giving the name of the tiddler containing the story list
 * <<.vlink tv-history-list>>, giving the name of the tiddler containing the history list
 
+! Examples
+
+See [[Creating SubStories]].

package/editions/tw5.com/tiddlers/widgets/QualifyWidget.tid

@@ -0,0 +1,39 @@
+caption: vars
+created: 20220125160004463
+modified: 20220125163041347
+tags: Widgets
+title: QualifyWidget
+
+! Introduction
+
+The <<.wid qualify>> widget sets a variable
+to a unique string that encodes its position within the widget tree, as identified by the stack of transcluded tiddlers that lead to that position.
+
+Internally, it is implemented using the transclusion variable.
+
+! Content and Attributes
+
+The content of the <<.wid qualify>> widget is the scope for the value assigned to the <<.var name>> variable.
+
+|!Attribute |!Description |
+|//title// |The prefix for the string, normally a tiddler title |
+|//name// |The name of the variable to be set to the unique string |
+
+! Examples
+
+The two examples below are identical, but produce different results because the second one has been transcluded from [[another tiddler|$:/editions/tw5.com/widget-examples/qualify-transcluded]].
+
+Each example shows the result of calling <<.var qualify>> and then the value of the <<.vlink transclusion>> variable.
+<$macrocall $name=".example" n="1"
+eg="""<$qualify title="BaseTiddler" name="iamnotanumber">
+<ul>
+<li><code><<iamnotanumber>></code></li>
+<li><code><<transclusion>></code></li>
+</ul>
+</$qualify>
+"""/>
+{{$:/editions/tw5.com/widget-examples/qualify-transcluded}}
+
+! Remarks
+
+In most cases it will be simpler to use the [[qualify Macro]].

package/editions/tw5.com/tiddlers/widgets/RadioWidget.tid

@@ -1,7 +1,7 @@
 caption: radio
 created: 20131212195353929
-modified: 20210307154753471
-tags: Widgets
+modified: 20211009121654734
+tags: Widgets TriggeringWidgets
 title: RadioWidget
 type: text/vnd.tiddlywiki
 

package/editions/tw5.com/tiddlers/widgets/RangeWidget.tid

@@ -1,7 +1,7 @@
 caption: range
 created: 20171102134825376
-modified: 20201130193635857
-tags: Widgets
+modified: 20211009121606405
+tags: Widgets TriggeringWidgets
 title: RangeWidget
 type: text/vnd.tiddlywiki
 

package/editions/tw5.com/tiddlers/widgets/ScrollableWidget.tid

@@ -1,9 +1,9 @@
+caption: scrollable
 created: 20140324223413403
-modified: 20150427123524945
+modified: 20220620115347910
 tags: Widgets
 title: ScrollableWidget
 type: text/vnd.tiddlywiki
-caption: scrollable
 
 ! Introduction
 
@@ -17,7 +17,7 @@ The content of the `<$scrollable>` widget is displayed within a pair of wrapper
 |class |The CSS class(es) to be applied to the outer DIV |
 |fallthrough |See below |
 
-If a scrollable widget can't handle the `tm-scroll` message because the inner DIV fits within the outer DIV, then by default the message falls through to the parent widget. Setting the ''fallthrough'' attribute to `no` prevents this behaviour.
+<$macrocall $name=".note" _="""If a scrollable widget can't handle the `tm-scroll` message because the inner DIV fits within the outer DIV, then by default the message falls through to the parent widget. Setting the ''fallthrough'' attribute to `no` prevents this behaviour."""/> 
 
 ! Examples