1
0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-06-16 10:29:54 +00:00

Lots and lots and lots of docs updates

Now we've got up-to-date skeleton documentation for all the widgets
This commit is contained in:
Jeremy Ruston 2013-10-31 22:03:40 +00:00
parent 33de87ec8c
commit fbc1f5e5f6
22 changed files with 513 additions and 31 deletions

View File

@ -1,6 +1,6 @@
created: 201308251542
creator: JeremyRuston
modified: 201308251543
modified: 201310311543
modifier: JeremyRuston
tags: mechanism
title: EncryptionMechanism
@ -11,10 +11,10 @@ For instructions on how to use TiddlyWiki5's encryption features, see [[How to u
The EncryptionMechanism is implemented with the following elements:
* A crypto "password vault" within the BootMechanism that holds the current encryption password
* A PasswordVault within the BootMechanism that holds the current encryption password
* The ability of the BootMechanism to read a block of encrypted tiddlers from the TiddlyWiki file, to prompt the user for a password, and to decrypt the tiddlers
* Handlers for the messages SetPasswordMessage and ClearPasswordMessage that handle the user interface for password changes
* The `<$encrypt>` widget within the main file template that encrypts a filtered list of tiddlers with the currently held password
* The EncryptWidget within the main file template that encrypts a filtered list of tiddlers with the currently held password
* The [[$:/isEncrypted]] tiddler that contains "yes" or "no" according to whether there is a password in the password vault
** The availability of this tiddler allows the RevealWidget to be used to selectively display user interface elements according to whether encryption is in force
* The [[$:/snippets/encryptionstatus]] snippet displays the current encryption status

View File

@ -0,0 +1,14 @@
title: BrowseWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The browse widget displays an HTML file browser button that allows the user to choose one or more files to import. It sends a [[WidgetMessage: tw-import-tiddlers]] carrying a JSON representation of the tiddlers imported from the files up through its parents. This message usually trapped by the NavigatorWidget which adds the tiddlers to the store and updates the story to display them.
! Content and Attributes
The browse widget has no attributes, and ignores any contained content.

View File

@ -0,0 +1,29 @@
title: ButtonWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The button widget displays an HTML `<button>` element that can perform a combination optional actions when clicked:
* Dispatch a user defined [[widget message|WidgetMessages]]
* Trigger a user defined [[popup|PopupMechanism]]
* Assign new text to a specified tiddler
! Content and Attributes
The content of the `<$button>` widget is displayed within the button.
|!Attribute |!Description |
|message |The name of the [[widget message|WidgetMessages]] to send when the button is clicked |
|param |The optional parameter to the message |
|set |The title of a tiddler to which a new value will be assigned |
|setTo |The new value to assign to the tiddler identified in the `set` attribute |
|popup |Title of a state tiddler for a popup that is toggled when the button is clicked |
|qualifyTiddlerTitles |If this attribute is present then the state tiddler titles specified in the `set` and `popup` attributes are qualified as described in HandlingUserInterfaceState |
|class |An optional CSS class name to be assigned to the HTML element |
|style |An optional CSS style attribute to be assigned to the HTML element |
|selectedClass |An optional additional CSS class to be assigned if the popup is triggered or the tiddler specified in `set` already has the value specified in `setTo` |

View File

@ -0,0 +1,18 @@
title: CheckboxWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The checkbox widget displays an HTML `<input type="checkbox">` element that is dynamically bound to the presence or absence of a specified tag on a specified tiddler.
! Content and Attributes
The content of the `<$checkbox>` widget is displayed within an HTML `<label>` element immediately after the checkbox itself. This means that clicking on the content will toggle the checkbox.
|!Attribute |!Description |
|tiddler |Title of the tiddler to manipulate (defaults to the [[TiddlerVariable: currentTiddler]]) |
|tag |The name of the tag to which the checkbox should be bound |

View File

@ -0,0 +1,17 @@
title: CountWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The count widget displays the number of matches to a specified [[filter expression|TiddlerFilters]].
! Content and Attributes
The content of the `<$count>` widget is ignored.
|!Attribute |!Description |
|filter |The filter expression to count |

View File

@ -0,0 +1,28 @@
title: DropzoneWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The dropzone widget creates an area into which the user can drag files and other objects. It also supports pasting via the clipboard, although browser support is currently limited.
It sends a [[WidgetMessage: tw-import-tiddlers]] carrying a JSON representation of the tiddlers to be imported up through its parents. This message usually trapped by the NavigatorWidget which adds the tiddlers to the store and updates the story to display them.
! Content and Attributes
The dropzone widget has no attributes, and displays any contained content within the dropzone.
! Display
The dropzone widget creates an HTML `<div class="tw-dropzone">` to contain its content. During a drag operation the class `tw-dragover` is added. CSS is used to provide user feedback.
! Data types supported
The following data transfer types are supported:
* ''text/vnd.tiddler'' - a list of tiddlers in JSON format (this format is generated by the LinkWidget)
* ''text/plain'' - plain text
* ''text/uri-list'' - a list of URIs as a single tiddler

View File

@ -0,0 +1,17 @@
title: EditBitmapWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The edit bitmap widget provides a user interface in the browser for editing bitmap tiddlers. It is currently a primitive proof-of-concept, supporting resizing and painting with a single color and line width.
! Content and Attributes
The content of the `<$edit-bitmap>` widget is ignored.
|!Attribute |!Description |
|tiddler |The tiddler to edit (defaults to the [[TiddlerVariable: currentTiddler]]) |

View File

@ -0,0 +1,28 @@
title: EditTextWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The edit text widget provides a user interface in the browser for editing text tiddler fields. The editing element is dynamically bound to the underlying tiddler value: changes to the tiddler are instantly reflected, and any edits are instantly propogated.
By default, the edit text widget generates a `<textarea>` as the HTML editing element when the `text` field is edited, and a `<input type="text">` element otherwise. This behaviour can be overridden with the `tag` and `type` attributes.
! Content and Attributes
The content of the `<$edit-text>` widget is ignored.
|!Attribute |!Description |
|tiddler |The tiddler to edit (defaults to the [[TiddlerVariable: currentTiddler]]) |
|field |The field to edit (defaults to `text`). Takes precedence over the `index` attribute |
|index |The index to edit |
|default |The default text to be provided when the target tiddler doesn't exist |
|class |A CSS class to be assigned to the generated HTML editing element |
|placeholder |Placeholder text to be displayed when the edit field is empty |
|focusPopup |Title of a state tiddler for a popup that is displayed when the editing element has focus |
|qualifyTiddlerTitles |If this attribute is present then the state tiddler title specified in the `focusPopup` attributes are qualified as described in HandlingUserInterfaceState |
|tag |Overrides the generated HTML editing element tag |
|type |Overrides the generated HTML editing element `type` attribute |

View File

@ -0,0 +1,20 @@
title: EditWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The edit widget provides a general purpose interface for editing a tiddler. It dynamically chooses the appropriate widget depending on the type of the tiddler (currently either the EditTextWidget or the EditBitmapWidget).
! Content and Attributes
The content of the `<$edit>` widget is ignored.
|!Attribute |!Description |
|tiddler |The tiddler to edit (defaults to the [[TiddlerVariable: currentTiddler]]) |
|field |The field to edit (defaults to `text`). Takes precedence over the `index` attribute |
|index |The index to edit |
|class |A CSS class to be added the generated editing widget |

View File

@ -0,0 +1,17 @@
title: EncryptWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The encrypt widget renders a filtered list of tiddlers to an encrypted block with the password currently held in the PasswordVault. The encrypted block can subsequently be decrypted by the TiddlyWiki5 BootMechanism. See the EncryptionMechanism for more details.
! Content and Attributes
The content of the `<$encrypt>` widget is ignored.
|!Attribute |!Description |
|filter |Filter defining the tiddlers to be included in the encrypted block. If not specified then all non-system tiddlers are used |

View File

@ -0,0 +1,23 @@
title: FieldManglerWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The field manager widget manipulates the fields and tags of a tiddler. It does so in response to the following WidgetMessages:
|!Message |!Description
|''tw-remove-field'' |Remove the field specified in `event.param` |
|''tw-add-field'' |Add the field specified in `event.param` |
|''tw-remove-tag'' |Remove the tag specified in `event.param` |
|''tw-add-tag'' |Add the tag specified in `event.param` |
! Content and Attributes
The field mangler widget displays any contained content, and responds to WidgetMessages dispatched within it.
|!Attribute |!Description |
|tiddler |Title of the tiddler to manipulate (defaults to the [[TiddlerVariable: currentTiddler]]) |

View File

@ -0,0 +1,31 @@
title: FieldsWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The fields widget renders each field of a specified tiddler through a simple text template. A list of fields to exclude can be provided. It is used internally by TiddlyWiki5, notably by the FileSavingMechanism.
!! Template Handling
The provided template is rendered with the following special substitutions:
|!Symbol |!Substitution |
|$name$ |Field name |
|$value$ |Field value |
|$encoded_value$ |HTML encoded form of field value |
! Content and Attributes
The content of the `<$fields>` widget is ignored.
|!Attribute |!Description |
|tiddler |Title of the tiddler from which the fields are to be displayed (defaults to the [[TiddlerVariable: currentTiddler]]) |
|template |Text of the template (see above) |
|exclude |Lists of fields to be excluded (defaults to "text") |
|stripTitlePrefix |If set to "yes" then curly bracketed prefixes are removed from titles (for example `{prefix}HelloThere` converts to `HelloThere`) |
The `stripTitlePrefix` attribute is used when building TiddlyWiki Classic; see `editions/tw2` in the TiddlyWiki5 repo.

View File

@ -0,0 +1,24 @@
title: LinkCatcherWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The link catcher widget responds to navigation WidgetMessages dispatched within its child content by performing any or all of these actions:
* sending a different widget message
* setting a tiddler to the title of the navigated tiddler
* setting a tiddler to a specified value
! Content and Attributes
The content of the `<$linkcatcher>` widget is displayed normally.
|!Attribute |!Description |
|to |Optional title of the tiddler to be set to the title of the navigated tiddler |
|message |Optional identifier for a [[widget message|WidgetMessages]] to be sent when a navigation is caught |
|set |Optional title of the tiddler to be set to a specified value when navigation occurs |
|setTo |Value to be assigned by the `set` attribute |

View File

@ -6,7 +6,7 @@ The `link` widget generates links to tiddlers.
! Content and Attributes
|!Attribute |!Description |
|to |The title of the target tiddler for the link (defaults to the currentTiddler variable if not specified) |
|to |The title of the target tiddler for the link (defaults to the [[TiddlerVariable: currentTiddler]]) |
The content of the link widget is rendered within the `<a>` tag.

View File

@ -1,13 +1,10 @@
created: 201308241419
created: 201310241419
creator: JeremyRuston
modified: 201308300837
modified: 201310300837
modifier: JeremyRuston
tags: widget
title: ListWidget
\define demoMacro(title)
This is the tiddler called [[Blah-$title$]]
\end
! Introduction
The list widget displays a sequence of tiddlers that match a [[tiddler filter|TiddlerFilters]]. It can be used for many purposes:
@ -17,27 +14,29 @@ The list widget displays a sequence of tiddlers that match a [[tiddler filter|Ti
* Listing each of the tags applied to a tiddler
* Handling the main story river
The tiddlers can either be displayed by transcluding each in turn through an optional template, or by providing a macro to be rendered for each list element.
The tiddlers can either be displayed by transcluding each in turn through an optional template.
! Content and Attributes
The content of the `<$list>` widget is the optional template to use for rendering each tiddler in the list (alternatively, the template can be specified as a tiddler title in the ``template`` attribute).
The content of the `<$list>` widget is an optional template to use for rendering each tiddler in the list (alternatively, the template can be specified as a tiddler title in the ``template`` attribute).
|!Attribute |!Description |
|type |Determines the HTML elements generated for the list: ''plain'', ''ul'' or ''ol'' |
|filter |The TiddlerFilter to display |
|template |The title of a template tiddler for rendering each tiddler in the list |
|editTemplate |An alternative template to use for DraftTiddlers in edit mode |
|emptyMessage |Message to be displayed when the list is empty |
|class |Class to be applied to the list frame element|
|itemClass |Class to be applied to the list member elements |
|macro |Specifies an optional macro to use for rendering each tiddler |
|listview |Optional name of module responsible for animating/processing the list |
|history |The title of the tiddler containing the navigation history |
|hackTemplate |If this attribute is present then the list items are directly transcluded without altering the current tiddler or using a template |
|hackCurrentTiddler |If this attribute is present then the template is directly transcluded without altering the current tiddler |
//`listview` and `history` are temporarily unimplemented //
//`hackTemplate` and `hackCurrentTiddler` are temporary hacks that will be removed//
!! Handling edit mode
The `<$list>` widget can optionally render draft tiddlers through a different tiddler than ordinary tiddlers -- see DraftMechanism for a discussion of how this capability is used.
The `<$list>` widget can optionally render draft tiddlers through a different template tiddler than ordinary tiddlers -- see DraftMechanism for a discussion of how this capability is used.
!! `listview` attribute
@ -52,18 +51,6 @@ The optional `history` attribute specifies the name of a tiddler that is used to
! Examples
!! Using the `macro` attribute
Example of using the `<$list>` widget with the macro attribute:
```
<$list filter="[tag[introduction]]" macro="demoMacro"/>
```
Renders as:
<$list filter="[tag[introduction]]" macro="demoMacro"/>
!! Creating nested lists
The ''types'' and ''recent'' tabs in the sidebar give two examples of a grouped list created by nesting.
@ -72,11 +59,16 @@ The ''types'' listing is performed with this markup:
```
<$list filter="[!is[system]has[type]each[type]sort[type]]">
<$view field="type" default="untyped"/>
<div class="tw-menu-list-item">
<$view field="type"/>
<$list filter="[type{!!type}!is[system]sort[title]]">
<$view field="title" format="link"/>
<div class="tw-menu-list-subitem">
<$link to={{!!title}}><$view field="title"/></$link>
</div>
</$list>
</div>
</$list>
```
The outer list filter selects each discrete value found in the `type` field. The inner list filter selects all the (non-system) tiddlers with that type.
@ -85,10 +77,14 @@ The ''recent'' listing is performed with this markup:
```
<$list filter="[!is[system]has[modified]!sort[modified]limit[100]eachday[modified]]" itemClass="tw-menu-list-item">
<div class="tw-menu-list-item">
<$view field="modified" format="date" template="DDth MMM YYYY"/>
<$list filter="[sameday{!!modified}!is[system]!sort[modified]]" itemClass="tw-menu-list-subitem">
<$view field="title" format="link"/>
<div class="tw-menu-list-subitem">
<$link to={{!!title}}><$view field="title"/></$link>
</div>
</$list>
</div>
</$list>
```

View File

@ -0,0 +1,26 @@
title: MacroCallWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The macro call widget provides an alternative syntax for invoking macros. The advantage of the widget form is that it allows macro parameters to be specified as widget attributes, thus allowing indirection and macro values to be set.
For example, a macro called `italicise` that takes a single parameter called `text` can be invoked in any of these ways:
```
<<italicise "Text to be made into italics">>
<<italicise text:"Text to be made into italics">>
<$macrocall $name="italicise" text="Text to be made into italics"/>
```
! Content and Attributes
The content of the `<$macrocall>` widget is ignored.
|!Attribute |!Description |
|$name |Name of the macro to invoke |
|//parameters// |Macro parameters specified as attributes |

View File

@ -0,0 +1,86 @@
title: NavigatorWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! 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.
|!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 |

View File

@ -0,0 +1,17 @@
title: PasswordWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The password widget displays a password input box that is bound to a named entry in the TiddlyWiki5 PasswordVault. Passwords are currently stored in the browsers local storage and are not themselves encrypted.
! Content and Attributes
The content of the `<$password>` widget is ignored.
|!Attribute |!Description |
|name |Name of the password vault entry |

View File

@ -0,0 +1,26 @@
title: RevealWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The reveal widget hides or shows its content depending upon the value of a [[state tiddler|StateTiddlers]]. The type of the widget determines the condition for the content being displayed:
* ''match'': the content is displayed if the state tiddler matches a specified value
* ''nomatch'': the content is displayed if the state tiddler doesn't match a specified value
* ''popup'': the content is displayed as a popup as described in the PopupMechanism
! Content and Attributes
The content of the `<$reveal>` widget is displayed according to the rules given above.
|!Attribute |!Description |
|state |The title of the tiddler containing the state |
|type |The type of matching performed: ''match'', ''nomatch'' or ''popup'' |
|text |The text to match when the type is ''match'' and ''nomatch'' |
|position |The position used for the popup when the type is ''popup''. Can be ''left'',''above'',''aboveright'',''right'',''belowleft'' or ''below'' |
|default |Default value to use when the state tiddler |
|qualifyTiddlerTitles |If this attribute is present then the state tiddler title is qualified as described in HandlingUserInterfaceState |

View File

@ -0,0 +1,18 @@
title: SetVariableWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The set variable widget assigns a value to a specified [[variable|TiddlerVariables]]. The new value of the variable is availale to the content within the set variable widget.
! Content and Attributes
The content of the `<$setvariable>` widget is the scope for the value assigned to the variable.
|!Attribute |!Description |
|name |The name of the variable to assign |
|value |The value to assign to the variable |

View File

@ -0,0 +1,14 @@
title: VersionWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The version widget displays the current TiddlyWiki core version number.
! Content and Attributes
The content of the `<$version>` widget is ignored, and it doesn't take any attributes

View File

@ -0,0 +1,33 @@
title: ViewWidget
created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
! Introduction
The view widget displays the contents of a tiddler field in a specified format.
! Content and Attributes
The content of the `<$view>` widget is ignored.
|!Attribute |!Description |
|tiddler |The title of the tiddler (defaults to the [[TiddlerVariable: currentTiddler]]) |
|field |The name of the field to view (defaults to "text") |
|format |The format for displaying the field (see below) |
|template |The optional template used with certain formats |
!! Formats
The following formats can be specified in the `format` attribute:
|!Format |!Description |
|''text'' |Plain text |
|''htmlwikified'' |The field is wikified and the resulting HTML returned as plain text |
|''htmlencoded'' |The field is displayed with HTML encoding issues |
|''date'' |The field is interpreted as a UTC date and displayed according to the DateFormat specified in the `template` attribute |
|''relativedate'' |The field is interpreted as a UTC date and displayed as the interval from the present instant |
|''stripcomments'' |The field is interpreted as JavaScript source code and any lines beginning `\\#` are stripped |
|''jsencoded'' |The field is displayed as a JavaScript encoded string |