This page is part of a static HTML representation of the TiddlyWiki at http://tiddlywiki.com/

ListWidget

23rd February 2015 at 10:37am
Widgets

Introduction

The list widget displays a sequence of tiddlers that match a tiddler filter. 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 are displayed by transcluding each in turn through a template. There are several ways to specify the template and for controlling the behaviour of the list.

Examples

plain list

<$list filter="[tag[ListWidget]sort[title]]"/>

Displays as:

GroupedLists

custom item output

<$list filter="[tag[ListWidget]sort[title]]">
<<currentTiddler>>
{{||$:/core/ui/ViewTemplate/tags}}
</$list>

Displays as:

GroupedLists

ListWidget

custom item template

<$list filter="[tag[ListWidget]sort[title]]" template="$:/core/ui/ViewTemplate/subtitle"/>

Displays as:

21st February 2015 at 11:01pm

Grouped Lists

See GroupedLists for how to generate nested and grouped lists using the ListWidget.

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. As a fallback, the default template just displays the tiddler title.

AttributeDescription
filterThe tiddler filter to display
templateThe title of a template tiddler for transcluding each tiddler in the list. When no template is specified, the body of the ListWidget serves as the item template. With no body, a simple link to the tiddler is returned.
editTemplateAn alternative template to use for DraftTiddlers in edit mode
variableThe name for a variable in which the title of each listed tiddler is stored. Defaults to currentTiddler
emptyMessageMessage to be displayed when the list is empty
storyviewOptional name of module responsible for animating/processing the list
historyThe title of the tiddler containing the navigation history

Edit mode

The <$list> widget can optionally render draft tiddlers through a different template to handle editing, see DraftMechanism.

storyview attribute

The storyview attribute specifies the name of an optional module that can animate changes to the list (including navigation). The core ships with the following storyview 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
  • pop: shrinks items in and out of place

In order for the storyviews to animate correctly each entry in the list should be a single block mode DOM element.

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 HistoryMechanism for details.