created: 201310241419
creator: JeremyRuston
modified: 201310300837
modifier: JeremyRuston
tags: widget
title: ListWidget

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

! Content and Attributes

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 |
|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 |
|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 template 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

!! 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]]">
<div class="tw-menu-list-item">
<$view field="type"/>
<$list filter="[type{!!type}!is[system]sort[title]]">
<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.

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">
<div class="tw-menu-list-subitem">
<$link to={{!!title}}><$view field="title"/></$link>
</div>
</$list>
</div>
</$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.