mirrors/TiddlyWiki5
1
0
Fork 0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-06-16 10:29:54 +00:00
Code Issues Releases Wiki Activity

Merge pull request #1332 from tobibeer/list-widget-iterator

Browse Source 
documentation for list iterators
This commit is contained in:
Jeremy Ruston 2015-01-11 19:59:28 +00:00
commit 17f2e5e7e6
4 changed files with 182 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
editions/tw5.com/tiddlers/demonstrations/GroupedLists.tid Normal file
View File

@ -0,0 +1,18 @@
title: GroupedLists
tags: ListWidget
created: 20150106180000000
modified: 20150106180000000
The following sidebar tabs give examples of grouped lists created by nesting.
!! Types Tab
For the [[Types|$:/core/ui/MoreSideBar/Types]] tab, the outer list filter as shown below selects each discrete value found in the `type` field. The inner list filter selects all the (non-system) tiddlers with that type.
<<tw-code "$:/core/ui/MoreSideBar/Types">>
!! Recent Tab
The list in the [[Recent|$:/core/ui/SideBar/Recent]] tab is generated using the TimelineMacro. 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.
<<tw-code-link "$:/core/macros/timeline">>

10
editions/tw5.com/tiddlers/system/wikitext-macros.tid
View File

@ -28,3 +28,13 @@ Renders as:
$src$
\end
\define tw-code(tiddler)
<$codeblock language={{$tiddler$!!type}} code={{$tiddler$}}/>
\end
\define tw-code-link(tiddler)
[[$tiddler$]]:
<<tw-code $tiddler$>>
\end

91
editions/tw5.com/tiddlers/variables/IteratorVariables Normal file
View File

@ -0,0 +1,91 @@
title: IteratorVariables
tags: ListWidget Variables
created: 20150106180000000
modified: 20150106180000000
The ListWidget exposes the following iterator variables during list processing:
; `<<iterator>>`
: set to the current index, e.g. `1`
; `<<iterator-even>>`
: set to `true` for an even index, otherwise `false`
; `<<iterator-last>>`
: set to `true` for last index, otherwise `false`
The ListWidget allows to declare an `iterator` attribute through which you can declare a custom iterator variable prefix:
```
<$list filter="[tag[foo]]" iterator="my-foo">
...
</$list>
```
!!Using Iterator Variables
You can use iterator variables with the RevealWidget to conditionally render output depending on the current index...
''only show for item at index 1, i.e. the first item''
```
<$reveal type=match default=1 text=<<my-foo>>>
...
</$reveal>
```
''show for all except first index''
```
<$reveal type=nomatch default=1 text=<<my-foo>>>
...
</$reveal>
```
''only show at even indexes''
```
<$reveal type=match default=true text=<<my-foo-even>>>
...
</$reveal>
```
''only show at uneven indexes''
```
<$reveal type=nomatch default=true text=<<my-foo-even>>>
...
</$reveal>
```
''only show for last index''
```
<$reveal type=match default=true text=<<my-foo-last>>>
...
</$reveal>
```
!! Live Example
```
<dl>
<$list filter="one two three" iterator=foo>
<dt><<currentTiddler>></dt>
<dd>`<<foo>>` = <<foo>></dd>
<dd>`<<foo-even>>` = <<foo-even>></dd>
<dd>`<<foo-last>>` = <<foo-last>></dd>
</$list>
</dl>
```
Displays as:
<<<
<dl>
<$list filter="one two three" iterator=foo>
<dt><<currentTiddler>></dt>
<dd>`<<foo>>` = <<foo>></dd>
<dd>`<<foo-even>>` = <<foo-even>></dd>
<dd>`<<foo-last>>` = <<foo-last>></dd>
</$list>
</dl>
<<<

119
editions/tw5.com/tiddlers/widgets/ListWidget.tid
View File

@ -1,36 +1,85 @@
created: 201310241419
modified: 20141027193838998
modified: 20150106180000000
tags: Widgets
title: ListWidget
caption: list
! Introduction
The list widget displays a sequence of tiddlers that match a [[tiddler filter|Filters]]. It can be used for many purposes:
The list widget displays a sequence of tiddlers matching a [[filter|Filters]]. It is vital for a various use-cases, e.g.:
* 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
* Displaying custom lists, e.g. "all tiddlers tagged ''task'' not tagged ''done''"
* Listing the tags of a tiddler
* Displaying lists of links, like in the sidebar
* 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. 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.
A number of options controll the list behaviour....
|!Attribute |!Description |
|filter |The [[tiddler filter|Filters]] 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 |
|variable |The [[widget variable|WidgetVariables]] name to be assigned the title of each tiddler in the list. Defaults to ''currentTiddler'' |
|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'' |
|iterator|a custom iterator prefix, see IteratorVariables|
|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 |
!! Handling edit mode
!! 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.
The `<$list>` widget can optionally render draft tiddlers through a different template to handle editing, see DraftMechanism.
!! `storyview` attribute
@ -42,48 +91,6 @@ The `storyview` attribute specifies the name of an optional module that can anim
In order for the storyviews to animate correctly each entry in the list should be a single block mode DOM element.
!! 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="tc-menu-list-item">
<$view field="type"/>
<$list filter="[type{!!type}!is[system]sort[title]]">
<div class="tc-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]]">
<div class="tc-menu-list-item">
<$view field="modified" format="date" template="DDth MMM YYYY"/>
<$list filter="[sameday{!!modified}!is[system]!sort[modified]]">
<div class="tc-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.
!! 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.