Better documentation for widget messages

editions/tw5.com/tiddlers/Release 5.0.8beta.tid

@@ -1,5 +1,5 @@
 created: 20140127143652456
-modified: 20140223191618338
+modified: 20140226195203603
 tags: releasenote
 title: Release 5.0.8-beta
 type: text/vnd.tiddlywiki
@@ -17,6 +17,7 @@ See [[Notes for upgrading to 5.0.8-beta]] for more details of these changes:
 !! Documentation Improvements
 
 * Improved documentation for TiddlerFilters, including a notation of the [[TiddlerFilter Formal Grammar]] contributed by [[@Tikkoneus|https://github.com/Tikkoneus]]
+* Improved documentation for WidgetMessages
 
 !! Usability Improvements
 

editions/tw5.com/tiddlers/concepts/WidgetMessages.tid

@@ -0,0 +1,20 @@
+created: 20140226083311937
+modified: 20140226090209479
+tags: concepts
+title: WidgetMessages
+type: text/vnd.tiddlywiki
+
+Widget messages are generated by widgets in response to user actions. They flow up the widget tree until they are handled by an ancestor widget.
+
+The following widget messages are implemented by the core:
+
+<ul>
+<$list filter="[tag[message]]">
+<li>
+<$link to={{!!title}}>
+<$view field="title"/>
+</$link>
+</li>
+</$list>
+</ul>
+

editions/tw5.com/tiddlers/dev/TiddlyWiki for Developers.tid

@@ -1,5 +1,5 @@
 created: 20131203074550710
-modified: 20131212093713249
+modified: 20140226083600000
 tags: introduction dev
 title: TiddlyWiki for Developers
 type: text/vnd.tiddlywiki
@@ -14,7 +14,7 @@ If you're interested in understanding more about the internal operation of Tiddl
 
 TiddlyWiki's architecture is very different from an HTML page written using jQuery. This section concisely explains what TiddlyWiki does differently. It may not make much sense on the first reading.
 
-The key to understanding how it works internally is to see that the RefreshMechanism requires that any region of the DOM can be regenerated at any time. This means that the entire state of the user interface must reside in the tiddler store, and not in the DOM.
+The key to understanding how it works internally is to see that the RefreshMechanism requires that any region of the DOM can be regenerated at any time. This means that the entire state of the user interface must reside in the tiddler store, from where it is synchronised into the DOM. This is done to improve performance by minimising the DOM interactions during the refresh cycles.
 
 It also determines the standard UI flow:
 

editions/tw5.com/tiddlers/messages/WidgetMessage_ tw-cancel-tiddler.tid

@@ -0,0 +1,13 @@
+created: 20140226193622350
+modified: 20140226193906089
+tags: message navigator-message
+title: WidgetMessage: tw-cancel-tiddler
+type: text/vnd.tiddlywiki
+
+The `tw-cancel-tiddler` message abandons the changes in a draft tiddler. It requires the following properties on the `event` object:
+
+|!Name |!Description |
+|param |Title of the tiddler that is being cancelled out of edit mode |
+|tiddlerTitle |Fallback title that is used if ''param'' isn't specified (automatically set by the ButtonWidget)  |
+
+The cancel tiddler message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.

editions/tw5.com/tiddlers/messages/WidgetMessage_ tw-clear-password.tid

@@ -0,0 +1,9 @@
+created: 20140226084018038
+modified: 20140226084916556
+tags: message
+title: WidgetMessage: tw-clear-password
+type: text/vnd.tiddlywiki
+
+The `tw-clear-password` message clears the current password from the password vault, clearing the [[$:/isEncrypted]] tiddler. See EncryptionMechanism for details.
+
+This message is typically generated with the ButtonWidget, and is handled by the core itself.

editions/tw5.com/tiddlers/messages/WidgetMessage_ tw-close-all-tiddlers.tid

@@ -0,0 +1,9 @@
+created: 20140226194242809
+modified: 20140226194341303
+tags: message navigator-message
+title: WidgetMessage: tw-close-all-tiddlers
+type: text/vnd.tiddlywiki
+
+The close all tiddlers message empties the story list.
+
+The close all tiddlers message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.

editions/tw5.com/tiddlers/messages/WidgetMessage_ tw-close-tiddler.tid

@@ -0,0 +1,13 @@
+created: 20140226193940778
+modified: 20140226194227227
+tags: message navigator-message
+title: WidgetMessage: tw-close-tiddler
+type: text/vnd.tiddlywiki
+
+The `tw-close-tiddler` message removes a specified tiddler from the story list. It requires the following properties on the `event` object:
+
+|!Name |!Description |
+|param |Title of the tiddler that is to be closed |
+|tiddlerTitle |Fallback title that is used if ''param'' isn't specified (automatically set by the ButtonWidget)  |
+
+The close tiddler message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.

editions/tw5.com/tiddlers/messages/WidgetMessage_ tw-delete-tiddler.tid

@@ -0,0 +1,13 @@
+created: 20140226090324129
+modified: 20140226090441236
+tags: message navigator-message
+title: WidgetMessage: tw-delete-tiddler
+type: text/vnd.tiddlywiki
+
+The `tw-delete-tiddler` message deletes the specified tiddler and removes it from the current story. If the tiddler is a draft then it also deletes the tiddler specified in the `draft.of` field. The delete tiddler message requires the following properties on the `event` object:
+
+|!Name |!Description |
+|param |Title of the tiddler that is to be deleted |
+|tiddlerTitle |Fallback title that is used if ''param'' isn't specified (automatically set by the ButtonWidget)  |
+
+The delete tiddler message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.

editions/tw5.com/tiddlers/messages/WidgetMessage_ tw-edit-tiddler.tid

@@ -0,0 +1,13 @@
+created: 20140226085529797
+modified: 20140226090641987
+tags: message navigator-message
+title: WidgetMessage: tw-edit-tiddler
+type: text/vnd.tiddlywiki
+
+The `tw-edit-tiddler` message replaces the specified tiddler in the current story with a draft version of itself. It requires the following properties on the `event` object:
+
+|!Name |!Description |
+|param |Title of the tiddler that is being switched to edit mode |
+|tiddlerTitle |Fallback title that is used if ''param'' isn't specified (automatically set by the ButtonWidget)  |
+
+The edit tiddler message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.

editions/tw5.com/tiddlers/messages/WidgetMessage_ tw-import-tiddlers.tid

@@ -0,0 +1,14 @@
+created: 20140226084658099
+modified: 20140226195055502
+tags: message navigator-message
+title: WidgetMessage: tw-import-tiddlers
+type: text/vnd.tiddlywiki
+
+The `tw-import-tiddlers` message inserts a list of tiddlers into the store. If multiple tiddlers are imported then a report is displayed; if only one tiddler is imported then it is displayed instead. The import message requires the following properties on the `event` object:
+
+|!Name |!Description |
+|param |JSON text of the array of tiddlers to be imported |
+
+This message is handled by the NavigatorWidget.
+
+The import tiddlers message is usually generated with the DropzoneWidget or the BrowseWidget, and is handled by the NavigatorWidget.

editions/tw5.com/tiddlers/messages/WidgetMessage_ tw-navigate.tid

@@ -0,0 +1,17 @@
+created: 20140226085215941
+modified: 20140226085454346
+tags: message
+title: WidgetMessage: tw-navigate
+type: text/vnd.tiddlywiki
+
+The `tw-navigate` message inserts the specified tiddler into the story and puts it at the top of the history stack. If the tiddler is not already present in the story then it will be positioned immediately after the tiddler specified in `event.navigateFromTitle`.
+
+The navigate message requires the following properties on the `event` object:
+
+|!Name |!Description |
+|navigateTo |Title of the tiddler that is being navigated |
+|navigateFromTitle |Title of the tiddler from which the navigation was initiated |
+|navigateFromClientRect |Bounding rectangle in client page coordinates of the element initiating the navigation |
+|navigateSuppressNavigation |''true'' causes the new tiddler to only be added to the story, and not the history stack. This suppresses the scrolling associated with navigating to a tiddler |
+
+The navigate message can be generated by the LinkWidget and the ButtonWidget, and is handled by the NavigatorWidget.

editions/tw5.com/tiddlers/messages/WidgetMessage_ tw-new-tiddler.tid

@@ -0,0 +1,13 @@
+created: 20140226194405353
+modified: 20140226194729158
+tags: message navigator-message
+title: WidgetMessage: tw-new-tiddler
+type: text/vnd.tiddlywiki
+
+The new tiddler message creates a new draft tiddler and adds it to the current story. It requires the following properties on the `event` object:
+
+|!Name |!Description |
+|param |Optional title of a tiddler to use as a template for the new tiddler |
+|navigateFromTitle |Title of the tiddler from which the navigation to the new tiddler was initiated |
+
+The new tiddler message is usually generated with the LinkWidget or the ButtonWidget and is handled by the NavigatorWidget.

editions/tw5.com/tiddlers/messages/WidgetMessage_ tw-save-tiddler.tid

@@ -0,0 +1,13 @@
+created: 20140226090544323
+modified: 20140226090729828
+tags: message navigator-message
+title: WidgetMessage: tw-save-tiddler
+type: text/vnd.tiddlywiki
+
+The `tw-save-tiddler` message is applied to draft tiddlers. It saves the draft over the tiddler identified in the `draft.of` field and then deletes the draft. The save tiddler message requires the following properties on the `event` object:
+
+|!Name |!Description |
+|param |Title of the tiddler that is being switched out of edit mode |
+|tiddlerTitle |Fallback title that is used if ''param'' isn't specified (automatically set by the ButtonWidget)  |
+
+The save tiddler message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.

editions/tw5.com/tiddlers/messages/WidgetMessage_ tw-set-password.tid

@@ -0,0 +1,9 @@
+created: 20140226084623977
+modified: 20140226085200323
+tags: message
+title: WidgetMessage: tw-set-password
+type: text/vnd.tiddlywiki
+
+The `tw-set-password` message prompts the user for a new password and stores it in the password vault, replacing any existing password. It also sets the [[$:/isEncrypted]] tiddler. See EncryptionMechanism for details.
+
+This message is typically generated with the ButtonWidget, and is handled by the core itself.

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

@@ -1,80 +1,13 @@
-title: NavigatorWidget
+created: 20131024141900000
-created: 201310241419
+modified: 20140226194810214
-modified: 201310300837
 tags: widget
+title: NavigatorWidget
+type: text/vnd.tiddlywiki
 
 ! Introduction
 
 The navigator widget manipulates the current store, the story list and history lists in response to various WidgetMessages.
 
-! Navigator Widget Messages
-
-The actions performed by each widget message are described below.
-
-!! Action of `tw-navigate` message
-
-The navigate message inserts the specified tiddler into the story and puts it at the top of the history stack. If the tiddler is not already present in the story then it will be positioned immediately after the tiddler specified in `event.navigateFromTitle`.
-
-The navigate message requires the following properties on the `event` object:
-
-|!Name |!Description |
-|navigateTo |Title of the tiddler that is being navigated |
-|navigateFromTitle |Title of the tiddler from which the navigation was initiated |
-|navigateFromClientRect |Bounding rectangle in client page coordinates of the element initiating the navigation |
-
-!! Action of `tw-edit-tiddler` message
-
-The edit tiddler message replaces the specified tiddler in the current story with a draft version of itself. It requires the following properties on the `event` object:
-
-|!Name |!Description |
-|tiddlerTitle |Title of the tiddler that is being switched to edit mode |
-
-!! Action of `tw-delete-tiddler` message
-
-The delete tiddler message deletes specified tiddler and removes it from the current story. If the tiddler is a draft then it also deletes the tiddler specified in the `draft.of` field. The delete tiddler message requires the following properties on the `event` object:
-
-|!Name |!Description |
-|tiddlerTitle |Title of the tiddler that is being switched to edit mode |
-
-!! Action of `tw-save-tiddler` message
-
-The save tiddler message is applied to draft tiddlers. It saves the draft over the tiddler identified in the `draft.of` field and then deletes the draft. The save tiddler message requires the following properties on the `event` object:
-
-|!Name |!Description |
-|tiddlerTitle |Title of the tiddler that is being switched out of edit mode |
-
-!! Action of `tw-cancel-tiddler` message
-
-The cancel tiddler message abandons the changes in a draft tiddler. It requires the following properties on the `event` object:
-
-|!Name |!Description |
-|tiddlerTitle |Title of the tiddler that is being cancelled out of edit mode |
-
-!! Action of `tw-close-tiddler` message
-
-The close tiddler message removes a specified tiddler from the story list. It requires the following properties on the `event` object:
-
-|!Name |!Description |
-|tiddlerTitle |Title of the tiddler that is to be closed |
-
-!! Action of `tw-close-all-tiddlers` message
-
-The close all tiddlers message empties the story list.
-
-!! Action of `tw-new-tiddler` message
-
-The new tiddler message creates a new draft tiddler and adds it to the current story. It requires the following properties on the `event` object:
-
-|!Name |!Description |
-|navigateFromTitle |Title of the tiddler from which the navigation to the new tiddler was initiated |
-
-!! Action of `tw-import-tiddlers` message
-
-The import tiddlers message adds a list of tiddlers to the store and adds them to the current story. It requires the following properties on the `event` object:
-
-|!Name |!Description |
-|param |JSON text of the tiddlers to be imported |
-
 ! Content and Attributes
 
 The navigator widget displays any contained content, and responds to WidgetMessages dispatched within it.
@@ -82,3 +15,17 @@ The navigator widget displays any contained content, and responds to WidgetMessa
 |!Attribute |!Description |
 |story |Name of the tiddler containing the story list to be manipulated |
 |history |Name of the tiddler containing the history list to be manipulated |
+
+! Widget Messages
+
+The following WidgetMessages are handled by the navigator widget:
+
+<ul>
+<$list filter="[tag[navigator-message]]">
+<li>
+<$link to={{!!title}}>
+<$view field="title"/>
+</$link>
+</li>
+</$list>
+</ul>