From 2b21b74c500421423a543a2f5061e54d3d4f1c73 Mon Sep 17 00:00:00 2001
From: twMat <boardsmm@gmail.com>
Date: Tue, 12 Dec 2017 18:30:18 +0100
Subject: [PATCH] New docs: Introduction to Lists (#3051)

[ref](https://groups.google.com/forum/#!topic/tiddlywiki/oP3r1yx4C14)
---
 .../tiddlers/learning/Introduction to Lists   | 66 +++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 editions/tw5.com/tiddlers/learning/Introduction to Lists

diff --git a/editions/tw5.com/tiddlers/learning/Introduction to Lists b/editions/tw5.com/tiddlers/learning/Introduction to Lists
new file mode 100644
index 000000000..22fd96744
--- /dev/null
+++ b/editions/tw5.com/tiddlers/learning/Introduction to Lists	
@@ -0,0 +1,66 @@
+tags: Learning
+title: Introduction to Lists
+type: text/vnd.tiddlywiki
+
+Lists play a central role in TiddlyWiki and there are several aspects of lists worth understanding. The following is a brief run-through of some of the more common techniques associated with lists.
+
+Note that lists in ~TiddlyWiki often don’t have the typical one-item-per-row appearance but is instead a wider concept to present data.
+
+!Typed lists
+!!~WikiText
+WikiText lists are manually typed lists, including some “special character” to specify what sort of list it is and how it should be displayed. Examples include bullet lists created with asterisks (*) and numbered lists (#). Behind the scenes, ~WikiText lists are based on the simple `<ul>` and `<li>` html-elements. For more, see [[Lists in WikiText]]. A typical typed list in WikiText might look something like:
+
+```
+* Greatest Movies of All Time
+** Casa Blanca
+** Pride and Prejudice and Zombies
+```
+
+and render as:
+
+<<<
+* Greatest Movies of All Time
+** Casa Blanca
+** Pride and Prejudice and Zombies
+<<<
+
+!Generated lists
+Generated lists center around [[filters|Filters]] in which [[filter operators|Filter Operators]] 
+specify which tiddlers and what aspects of these that are desired as output, for example the tiddlers titles or their texts, etc.
+
+!!~ListWidget
+The ListWidget is the most powerful tool for creating lists. It allows the filtered output to be manipulated and styled into forms that may not seem to resemble lists at all, for example tables or complex texts. For more details, see [[ListWidget]].
+
+An example to show all tiddlers tagged with "HelloThere" might look like:
+
+```
+<$list filter="[tag[HelloThere]]"><$view field="title"/><br/></$list>
+```
+
+and render like:
+
+<<<
+<$list filter="[tag[HelloThere]]"><$view field="title"/><br/></$list>
+<<<
+
+''Side note'': Even tiddlers themselves are made with the ~ListWidget. The [[ViewTemplate|$:/core/ui/ViewTemplate]] makes use of the ListWidget to fetch all specified templates that are used to show a tiddlers title, tags, text and more.
+
+!!Filtered transclusion
+The short form for filtered transclusion `{{{...}}}` takes a filter as input and outputs a linked-list of matching titles. You can also apply a [[template|Transclusion with Templates]], for example `{{{ [tag[HelloThere]] || $:/core/ui/TagTemplate }}}` renders like:
+
+<<<
+{{{ [tag[HelloThere]] || $:/core/ui/TagTemplate }}}
+<<<
+
+!!list-links Macro
+The [[list-links|list-links Macro]] macro gives a preformatted list, typically a bullet list, in a more simplified way than by using the ListWidget. Behind the scenes it really is the ListWidget applying a default template to each list item.
+
+`<<list-links "[tag[HelloThere]]">>` gives:
+
+<<list-links "[tag[HelloThere]]">>
+
+!Other “list related” features
+
+[[list|ListField]], [[list-before|Order of Tagged Tiddlers]] and [[list-after|Order of Tagged Tiddlers]] are all field names to control the position of tiddlers in a list. [[Fields|TiddlerFields]] are a way to add additional bits of structured information to a tiddler such as date, quantity, category, etc.
+
+[[list|list Operator]] and [[listed|listed Operator]] are //filter operators// to, respectively, select and find titles in lists.