tiddlywiki 5.1.21 → 5.2.1

package/editions/tw5.com/tiddlers/webserver/Using the external JavaScript template.tid

@@ -1,19 +1,100 @@
 created: 20180905075846391
-modified: 20180905080955513
+modified: 20210611055708739
 tags: [[WebServer Guides]]
 title: Using the external JavaScript template
 type: text/vnd.tiddlywiki
 
-Setting the [[root-tiddler|WebServer Parameter: root-tiddler]] parameter to `$:/core/save/all-external-js` switches to a special template that externalises TiddlyWiki's core JavaScript into a separate file. For example:
+You can use a special template to externalise TiddlyWiki's core code into a separate file. This configuration allows the browser to cache the core for improved efficiency. 
+
+! Background
+
+TiddlyWiki in the single file configuration ordinarily packs everything into a single file: your data, and the ~JavaScript, CSS and HTML comprising TiddlyWiki itself. This lack of dependencies is usually very convenient: it means that it is impossible for the parts of a TiddlyWiki to become separated, and enormously improves the chances of it still functioning in the future.
+
+However, there is some inefficiency in this arrangement because the core code is repeatedly loaded and saved every time the content of the wiki is saved. This inefficiency is partially ameliorated when working in the client server configuration because once the wiki is loaded by the browser the synchronisation process only transmits individual tiddlers back and forth to the server.
+
+The remaining inefficiency when working in the client server configuration is that the single page wiki that is initially loaded will contain a copy of the entire core code of TiddlyWiki, making it impossible for the browser to cache it.
+
+! Using the external JavaScript template with the client-server configuration
+
+The mechanism is activated by setting the [[root-tiddler|WebServer Parameter: root-tiddler]] parameter to `$:/core/save/all-external-js`. This template externalises TiddlyWiki's core JavaScript into a separate file. For example, the following command will start your server with caching enabled. It will transfer the wiki with two GET requests, and the core can be cached by the browser.
 
 ```
-tiddlywiki editions/tw5.com-server/ --listen host=0.0.0.0 "root-tiddler=$:/core/save/all-external-js"
+tiddlywiki YOUR_WIKI_FOLDER --listen 'root-tiddler=$:/core/save/all-external-js' use-browser-cache=yes
 ```
 
-!! Background
+<<.tip """You can activate your browser's ''Developer Tools: Network'' tab and reload the page to see how it works.""">>
 
-TiddlyWiki in the single file configuration ordinarily packs everything into a single file: your data, and the JavaScript, CSS and HTML comprising TiddlyWiki itself. This lack of dependencies is usually very convenient: it means that it is impossible for the parts of a TiddlyWiki to become separated, and enormously improves the chances of it still functioning in the future.
+<<.tip """On Windows, Command Prompt (CMD) users need to replace single quotes `'` with double quotation marks `"`.""">>
 
-However, there is some inefficiency in this arrangement because the core code is repeatedly loaded and saved every time the content of the wiki is saved. This inefficiency is partially ameliorated when working in the client server configuration because once the wiki is loaded by the browser the synchronisation process only transmits individual tiddlers back and forth to the server.
+!! Initializing a new wiki
+
+The provided edition `server-external-js` contains all the configuration necessary to use the external ~JavaScript template. Here is an example:
+
+```
+tiddlywiki ./myNewWiki --init server-external-js
+tiddlywiki ./myNewWiki --build listen
+```
+
+The above commands perform the following:
+
+* Create a new wiki with external JavaScript customization included.
+* Start the server with external JavaScript enabled. The server listens on port 8080. Visit http://localhost:8080 in your browser.
+
+To customize your `--build listen` command, see [[tiddlywiki.info Files]] and [[ListenCommand]].
+
+! Using the external JavaScript template with the single file configuration
+
+You can use the "external-js" template with your single file wiki, but this requires that you have ~TiddlyWiki's core ~JavaScript saved alongside your HTML file. You may prefer this configuration, for example, if you have several wikis on a ~WebDav server. (See: [[Saving via WebDAV]])
+
+<<.warning "This functionality is intended for advanced users: there are many more ways for things to go wrong than with the standard single file configuration">>
+
+!! Saving your snapshots
+
+If you start your ~TiddlyWiki server in the "external-js" configuration, snapshots you save from the wiki will also have the external-js configuration.
+
+You can click on the "cloud" button and choose <<.icon $:/core/images/download-button>>  ''Save snapshot for offline use''. The html wiki you saved will have a reduced file size compared to a regular snapshot because the ~TiddlyWiki core code has been externalized. However, to be able to use this wiki, you ''must'' also have a copy of ~TiddlyWiki's core ~JavaScript in the same directory; see below for instructions for obtaining it
+
+The "server-external-js" edition lets you save the snapshot from the command line:
+
+```
+tiddlywiki YOUR_WIKI_FOLDER --build index
+```
+
+The files `index.html` and `tiddlywikicore-5.x.x.js` will be saved in your wiki folder's `output` directory.
+
+!! Obtaining the ~TiddlyWiki core in the browser
+
+To download a copy of the TiddlyWiki core JavaScript file from any existing TiddlyWiki, visit the system tiddler $:/core/ui/ExportTiddlyWikiCore and click the download button. (You can search for ''~ExportTiddlyWikiCore'' in the ''Shadows'' tab of $:/AdvancedSearch).
+
+!! Obtaining the ~TiddlyWiki core with Node.js
+
+You can also run the following command to obtain the core ~JavaScript. The file `tiddlywikicore-5.x.x.js` will be saved in the`output` directory of your wiki folder:
+
+```
+tiddlywiki YOUR_WIKI_FOLDER \
+    --render '$:/core/templates/tiddlywiki5.js' \
+    '[[tiddlywikicore-]addsuffix<version>addsuffix[.js]]' \
+    'text/plain'
+```
+
+The "server-external-js" edition has a shortcut for the BuildCommand to do the same thing:
+
+```
+tiddlywiki YOUR_WIKI_FOLDER --build tiddlywikicore
+```
+
+! Upgrading your standalone wiki
+
+<<.warning "This procedure is experimental, please take care to backup your data">>
+
+Before you proceed, backup your wiki first! Follow the steps below to upgrade a single-file wiki with the external JavaScript template:
+
+# Proceed with the [[Upgrade Process for Standalone TiddlyWikis|Upgrading]]. Your wiki will be converted to a full standalone HTML.
+
+# Open your upgraded wiki in the browser. If you'd like to revert to using the regular template, restore the original shadow tiddler `$:/config/SaveWikiButton/Template` by deleting any custom copy. Save your wiki and you are done. 
+
+# Otherwise, from your wiki, select the ''Tools'' tab from the sidebar and click on the <<.icon $:/core/images/star-filled>> ''export tiddlywiki core'' button to obtain the core from your wiki.
+
+# Verify that `$:/config/SaveWikiButton/Template` still contains `$:/core/save/offline-external-js`. Modify if necessary.
 
-The remaining inefficiency when working in the client server configuration is that the single page wiki that is initially loaded will contain a copy of the entire core code of TiddlyWiki, making it impossible for the browser to cache it.
+# Save your wiki again. Your wiki is now converted to using the external core.

package/editions/tw5.com/tiddlers/webserver/WebServer API_ Delete Tiddler.tid

@@ -1,5 +1,5 @@
 created: 20181002112106875
-modified: 20181002124355314
+modified: 20210418100750769
 tags: [[WebServer API]]
 title: WebServer API: Delete Tiddler
 type: text/vnd.tiddlywiki
@@ -14,6 +14,10 @@ Parameters:
 
 * ''title'' - URI encoded title of the tiddler to delete
 
+Headers:
+
+* ''x-requested-with'' - must be set to `TiddlyWiki` in order for the request to succeed, unless [[WebServer Parameter: csrf-disable]] is set to `yes`
+
 Response:
 
 * 204 No Content

package/editions/tw5.com/tiddlers/webserver/WebServer API_ Get All Tiddlers.tid

@@ -1,5 +1,5 @@
 created: 20181002131215403
-modified: 20190903094711346
+modified: 2020031109590546
 tags: [[WebServer API]]
 title: WebServer API: Get All Tiddlers
 type: text/vnd.tiddlywiki
@@ -12,11 +12,23 @@ GET /recipes/default/tiddlers.json
 
 Parameters:
 
-* none
+* ''filter'' - filter identifying tiddlers to be returned (optional, defaults to "[all[tiddlers]!is[system]sort[title]]")
+* ''exclude'' - comma delimited list of fields to excluded from the returned tiddlers (optional, defaults to "text")
 
-Response:
+In order to avoid denial of service attacks with malformed filters in the default configuration the only filter that is accepted is the default filter "[all[tiddlers]!is[system]sort[title]]"; attempts to use any other filter will result in an HTTP 403 error.
+
+To enable a particular filter, create a tiddler with the title "$:/config/Server/ExternalFilters/" concatenated with the filter text, and the text field set to "yes". For example, the TiddlyWeb plugin includes the following shadow tiddler to enable the filter that it requires:
 
+```
+title: $:/config/Server/ExternalFilters/[all[tiddlers]] -[[$:/isEncrypted]] -[prefix[$:/temp/]] -[prefix[$:/status/]]
+text: yes
+```
+
+It is also possible to configure the server to accept any filter by creating a tiddler titled $:/config/Server/AllowAllExternalFilters with the text "yes". This should not be done for public facing servers.
+
+Response:
 
 * 200 OK
 *> `Content-Type: application/json`
 *> Body: array of all non-system tiddlers in [[TiddlyWeb JSON tiddler format]] 
+* 403 Forbidden

package/editions/tw5.com/tiddlers/webserver/WebServer API_ Put Tiddler.tid

@@ -1,5 +1,5 @@
 created: 20181002131341062
-modified: 20181002131556452
+modified: 20210418100750769
 tags: [[WebServer API]]
 title: WebServer API: Put Tiddler
 type: text/vnd.tiddlywiki
@@ -16,6 +16,10 @@ Parameters:
 
 * ''title'' - URI encoded title of the tiddler to save
 
+Headers:
+
+* ''x-requested-with'' - must be set to `TiddlyWiki` in order for the request to succeed, unless [[WebServer Parameter: csrf-disable]] is set to `yes`
+
 Response:
 
 * 204 No Content

package/editions/tw5.com/tiddlers/webserver/WebServer Parameter_ path-prefix.tid

@@ -1,14 +1,19 @@
 caption: path-prefix
 created: 20180630180514893
-modified: 20180702154716090
+modified: 20201027122943281
 tags: [[WebServer Parameters]]
 title: WebServer Parameter: path-prefix
 type: text/vnd.tiddlywiki
 
 The [[web server configuration parameter|WebServer Parameters]] ''path-prefix'' can be used to set an optional prefix for all paths served.
 
-This example causes the server to serve from http://127.0.0.1/MyApp instead of the default http://127.0.0.1/MyApp.
+This example causes the server to serve from http://127.0.0.1/MyApp instead of the default http://127.0.0.1/.
 
 ```
 tiddlywiki mywikifolder --listen "path-prefix=/MyApp"
 ```
+
+Notes:
+
+* Further steps are required to configure the client-side components to use the prefix. See [[Using a custom path prefix with the client-server edition]]
+* If no path prefix is required then the `path-prefix` parameter should be omitted or set to the empty string, and not to `\` as might be expected

package/editions/tw5.com/tiddlers/webserver/WebServer Parameter_ port.tid

@@ -1,6 +1,6 @@
 caption: port
 created: 20180630180552254
-modified: 20180702155017130
+modified: 20191219123751824
 tags: [[WebServer Parameters]]
 title: WebServer Parameter: port
 type: text/vnd.tiddlywiki
@@ -10,6 +10,7 @@ The [[web server configuration parameter|WebServer Parameters]] ''port'' specifi
 The ''port'' parameter accepts two types of value:
 
 * Numerical values are interpreted as a decimal port number
+** The special value 0 (zero) causes the operating system to assign an available port
 * Non-numeric values are interpreted as an environment variable from which the port should be read
 
 This example configures the server to listen on port 8090:

package/editions/tw5.com/tiddlers/webserver/WebServer Parameter_ tiddler-render-type.tid

@@ -5,6 +5,6 @@ tags: [[WebServer Parameters]]
 title: WebServer Parameter: tiddler-render-type
 type: text/vnd.tiddlywiki
 
-The [[web server configuration parameter|WebServer Parameters]] ''tiddler-render-type'' is used to specify the render type for serving ordinary, non-system tiddlers in the [[read-only single tiddler view|Using the read-only single tiddler view]]. The default value is `text/html`, causing the full HTML of the rendered output to be returned. Alternatively, `text/html` can be used to cause the raw text of rendered system tiddlers to be returned.
+The [[web server configuration parameter|WebServer Parameters]] ''tiddler-render-type'' is used to specify the render type for serving ordinary, non-system tiddlers in the [[read-only single tiddler view|Using the read-only single tiddler view]]. The default value is `text/html`, causing the full HTML of the rendered output to be returned. Alternatively, `text/plain` can be used to cause the raw text of rendered system tiddlers to be returned.
 
-<<.tip "This setting may be overwritten by specifying the `_render_type` field of a tiddler.">>
+<<.tip "This setting may be overwritten by specifying the `_render_type` field of a tiddler.">>

package/editions/tw5.com/tiddlers/widgets/$__docs_anyField.tid

@@ -0,0 +1,8 @@
+created: 20210505094244703
+field: list
+modified: 20210505094434740
+tags: 
+title: $:/docs/anyField
+type: text/vnd.tiddlywiki
+
+This tiddler is needed for the last [[SetWidget]] example

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

@@ -0,0 +1,40 @@
+caption: action-confirm
+created: 20201115150255011
+modified: 20201115160335288
+tags: Widgets ActionWidgets
+title: ActionConfirmWidget
+type: text/vnd.tiddlywiki
+
+! Introduction
+
+<<.from-version "5.1.23">>The ''action-confirm'' widget is an [[action widget|ActionWidgets]] that prompts the user for confirmation and invokes other action widgets contained within it only if the user confirms. ActionWidgets are used within triggering widgets such as the ButtonWidget.
+
+! Content and Attributes
+
+The ''action-confirm'' widget is invisible. Any content within it is only processed if the user confirms the action, or the confirmation has been disabled by the `$prompt` attribute.
+
+|!Attribute |!Description |
+|$message |Optional message displayed to the user when asking for confirmation.|
+|$prompt |Optional flag, set to "no" to disable the prompt for confirmation. Defaults to "yes" |
+
+! Examples
+
+Here is an example of a button that asks the user for confirmation, before deleting the caption and tags fields of the current tiddler:
+
+<$macrocall $name='wikitext-example-without-html'
+src='<$button>
+<$action-confirm $message="Do you wish to delete the caption and tags?">
+<$action-deletefield caption tags/>
+Delete "caption" and "tags"
+</$action-confirm>
+</$button>'/>
+
+Here is an example of a button that uses the optional `$prompt` attribute to control whether to prompt the user before deleting the text field of the tiddler HelloThere:
+
+<$macrocall $name='wikitext-example-without-html'
+src='<$button>
+<$action-confirm $message="Do you wish to delete the text field?" $prompt={{$:/state/promptUser}}>
+<$action-deletefield $tiddler="HelloThere" $field="text"/>
+</$action-confirm>
+Delete text from ~HelloThere
+</$button>'/>

package/editions/tw5.com/tiddlers/widgets/ActionCreateTiddlerWidget Example 1.tid

@@ -0,0 +1,26 @@
+created: 20200131142401129
+modified: 20211113230406823
+tags: ActionCreateTiddlerWidget Widgets
+title: ActionCreateTiddlerWidget Example 1
+type: text/vnd.tiddlywiki
+
+\define testCreate()
+<$action-createtiddler />
+\end
+
+This example will create "New Tiddler", "New Tiddler 1", " New Tiddler 2" and so on
+
+```
+\define testCreate()
+<$action-createtiddler />
+\end
+
+<$button actions=<<testCreate>> >
+Create Tiddler
+</$button>
+```
+
+<$button actions=<<testCreate>> >
+<$action-setfield $tiddler="$:/state/tab/sidebar--595412856" text="$:/core/ui/SideBar/Recent"/>
+Create Tiddler
+</$button> - Clicking this button, will also open the Right sidebar: Recent tab

package/editions/tw5.com/tiddlers/widgets/ActionCreateTiddlerWidget Example 2.tid

@@ -0,0 +1,28 @@
+created: 20200131144828713
+modified: 20211113011036840
+tags: ActionCreateTiddlerWidget Widgets
+title: ActionCreateTiddlerWidget Example 2
+type: text/vnd.tiddlywiki
+
+\define testCreate()
+<$action-createtiddler $basetitle={{$:/language/DefaultNewTiddlerTitle}} $overwrite="yes"/>
+\end
+
+This example will use the base title defined in [[$:/language/DefaultNewTiddlerTitle]]. 
+
+It will overwrite the tiddler, if the button is clicked several times.
+
+```
+\define testCreate()
+<$action-createtiddler $basetitle={{$:/language/DefaultNewTiddlerTitle}} $overwrite="yes"/>
+\end
+
+<$button actions=<<testCreate>> >
+Create Tiddler
+</$button>
+```
+
+<$button actions=<<testCreate>> >
+<$action-setfield $tiddler="$:/state/tab/sidebar--595412856" text="$:/core/ui/SideBar/Recent"/>
+Create Tiddler
+</$button> - Clicking this button, will also open the Right sidebar: Recent tab

package/editions/tw5.com/tiddlers/widgets/ActionCreateTiddlerWidget Example 3.tid

@@ -0,0 +1,28 @@
+created: 20200131145355658
+modified: 20211113011111052
+tags: ActionCreateTiddlerWidget Widgets
+title: ActionCreateTiddlerWidget Example 3
+type: text/vnd.tiddlywiki
+
+\define testCreate()
+<$action-createtiddler $basetitle="base" $template="ActionCreateTiddlerWidget Template"/>
+\end
+
+This example will uses a base-title and a template: [[ActionCreateTiddlerWidget Template]]
+
+It will create: "base", "base 1", "base 2" and so on 
+
+```
+\define testCreate()
+<$action-createtiddler $basetitle="base" $template="ActionCreateTiddlerWidget Template"/>
+\end
+
+<$button actions=<<testCreate>> >
+Create Tiddler
+</$button>
+```
+
+<$button actions=<<testCreate>> >
+<$action-setfield $tiddler="$:/state/tab/sidebar--595412856" text="$:/core/ui/SideBar/Recent"/>
+Create Tiddler
+</$button> - Clicking this button will also open the Right sidebar: Recent tab

package/editions/tw5.com/tiddlers/widgets/ActionCreateTiddlerWidget Example 4.tid

@@ -0,0 +1,28 @@
+created: 20200131150229551
+modified: 20211113011129601
+tags: ActionCreateTiddlerWidget Widgets
+title: ActionCreateTiddlerWidget Example 4
+type: text/vnd.tiddlywiki
+
+\define testCreate()
+<$action-createtiddler $basetitle="base" $template="ActionCreateTiddlerWidget Template" aa="new field aa" bb="new field bb" />
+\end
+
+This example uses a base-title "base" and a template: [[ActionCreateTiddlerWidget Template]].
+
+There will be new fields "aa" and "bb" which are added to the new tiddlers.
+
+```
+\define testCreate()
+<$action-createtiddler $basetitle="base" $template="ActionCreateTiddlerWidget Template" aa="new field aa" bb="new field bb" />
+\end
+
+<$button actions=<<testCreate>> >
+Create Tiddler
+</$button>
+```
+
+<$button actions=<<testCreate>> >
+<$action-setfield $tiddler="$:/state/tab/sidebar--595412856" text="$:/core/ui/SideBar/Recent"/>
+Create Tiddler
+</$button> - Clicking this button will also open the Right sidebar: Recent tab

package/editions/tw5.com/tiddlers/widgets/ActionCreateTiddlerWidget Template.tid

@@ -0,0 +1,8 @@
+created: 20200131145608087
+modified: 20211116192551162
+tags: test [[Widget Examples]]
+title: ActionCreateTiddlerWidget Template
+type: text/vnd.tiddlywiki
+x: x
+
+This is a tiddler used as a template in: [[ActionCreateTiddlerWidget Example 3]]

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

@@ -1,6 +1,6 @@
 caption: action-createtiddler
 created: 20161020152745942
-modified: 20190604113017742
+modified: 20210601092956998
 tags: Widgets ActionWidgets
 title: ActionCreateTiddlerWidget
 type: text/vnd.tiddlywiki
@@ -16,16 +16,49 @@ There are several differences from the [[tm-new-tiddler message|WidgetMessage: t
 
 ! Content and Attributes
 
-The ''action-createtiddler'' widget is invisible. Any content within it is ignored.
+The ''action-createtiddler'' widget is invisible.
+
+<<.from-version "5.2.0">> The action widgets contained within the ''action-createtiddler'' widget are executed after the new tiddler has been created with the title of the tiddler in the variable `createTiddler-title` and `createTiddler-draftTitle`.
 
 |!Attribute |!Description |
 |$basetitle |The initial title that will be attempted. If a tiddler with that title already exists, then a numerical counter is added to the title and incremented until it is unique|
-|$savetitle |A text reference identifying a field or index into which the title of the newly created tiddler will be stored after it is created |
-|$savedrafttitle |<<.from-version "5.1.20">> A text reference identifying a field or index into which the draft title associated with the newly created tiddler will be stored after it is created. This is useful when using a sequence of action widgets to create a new tiddler, put it into edit mode, and position it within the list of its parent tag |
+|$savetitle |//(deprecated – see below)// A text reference identifying a field or index into which the title of the newly created tiddler will be stored after it is created |
+|$savedrafttitle |//(deprecated – see below)// <<.from-version "5.1.20">> A text reference identifying a field or index into which the draft title associated with the newly created tiddler will be stored after it is created. This is useful when using a sequence of action widgets to create a new tiddler, put it into edit mode, and position it within the list of its parent tag |
 |$timestamp |Specifies whether the timestamp(s) of the target tiddler will be updated (''modified'' and ''modifier'', plus ''created'' and ''creator'' for newly created tiddlers). Can be "yes" (the default) or "no" |
+|$template |<<.from-version "5.1.22">> The title of a template tiddler, that will be used to create a new tiddler |
+|$overwrite |<<.from-version "5.1.22">> If set to "yes", it will overwrite existing tiddlers. ''Be careful!'' |
 |//{any attributes not starting with $}// |Each attribute name specifies a field to be created in the new tiddler  |
 
+<<.from-version "5.2.0">> Note that the attributes `$savetitle` and `$savedrafttitle` are no longer needed. Instead, any action widgets that need to use the title of the newly created tiddler should be contained within the ''action-createtiddler'' widget, and reference the variables `createTiddler-title` and `createTiddler-draftTitle` to obtain the title.
+
 ! Examples
 
-<$macrocall $name='wikitext-example-without-html'
-src={{ActionCreateTiddlerWidget Example}}/>
+<<<
+<$macrocall $name='wikitext-example-without-html' src={{ActionCreateTiddlerWidget Example}}/>
+<<<
+
+---
+
+<<<
+<$transclude tiddler="ActionCreateTiddlerWidget Example 1" mode=block/>
+<<<
+
+---
+
+<<<
+{{ActionCreateTiddlerWidget Example 2}}
+<<<
+
+---
+
+<<<
+{{ActionCreateTiddlerWidget Example 3}}
+<<<
+
+---
+
+<<<
+{{ActionCreateTiddlerWidget Example 4}}
+<<<
+
+

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

@@ -1,12 +1,14 @@
 created: 20161020153426686
-modified: 20161020155142990
-tags: ActionCreateTiddlerWidget
+modified: 20211113011019510
+tags: ActionCreateTiddlerWidget Widgets
 title: ActionCreateTiddlerWidget Example
 type: text/vnd.tiddlywiki
 
-New button caption: <$edit-text tiddler="$:/state/new-button-caption" tag="input" default=""/>
+Caption for new button: <$edit-text tiddler="$:/state/new-button-caption" tag="input" default=""/>
 
 <$button>
-<$action-createtiddler $basetitle="Homemade Button" tags="$:/tags/PageControls" text={{$:/state/new-button-caption}}/>
-Create non-functional page control button
+<$action-createtiddler $basetitle="Homemade Button" tags="$:/tags/PageControls" text={{$:/state/new-button-caption}}>
+<$action-navigate $to=<<createTiddler-title>>/>
+</$action-createtiddler>
+Create a new non-functional page control button and open the tiddler
 </$button>

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

@@ -1,7 +1,7 @@
 caption: action-listops
 created: 20141025120850184
 list: efg hlm pqr
-modified: 20151228083329099
+modified: 20211115091121133
 myfield: 
 revision: 0
 tags: ActionWidgets Widgets
@@ -10,7 +10,7 @@ type: text/vnd.tiddlywiki
 
 \define .operator-rows(filter)
 <$list filter="$filter$"><tr>
-<td><$link to={{!!title}}>{{!!caption}}</$link></td>
+<td><$link>{{!!caption}}</$link></td>
 <td>{{!!op-purpose}} <$list filter="[all[current]tag[Common Operators]]">{{$:/core/images/done-button}}</$list></td>
 <td align="center"><$list filter="[all[current]tag[Negatable Operators]]">`!`</$list></td>
 </tr></$list>
@@ -29,13 +29,63 @@ The ''action-listops'' widget is an [[action widget|ActionWidgets]] that manipul
 The ''action-listops'' widget is invisible. Any content within it is ignored.
 
 |!Attribute |!Description |
-|$tiddler |The title of the tiddler whose lists are to be modified (if not provided defaults to the [[current tiddler|Current Tiddler]] |
+|$tiddler |The title of the tiddler whose lists are to be modified (if not provided defaults to the [[current tiddler|Current Tiddler]]) |
 |$field |The name of a field to be manipulated as a list (defaults to 'list') |
 |$index |Optional index of a property in a [[data tiddler|DataTiddlers]] index to be manipulated as a list |
 |$filter |An optional filter expression, the output of which will be saved to the field/index being manipulated |
 |$subfilter |An optional subfilter expression, which takes the list being manipulated as input, and saves the modified list back to the field/index being manipulated |
 |$tags |An optional subfilter expression, which takes the 'tags' field of the target tiddler as input, and saves the modified list of tags back to the 'tags' field |
 
+! $filter vs. $subfilter
+
+Standalone use of the `$subfilter` attribute can be replaced by using a (more complicated) `$filter` attribute value.
+
+For example, the items "abc" and "123" can be appended to the field `myfield` using the `$subfilter` attribute:
+
+```
+<$action-listops $field="myfield" $subfilter="abc 123"/>
+```
+
+The same can be achieved using the `$filter` attribute and prepending the [[Filter Run]] `[all[current]get[myfield]enlist-input[]]` to the [[Filter Expression]]:
+
+```
+<$action-listops $field="myfield" $filter="[all[current]get[myfield]enlist-input[]] abc 123"/>
+```
+
+The short form is more convenient, but the long form is useful for live-debugging complicated `$subfilter` values using the filter tab of [[$:/AdvancedSearch]]. By using [[$:/AdvancedSearch]], the [[Filter Expression]] can be tested before using ''action-listops'' to modify actual tiddler fields. For this use case, the `all[current]` portion of the expression needs to be changed to select the proper test tiddler.
+
+! $tags vs. $field + $subfilter
+
+[[Tagging]] is implemented using a tiddler's 'tags' field, so appending the tags "abc" and "123" using the `$tags` attribute like this:
+
+```
+<$action-listops $tags="abc 123"/>
+```
+
+is mostly equivalent to using `$subfilter` along with "tags" for the value of `$field`:
+
+```
+<$action-listops $field="tags" $subfilter="abc 123"/>
+```
+
+! $action-listops widget vs. $action-setfield widget
+
+The ActionSetFieldWidget replaces a field's value using `$field`/`$value` attributes. A single ActionSetFieldWidget can be used to set any number of fields by using attributes not starting with $.
+
+The ActionListopsWidget replaces or modifies a single field's value. The new value is generated using filters.
+
+The following two examples are functionally equivalent:
+
+```
+<$action-setfield $field="myfield" $value="abc 123"/>
+```
+
+```
+<$action-listops $field="myfield" $filter="abc 123"/>
+```
+
+In general, ActionSetFieldWidget is better for setting multiple fields at once and for replacing a field's value. The ActionListopsWidget is better for modifying a field based on the field's existing value and for using a [[Filter Expression]] to derive the value.
+
 ! Extended Filter Operators
 
 A number of [[extended filter operators|The Extended Listops Filters]] are necessary for the manipulation of lists. These operators have been designed primarily for use in subfilter expressions whereby the modified current list is returned in place of the current list.

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

@@ -0,0 +1,50 @@
+caption: action-log
+created: 20201114113318785
+modified: 20201120155202652
+tags: Widgets ActionWidgets [[Debugging Widgets]]
+title: ActionLogWidget
+type: text/vnd.tiddlywiki
+
+! Introduction
+
+<<.from-version "5.1.23">> The ''action-log'' widget is an [[action widget|ActionWidgets]] that can be used to output debugging information to the [[JavaScript console|Web Developer Tools]] supported by most browsers. This can be useful because otherwise it is difficult to observe what is going on within a sequence of actions.
+
+ActionWidgets are used within triggering widgets such as the ButtonWidget.
+
+<<.tip """ For debugging outside of actions see [[LogWidget]]""">>
+
+! Content and Attributes
+
+The ''action-log'' widget is invisible. Any content within it is ignored.
+
+When the actions are invoked, the names and values of all attributes are logged to the JavaScript console.
+In addition there are optional attributes that can be used:
+
+|!Optional Attribute |!Description |
+|$$filter|All variables matching this filter will also be logged. |
+|$$message |A message to display as the title of the information logged. Useful when several `action-log` widgets are used in sequence. |
+|$$all |Set to "yes" to log all variables in a collapsed table. Note that if there is nothing specified to log, all variables are always logged instead.|
+
+
+<<.tip """A handy tip if an action widget is not behaving as expected is to temporarily change it to an `<$action-log>` widget so that the attributes can be observed.""">>
+
+! Example
+
+Here is an example of logging two variables:
+
+```
+<$action-log myVar=<<myVar>> otherVar=<<otherVar>>/>
+```
+
+To log all variables:
+
+```
+<$action-log />
+```
+
+
+To log two variables as well as all core variables (which start with `tv-`):
+
+```
+<$action-log myVar=<<myVar>> other={{!!status}} $$filter="[prefix[tv-]]"/>
+```