mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-12-28 02:50:27 +00:00
be06257430
Belatedly realised that the design would be clearer without these two separate concepts being conflated into a single widget. As a result of this change, any other widget or template that generates transclude widgets has needed adjustment.
97 lines
3.9 KiB
Plaintext
97 lines
3.9 KiB
Plaintext
created: 201308241419
|
|
creator: JeremyRuston
|
|
modified: 201308241419
|
|
modifier: JeremyRuston
|
|
tags: widget docs
|
|
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 TiddlerFilter. It can be used for many purposes:
|
|
|
|
* Displaying custom lists of links, like in TiddlyWiki5's sidebar
|
|
* Custom lists, such as "all tiddlers tagged 'task' that are not tagged 'done'"
|
|
* 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.
|
|
|
|
! 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).
|
|
|
|
|!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 |
|
|
|
|
!! 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.
|
|
|
|
!! `listview` attribute
|
|
|
|
The `listview` attribute gives the specifies the name of an optional module that can animate changes to the list (including navigation). The core ships with the following listview modules:
|
|
|
|
* `classic`: renders the list as an ordered sequence of tiddlers
|
|
* `zoomin`: just renders the current tiddler from the list, with a zoom animation for navigating between tiddlers
|
|
|
|
!! Handling history and navigation
|
|
|
|
The optional `history` attribute specifies the name of a tiddler that is used to track the current tiddler for navigation purposes. When the history tiddler changes the list view responds by telling the listview to handle navigating to the new tiddler. See the NavigationMechanism for more details.
|
|
|
|
! 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.
|
|
|
|
The ''types'' listing is performed with this markup:
|
|
|
|
```
|
|
<$list filter="[!is[system]has[type]each[type]sort[type]]">
|
|
<$view field="type" default="untyped"/>
|
|
<$list filter="[type{!!type}!is[system]sort[title]]">
|
|
<$view field="title" format="link"/>
|
|
</$list>
|
|
</$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.
|
|
|
|
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">
|
|
<$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"/>
|
|
</$list>
|
|
</$list>
|
|
```
|
|
|
|
Here the outer list filter selects each discrete day found in the `modified` field, while the inner list filter selects all the tiddlers dated the same day in the `modified` field.
|
|
|