mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-11-25 19:17:19 +00:00
144 lines
5.7 KiB
Plaintext
144 lines
5.7 KiB
Plaintext
caption: list
|
||
created: 20131024141900000
|
||
modified: 20210416175333981
|
||
tags: Widgets Lists
|
||
title: ListWidget
|
||
type: text/vnd.tiddlywiki
|
||
|
||
! Introduction
|
||
|
||
The list widget displays a sequence of tiddlers that match a [[tiddler filter|Filters]]. 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:
|
||
|
||
<<<
|
||
<$list filter="[tag[ListWidget]sort[title]]"/>
|
||
|
||
<<<
|
||
|
||
''custom item output''
|
||
|
||
```
|
||
<$list filter="[tag[ListWidget]sort[title]]">
|
||
<<currentTiddler>>
|
||
{{||$:/core/ui/ViewTemplate/tags}}
|
||
</$list>
|
||
```
|
||
|
||
Displays as:
|
||
|
||
<<<
|
||
<$list filter="[tag[ListWidget]sort[title]]">
|
||
<<currentTiddler>>
|
||
{{||$:/core/ui/ViewTemplate/tags}}
|
||
</$list>
|
||
<<<
|
||
|
||
''custom item template''
|
||
|
||
```
|
||
<$list filter="[tag[ListWidget]sort[title]]" template="$:/core/ui/ViewTemplate/subtitle"/>
|
||
```
|
||
|
||
Displays as:
|
||
|
||
<<<
|
||
<$list filter="[tag[ListWidget]sort[title]]" template="$:/core/ui/ViewTemplate/subtitle"/>
|
||
|
||
<<<
|
||
|
||
!! 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.
|
||
|
||
The action of the list widget depends on the results of the filter combined with several options for specifying the template:
|
||
|
||
* If the filter evaluates to an empty list, the text of the ''emptyMessage'' attribute is rendered, and all other templates are ignored
|
||
* Otherwise, if the ''template'' attribute is specified then it is taken as the title of a tiddler to use as a template for rendering each item of the list
|
||
* Otherwise, if the list widget content is not blank, it is used as a template for rendering each item of the list
|
||
* Otherwise, a default template is used consisting of a `<span>` or `<div>` element wrapped around a link to the item
|
||
|
||
|!Attribute |!Description |
|
||
|filter |The [[tiddler filter|Filters]] to display |
|
||
|template |The 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. |
|
||
|editTemplate |An alternative template to use for [[DraftTiddlers|DraftMechanism]] in edit mode |
|
||
|variable |The name for a [[variable|Variables]] in which the title of each listed tiddler is stored. Defaults to ''currentTiddler'' |
|
||
|counter |<<.from-version "5.2.0">> Optional name for a [[variable|Variables]] in which the 1-based numeric index of each listed tiddler is stored (see below) |
|
||
|emptyMessage |Message to be displayed when the list is empty |
|
||
|storyview |Optional name of module responsible for animating/processing the list |
|
||
|history |The title of the tiddler containing the navigation history |
|
||
|
||
!! `counter` attribute
|
||
|
||
The optional `counter` attribute specifies the name of a variable to hold the 1-based numeric index of the current item in the list.
|
||
|
||
Two additional variables are also set to indicate the first and last items in the list:
|
||
|
||
* `<counter-variable-name>-first` is set to `yes` for the first entry in the list, `no` for the others
|
||
* `<counter-variable-name>-last` is set to `yes` for the last entry in the list, `no` for the others
|
||
|
||
For example:
|
||
|
||
|
||
```
|
||
<$list filter="[tag[About]sort[title]]" counter="counter">
|
||
<div>
|
||
<<counter>>: ''<$text text=<<currentTiddler>>/>'' (is first: <<counter-first>>, is last: <<counter-last>>)
|
||
</div>
|
||
</$list>
|
||
```
|
||
|
||
Displays as:
|
||
|
||
<<<
|
||
<$list filter="[tag[About]sort[title]]" counter="counter">
|
||
<div>
|
||
<<counter>>: ''<$text text=<<currentTiddler>>/>'' (is first: <<counter-first>>, is last: <<counter-last>>)
|
||
</div>
|
||
</$list>
|
||
<<<
|
||
|
||
Note that using the `counter` attribute can degrade the performance of the list widget in certain circumstances. In particular, it prevents an optimisation that normally occurs when dynamically adding or removing entries.
|
||
|
||
!! 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.
|
||
|
||
!! Additional Notes and Edge Cases
|
||
|
||
* If the `filter` attribute is not present then a default of `[!is[system]sort[title]]` is used
|
||
* If the list widget is completely empty (ie only whitespace between the opening and closing tags), then it behaves as if the content were a `DIV` or a `SPAN` containing a link to the current tiddler (it’s a `DIV` if the list widget is in block mode, or a SPAN if it is in inline mode)
|
||
* If the `template` attribute is not present then the content of the list widget will be used as the template, unless the widget is completely empty in which case a default template is used |