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

created: 201308241419
creator: JeremyRuston
modified: 201308300837
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:

* 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.