mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-06-16 02:19:55 +00:00
Merge remote-tracking branch 'upstream/master'
This commit is contained in:
Bram Chen
commit
42bd29fe0b
|
|
@ -4,7 +4,7 @@ description: Render tiddlers matching a filter to a specified ContentType
|
|||
Render a set of tiddlers matching a filter to separate files of a specified ContentType (defaults to `text/html`) and extension (defaults to `.html`).
|
||||
|
||||
```
|
||||
--rendertiddlers <filter> <template> <pathname> [<type>] [<extension>]
|
||||
--rendertiddlers <filter> <template> <pathname> [<type>] [<extension>] ["noclean"]
|
||||
```
|
||||
|
||||
For example:
|
||||
|
|
@ -15,4 +15,4 @@ For example:
|
|||
|
||||
By default, the pathname is resolved relative to the `output` subdirectory of the edition directory. The `--output` command can be used to direct output to a different directory.
|
||||
|
||||
Any files in the target directory are deleted. The target directory is recursively created if it is missing.
|
||||
Any files in the target directory are deleted unless the "noclean" parameter is specified. The target directory is recursively created if it is missing.
|
||||
|
|
|
|||
|
|
@ -38,8 +38,11 @@ Command.prototype.execute = function() {
|
|||
pathname = path.resolve(this.commander.outputPath,this.params[2]),
|
||||
type = this.params[3] || "text/html",
|
||||
extension = this.params[4] || ".html",
|
||||
deleteDirectory = (this.params[5] || "") != "noclean",
|
||||
tiddlers = wiki.filterTiddlers(filter);
|
||||
$tw.utils.deleteDirectory(pathname);
|
||||
if(deleteDirectory){
|
||||
$tw.utils.deleteDirectory(pathname);
|
||||
}
|
||||
$tw.utils.createDirectory(pathname);
|
||||
$tw.utils.each(tiddlers,function(title) {
|
||||
var parser = wiki.parseTiddler(template),
|
||||
|
|
|
|||
45
core/modules/parsers/wikiparser/rules/syslink.js
Normal file
45
core/modules/parsers/wikiparser/rules/syslink.js
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
/*\
|
||||
title: $:/core/modules/parsers/wikiparser/rules/syslink.js
|
||||
type: application/javascript
|
||||
module-type: wikirule
|
||||
|
||||
Wiki text inline rule for system tiddler links.
|
||||
Can be suppressed preceding them with `~`.
|
||||
\*/
|
||||
(function(){
|
||||
|
||||
/*jslint node: true, browser: true */
|
||||
/*global $tw: false */
|
||||
"use strict";
|
||||
|
||||
exports.name = "syslink";
|
||||
exports.types = {inline: true};
|
||||
|
||||
exports.init = function(parser) {
|
||||
this.parser = parser;
|
||||
// Regexp to match
|
||||
this.matchRegExp = /~?\$:[^\s<|]+(?:[^\s<|])/mg;
|
||||
};
|
||||
|
||||
exports.parse = function() {
|
||||
var match = this.match[0];
|
||||
// Move past the match
|
||||
this.parser.pos = this.matchRegExp.lastIndex;
|
||||
// Create the link unless it is suppressed
|
||||
if(match.substr(0,1) === "~") {
|
||||
return [{type: "text", text: match.substr(1)}];
|
||||
} else {
|
||||
return [{
|
||||
type: "link",
|
||||
attributes: {
|
||||
to: {type: "string", value: match}
|
||||
},
|
||||
children: [{
|
||||
type: "text",
|
||||
text: match
|
||||
}]
|
||||
}];
|
||||
}
|
||||
};
|
||||
|
||||
})();
|
||||
|
|
@ -12,6 +12,9 @@ type: text/vnd.tiddlywiki-html
|
|||
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
|
||||
<meta name="generator" content="TiddlyWiki" />
|
||||
<meta name="tiddlywiki-version" content="{{$:/core/templates/version}}" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<meta name="apple-mobile-web-app-capable" content="yes" />
|
||||
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
|
||||
<meta name="format-detection" content="telephone=no">
|
||||
<link id="faviconLink" rel="shortcut icon" href="favicon.ico">
|
||||
<title>{{$:/core/wiki/title}}</title>
|
||||
|
|
|
|||
|
|
@ -10,6 +10,9 @@ title: $:/core/templates/static.tiddler.html
|
|||
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
|
||||
<meta name="generator" content="TiddlyWiki" />
|
||||
<meta name="tiddlywiki-version" content="`{{$:/core/templates/version}}`" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<meta name="apple-mobile-web-app-capable" content="yes" />
|
||||
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
|
||||
<meta name="format-detection" content="telephone=no">
|
||||
<link id="faviconLink" rel="shortcut icon" href="favicon.ico">
|
||||
<link rel="stylesheet" href="static.css">
|
||||
|
|
|
|||
9
core/ui/Components/tag-link.tid
Normal file
9
core/ui/Components/tag-link.tid
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
title: $:/core/ui/Components/tag-link
|
||||
|
||||
<$link>
|
||||
<$set name="backgroundColor" value={{!!color}}>
|
||||
<span style=<<tag-styles>> class="tc-tag-label">
|
||||
<$view field="title" format="text"/>
|
||||
</span>
|
||||
</$set>
|
||||
</$link>
|
||||
|
|
@ -27,14 +27,12 @@ background-color:$(backgroundColor)$;
|
|||
<$reveal state=<<qualify "$:/state/popup/tags-auto-complete">> type="nomatch" text="" default="">
|
||||
<div class="tc-block-dropdown">
|
||||
<$linkcatcher set="$:/temp/NewTagName" setTo="" message="tm-add-tag">
|
||||
<$list filter="[!is[shadow]tags[]search{$:/temp/NewTagName}sort[title]]">
|
||||
<$link>
|
||||
<$set name="backgroundColor" value={{!!color}}>
|
||||
<span style=<<tag-styles>> class="tc-tag-label">
|
||||
<$view field="title" format="text"/>
|
||||
</span>
|
||||
</$set>
|
||||
</$link>
|
||||
<$list filter="[tags[]search:title{$:/temp/NewTagName}sort[]]">
|
||||
{{||$:/core/ui/Components/tag-link}}
|
||||
</$list>
|
||||
<hr>
|
||||
<$list filter="[!is[system]search:title{$:/temp/NewTagName}sort[]]">
|
||||
{{||$:/core/ui/Components/tag-link}}
|
||||
</$list>
|
||||
</$linkcatcher>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -1,28 +1,48 @@
|
|||
caption: 5.1.8
|
||||
created: 20141219225007260
|
||||
modified: 20141219225007260
|
||||
created: 20150111154632954
|
||||
modified: 20150111154632954
|
||||
tags: ReleaseNotes
|
||||
title: Release 5.1.8
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
//[[See GitHub for detailed change history of this release|https://github.com/Jermolene/TiddlyWiki5/compare/v5.1.7...v5.1.8]]//
|
||||
|
||||
This release includes many improvements to the documentation for TiddlyWiki. Many thanks to everyone who has helped out, but especially to our prodigious new contributor Astrid Elocson.
|
||||
|
||||
!! Translation Improvements
|
||||
|
||||
*
|
||||
* Improvements to French, Chinese and Japanese translations
|
||||
|
||||
* [[Added|https://github.com/Jermolene/TiddlyWiki5/commit/5d947ed582fb9d68c01d82a334ab75498a8724ef]] Spanish translation
|
||||
* [[Added|https://github.com/Jermolene/TiddlyWiki5/commit/cb8caf6a01aeeac480bf28661888961657b0dbd8]] Czech translation
|
||||
|
||||
!! Usability Improvements
|
||||
|
||||
* [[Improved|https://github.com/Jermolene/TiddlyWiki5/pull/1353]] behaviour of the tag dropdown in the edit template
|
||||
* [[Added|https://github.com/Jermolene/TiddlyWiki5/commit/ea6e60e66983ee1184f09c5796ef6c8bceae703a]] automatic focusing of the search box at startup
|
||||
* [[Introduced|https://github.com/Jermolene/TiddlyWiki5/commit/4f3cb8b9aebfc4f65f40c96ef99730887d746b41]] the [[Railroad Plugin]] by Astrid Elocson (see it in action in the new [[Filter Syntax]] documentation)
|
||||
* [[Migrated|https://github.com/Jermolene/TiddlyWiki5/commit/230066eeae9ace8336612e02c78f8cdaa3f717e4]] functionality of "Sticky Titles" theme into "Vanilla"/"Snow White". This means that tiddler titles will stick to the top of the window during scrolling on browsers that support `position: sticky` (such as Safari and Firefox)
|
||||
* [[Added|https://github.com/Jermolene/TiddlyWiki5/commit/8cb7090c40489c81e8c5dfb8cbbdee2c60998c3e]] icons to [[$:/AdvancedSearch]], [[$:/ControlPanel]] and [[$:/TagManager]]
|
||||
* [[Changed|https://github.com/Jermolene/TiddlyWiki5/commit/b9129d77e99970579074bdb4f9c2ef4b77b812c6]] wording of tiddler "save" button to "store"
|
||||
* [[Added|https://github.com/Jermolene/TiddlyWiki5/issues/1103]] automatic linking of system tiddlers such as $:/ControlPanel
|
||||
|
||||
!! Hackability Improvements
|
||||
|
||||
*
|
||||
* [[Added|https://github.com/Jermolene/TiddlyWiki5/commit/a1ca53fa9bab218719b582bd553a578a477666c9]] IteratorVariables to the ListWidget
|
||||
|
||||
!! Bug Fixes
|
||||
|
||||
*
|
||||
* [[Fixed|https://github.com/Jermolene/TiddlyWiki5/pull/1249]] version number compatibility checks for plugins
|
||||
* [[Fixed|https://github.com/Jermolene/TiddlyWiki5/commit/1adfe20508116da0ee4b5c9e72ea9742f24b60c9]] problem with repeatedly cancelling a draft
|
||||
|
||||
!! Node.js Changes
|
||||
|
||||
//These changes are only relevant to people using TiddlyWiki under Node.js//
|
||||
|
||||
*
|
||||
* [[Fixed|https://github.com/Jermolene/TiddlyWiki5/commit/cc85368fd48f1e5878018a4e00b6c17d436e67a9]] [[Highlight Plugin]] to work when generating static files under Node.js
|
||||
* [[Fixed|https://github.com/Jermolene/TiddlyWiki5/commit/c296f14210545374124df5d4ae9ffb402ed73561]] problem with case-insensitive filing systems (eg Windows)
|
||||
* [[Added|https://github.com/Jermolene/TiddlyWiki5/pull/1354]] mobile metadata to static page templates
|
||||
* [[Added|https://github.com/Jermolene/TiddlyWiki5/pull/1352]] added "noclean" parameter to RenderTiddlersCommand
|
||||
|
||||
!! Changes affecting plugin authors
|
||||
|
||||
|
|
@ -32,13 +52,18 @@ type: text/vnd.tiddlywiki
|
|||
|
||||
[[@Jermolene|https://github.com/Jermolene]] would like to thank the contributors to this release who have generously given their time to help improve TiddlyWiki:
|
||||
|
||||
* [[@anavarre|https://github.com/anavarre]]
|
||||
|
||||
* [[@aelocson|https://github.com/aelocson]]
|
||||
* [[@Arlen22|https://github.com/Arlen22]]
|
||||
* [[@BramChen|https://github.com/BramChen]]
|
||||
* [[@Drakor|https://github.com/Drakor]]
|
||||
* [[@dullroar|https://github.com/dullroar]]
|
||||
* [[@erwanm|https://github.com/erwanm]]
|
||||
* [[@malgam|https://github.com/malgam]]
|
||||
* [[@nameanyone|https://github.com/nameanyone]]
|
||||
* [[@pekopeko1|https://github.com/pekopeko1]]
|
||||
* [[@Spangenhelm|https://github.com/Spangenhelm]]
|
||||
* [[@dpdannemiller|https://github.com/dpdannemiller]]
|
||||
* [[@evgeniy-gryaznov|https://github.com/evgeniy-gryaznov]]
|
||||
* [[@felixhayashi|https://github.com/felixhayashi]]
|
||||
* [[@gernert|https://github.com/gernert]]
|
||||
* [[@Infurnoape|https://github.com/Infurnoape]]
|
||||
* [[@Jc-L|https://github.com/Jc-L]]
|
||||
* [[@tobibeer|https://github.com/tobibeer]]
|
||||
* [[@twMat|https://github.com/twMat]]
|
||||
* [[@welford|https://github.com/welford]]
|
||||
* [[@xcazin|https://github.com/xcazin]]
|
||||
|
|
|
|||
|
|
@ -175,12 +175,12 @@ describe("Filter tests", function() {
|
|||
});
|
||||
|
||||
it("should handle the links operator", function() {
|
||||
expect(wiki.filterTiddlers("[!is[shadow]links[]sort[title]]").join(",")).toBe("a fourth tiddler,one,Tiddler Three,TiddlerSix,TiddlerTwo,TiddlerZero");
|
||||
expect(wiki.filterTiddlers("[!is[shadow]links[]sort[title]]").join(",")).toBe("$:/TiddlerTwo,a fourth tiddler,one,Tiddler Three,TiddlerSix,TiddlerZero");
|
||||
expect(wiki.filterTiddlers("[all[shadows]links[]sort[title]]").join(",")).toBe("TiddlerOne");
|
||||
});
|
||||
|
||||
it("should handle the backlinks operator", function() {
|
||||
expect(wiki.filterTiddlers("[!is[shadow]backlinks[]sort[title]]").join(",")).toBe("a fourth tiddler,one");
|
||||
expect(wiki.filterTiddlers("[!is[shadow]backlinks[]sort[title]]").join(",")).toBe("a fourth tiddler,one,TiddlerOne");
|
||||
expect(wiki.filterTiddlers("[all[shadows]backlinks[]sort[title]]").join(",")).toBe("Tiddler Three");
|
||||
});
|
||||
|
||||
|
|
@ -248,7 +248,7 @@ describe("Filter tests", function() {
|
|||
});
|
||||
|
||||
it("should handle the '[is[missing]]' operator", function() {
|
||||
expect(wiki.filterTiddlers("[all[missing]]").join(",")).toBe("TiddlerZero,TiddlerTwo");
|
||||
expect(wiki.filterTiddlers("[all[missing]]").join(",")).toBe("TiddlerZero");
|
||||
expect(wiki.filterTiddlers("[!is[missing]sort[title]]").join(",")).toBe("$:/TiddlerTwo,a fourth tiddler,one,Tiddler Three,TiddlerOne");
|
||||
expect(wiki.filterTiddlers("[[TiddlerOne]is[missing]]").join(",")).toBe("");
|
||||
expect(wiki.filterTiddlers("[[TiddlerZero]is[missing]]").join(",")).toBe("TiddlerZero");
|
||||
|
|
|
|||
|
|
@ -1,38 +0,0 @@
|
|||
created: 20141226192500000
|
||||
title: Instruction Tiddlers
|
||||
tags: documenting
|
||||
|
||||
Instruction tiddlers talk directly to the reader and guide them through a process. The reader is likely to be a beginner or an intermediate user.
|
||||
|
||||
Such tiddlers can be subcategorised as:
|
||||
|
||||
* ''Welcome''
|
||||
** What is ~TiddlyWiki and why should I care?
|
||||
** Demonstrations of key features and benefits
|
||||
** Frequently asked questions
|
||||
** Examples of ~TiddlyWiki in the field
|
||||
** Information about the project itself
|
||||
|
||||
* ''Tutorial''
|
||||
** An ordered presentation of material for beginners
|
||||
** Each tiddler introduces one new point or concept
|
||||
** Its main content contains very few links
|
||||
** A revealable "Further reading" section at the end can offer related links
|
||||
|
||||
* ''Exercise''
|
||||
** Accompanying a tutorial tiddler
|
||||
** Solution revealed on demand
|
||||
|
||||
* ''How-to''
|
||||
** A list of numbered steps for performing a small specific task
|
||||
** Concise, with links to reference tiddlers where appropriate
|
||||
** Often has a preamble to clarify the nature of the task
|
||||
|
||||
* ''Example''
|
||||
** Accompanying a [[Reference Tiddler|Reference Tiddlers]]
|
||||
** Can contain explanations and similar commentary
|
||||
** Kept separate to keep the reference tiddler pure
|
||||
|
||||
Instruction tiddlers talk directly to the reader as "you". They can be reasonably chatty.
|
||||
|
||||
But they avoid excessively colloquial language, cultural or topical references and attempts at humour, as these can baffle or even offend the international readership. They also avoid potentially frustrating the reader with descriptions of features as "convenient" or "easy".
|
||||
|
|
@ -1,25 +0,0 @@
|
|||
created: 20141226192500000
|
||||
title: Reference Tiddlers
|
||||
tags: documenting
|
||||
|
||||
Reference tiddlers offer raw information in a comprehensive interlinked way. The reader is likely to be an intermediate or expert user.
|
||||
|
||||
There are several subcategories:
|
||||
|
||||
* ''Concepts''
|
||||
** With definitions, together forming a glossary
|
||||
* ''User manual''
|
||||
** Presenting technical details of ~WikiText features
|
||||
** Subcategorised: messages, operators, widgets, etc
|
||||
* ''Developer manual''
|
||||
** Presenting technical details of ~TiddlyWiki's internal architecture
|
||||
|
||||
Reference material is written in a terse, formal style that avoids referring to the reader, and instead focuses on how ~TiddlyWiki itself behaves. The passive voice is often suitable:
|
||||
|
||||
* "the template can be specified as a tiddler" rather than "specify the template as a tiddler"
|
||||
* "the widget can be used for various purposes" rather than "you can use the widget for various purposes"
|
||||
* But "this widget has several possible uses" is better, because it is more succinct
|
||||
|
||||
Contracted verb forms are normally avoided in reference tiddlers.
|
||||
|
||||
To reduce the risk that the reader will overlook the word "not", it can be italicised.
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
created: 20141226192500000
|
||||
title: Tiddler Titles
|
||||
tags: documenting
|
||||
|
||||
Each of the main words of a tiddler title begins with a capital letter, but minor words such as "and", "or", "the", "to" and "with" do not. Avoid starting a tiddler with the word "the".
|
||||
|
||||
[[Reference Tiddlers]] have ~CamelCase nouns as their titles, e.g. ''~RevealWidget'', ''~CamelCase'', ''CSS''. The title is plural if it denotes a category, e.g. ''~KeyboardShortcuts'', ''~TiddlerFields''. Such categories are used to tag more specific tiddlers within the category.
|
||||
|
||||
Other tags usually consist of a single lowercase word. Avoid spaces in tags.
|
||||
|
||||
[[Instruction Tiddlers]] have spaces between the words of their titles. Each word that contributes significantly to the meaning of the title starts with a capital letter. Words that are little more than structural signposts ("the", "and", "of", etc) are entirely lowercase.
|
||||
|
||||
How-to tiddlers have titles that begin with ''How to''.
|
||||
|
|
@ -1,26 +0,0 @@
|
|||
created: 20141226192500000
|
||||
title: Typography
|
||||
tags: documenting
|
||||
|
||||
Use ''bold'' when referring to:
|
||||
|
||||
* Captions in ~TiddlyWiki's user interface:
|
||||
** "the ''Recent'' tab", "the ''Hide sidebar'' button"
|
||||
* Tiddler fields:
|
||||
** "the ''list'' field"
|
||||
* Example tiddlers and tags:
|
||||
** "create a tiddler called ''Super Soup Recipe'' with the tag ''cookery''"
|
||||
|
||||
''Bold'' is also used to make part or all of a sentence stand out from the rest of the tiddler.
|
||||
|
||||
Use //italics// to give more subtle emphasis to a word or phrase.
|
||||
|
||||
Use `monospaced` text when a sentence contains a fragment of ~WikiText or a string that the user could type.
|
||||
|
||||
Use the double quotation mark `"` as the basic one. It is easier to read on screen, and it avoids confusion with the apostrophe. To keep things clean and simple, quotation marks and apostrophes should be straight `'`, not curly `’`, and the ellipsis should be three separate dots `...` rather than `…`
|
||||
|
||||
Avoid using a single hyphen `-` as sentence punctuation. Instead, use a double hyphen -- which ~TiddlyWiki renders as an en-dash -- with a space on either side.
|
||||
|
||||
Items in lists and tables should only end with a full stop (period in US English) if they are complete sentences. They should have no trailing punctuation otherwise.
|
||||
|
||||
It is very rarely necessary to use an exclamation mark in professional documentation.
|
||||
|
|
@ -1,16 +1,25 @@
|
|||
created: 20130827080000000
|
||||
created: 20130827080000000=
|
||||
modified: 20140912145347313
|
||||
tags: Reference Concepts
|
||||
title: Filters
|
||||
type: text/vnd.tiddlywiki
|
||||
list: [[Introduction to filter notation]] [[Filter Syntax]]
|
||||
|
||||
Filters are used in TiddlyWiki to choose tiddlers by specifying simple match criteria. They are used by widgets like the ListWidget and the CountWidget to perform operations on multiple tiddlers at once.
|
||||
You can think of TiddlyWiki as a database where the records are tiddlers. A database typically provides a way of discovering which records match a given pattern, and in ~TiddlyWiki this is done with filters.
|
||||
|
||||
* [[Introduction to Filters]] is a step-by-step introduction to how filters are used
|
||||
* [[Filter Syntax]] explains the exact rules for writing filters
|
||||
A <<doc-def filter>> is a concise notation for selecting a particular set of tiddlers, known as its <<doc-def "result">>. Whenever ~TiddlyWiki encounters a filter, it calculates the result. Further work can then be done with just those tiddlers, such as [[counting|CountWidget]] or [[listing|ListWidget]] them.
|
||||
|
||||
The most common filter operators are:
|
||||
The following example passes a filter to the [[list-links macro|ListMacro]] to display a list of all tiddlers whose titles start with the letter H:
|
||||
|
||||
<<list-links "[tag[CommonFilters]]">>
|
||||
```
|
||||
<<list-links "[prefix[H]]">>
|
||||
```
|
||||
|
||||
See FilterOperators for a complete list of available filter operators
|
||||
The result of a filter can change as tiddlers are added and deleted in the wiki. ~TiddlyWiki recalculates the results on the fly, automatically updating any filter-based counts or lists as well.
|
||||
|
||||
[[Advanced Search|$:/AdvancedSearch]] has a <<doc-advancedsearch-tab Filter>> tab that makes it easy to experiment with filters.
|
||||
|
||||
;Find out more:
|
||||
* [[Introduction to filter notation]] -- a step-by-step walkthrough
|
||||
* [[Filter Syntax]] -- the exact rules of the notation
|
||||
* [[FilterOperators]] -- the available methods of filtering
|
||||
|
|
@ -10,6 +10,8 @@ Each diagram starts on the left and ends on the right. Simply follow any line fr
|
|||
start [:optional] {repeated +","} end
|
||||
"""/>
|
||||
|
||||
In the example above, a comma appears between each occurrence of the `repeated` item. The comma path runs from right to left, and can only be reached by first passing through `repeated`.
|
||||
|
||||
Characters in round boxes are literal, i.e. they denote themselves. A name in a rectangular box denotes a further railroad diagram.
|
||||
|
||||
The railroad diagrams on this site are generated using the [[Railroad Plugin]].
|
||||
The railroad diagrams on this site are generated with the [[Railroad Plugin]].
|
||||
|
|
|
|||
18
editions/tw5.com/tiddlers/demonstrations/GroupedLists.tid
Normal file
18
editions/tw5.com/tiddlers/demonstrations/GroupedLists.tid
Normal 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">>
|
||||
|
|
@ -22,4 +22,4 @@ Clicking on the magnifying glass icon to the right of the search box will open [
|
|||
|
||||
* The ''shadows'' tab allows you to limit your search to shadow tiddlers
|
||||
|
||||
* The ''filter'' tab is not a search box, per se, but a way to obtain a list of all tiddlers that meet the specific criteria described by that filter, for example, "All tags except system tags". More information in [[Introduction to Filters]]
|
||||
* The ''filter'' tab is not a search box, per se, but a way to obtain a list of all tiddlers that meet the specific criteria described by that [[filter|Filters]], for example, "All tags except system tags"
|
||||
|
|
|
|||
|
|
@ -4,8 +4,14 @@ tags: Concepts
|
|||
title: FilterOperators
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
Filter operators are the individual elements of [[filters|Filters]]. See [[Introduction to Filters]] for details.
|
||||
A <<doc-def "filter operator">> is a predefined name attached to an individual step in a [[filter|Filters]]. It defines how that step is to be performed.
|
||||
|
||||
The full list of available filter operators is:
|
||||
A typical step is written as `[operator[parameter]]`, although not all of the operators need a parameter.
|
||||
|
||||
<<list-links "[tag[Filters]]">>
|
||||
Here are the most commonly used operators:
|
||||
|
||||
<<list-links "[tag[CommonFilters]]">>
|
||||
|
||||
The complete list is:
|
||||
|
||||
<<list-links "[tag[Filters]] -[[Introduction to filter notation]] -[[Filter Syntax]]">>
|
||||
|
|
|
|||
|
|
@ -4,7 +4,9 @@ tags: Filters
|
|||
title: Filter Syntax
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
[[Filter expressions|Filters]] follow a grammar that is presented here, using [[RailroadDiagrams]], for those who find formal syntax descriptions helpful. However, you can write your own filter expressions without needing to understand this tiddler.
|
||||
[[Filters]] follow a grammar that is presented here, using [[RailroadDiagrams]], for those who find formal syntax descriptions helpful. However, [[you can learn to write filters|Introduction to filter notation]] without needing to understand this tiddler.
|
||||
|
||||
When a filter is evaluated, it generates a <<doc-def result>>, which is an ordered set of items. No item can appear more than once in the result. The items are usually tiddler titles, but certain specialised filters generate other items, such as Node.js command words.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -13,14 +15,14 @@ type: text/vnd.tiddlywiki
|
|||
{ [:whitespace] ("+" | :- | "-") run }
|
||||
"""/>
|
||||
|
||||
A sequence of runs is evaluated from left to right, as follows:
|
||||
A <<doc-def filter>> is a sequence of runs, evaluated from left to right.
|
||||
|
||||
|!Sequence |!Interpretation |
|
||||
|`run1 run2` |union of the sets, i.e. the tiddlers in //either// run1 //or// run2 |
|
||||
|`run1 -run2` |difference of the sets, i.e. run1 but excluding any tiddlers in run2 |
|
||||
|`run1 +run2` |run2 takes run1 as its input |
|
||||
Each run receives an <<doc-def "input set">>, which it modifies to produce a result. The first run in a sequence receives `[all[tiddlers]]` as its input, i.e. the set of all non-missing tiddlers. The second run receives the result of the first run as its input, and so on.
|
||||
|
||||
The first run takes `[all[tiddlers]]` as its input, i.e. the set of all non-missing tiddlers.
|
||||
|!Run |!Interpretation |!Result |
|
||||
|`run` |union of sets|input OR run |
|
||||
|`+run` |intersection of sets |input AND run |
|
||||
|`-run` |difference of sets|input AND NOT run |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -28,45 +30,59 @@ The first run takes `[all[tiddlers]]` as its input, i.e. the set of all non-miss
|
|||
: <$railroad text="""
|
||||
( "[" {step} "]"
|
||||
|
|
||||
'"' [{/'any character except "'/}] '"'
|
||||
|
|
||||
"'" [{/"any character except '"/}] '"'
|
||||
|
|
||||
[{/"any character except [ ] or whitespace"/}]
|
||||
[:{/"anything but [ ] or whitespace"/}]
|
||||
)
|
||||
"""/>
|
||||
* The last three options are short for `[title[text]]`
|
||||
* A run evaluates each of its steps and returns the intersection of the results
|
||||
|
||||
<!-- The following has been removed from the diagram until issue #1346 is addressed:
|
||||
'"' [:{/'anything but "'/}] '"'
|
||||
|
|
||||
"'" [:{/"anything but '"/}] '"'
|
||||
|
|
||||
-->
|
||||
|
||||
The lower option, e.g. matching `HelloThere`, is short for `[title[HelloThere]]`.
|
||||
|
||||
A <<doc-def run>> is a sequence of steps, evaluated from left to right.
|
||||
|
||||
The run's result is basically the intersection of the step results. In other words, the run's result contains the items that are found in <<doc-em all>> of the step results.
|
||||
|
||||
However, a few operators (known as <<doc-def selectors>>) ignore any preceding steps in the same run, and completely replace the result so far. Examples of this are <<doc-clink "commands" "FilterOperator: commands">> and <<doc-clink "title" "FilterOperator: title">>, but not <<doc-clink "field:title" "FilterOperator: field">>.
|
||||
|
||||
---
|
||||
|
||||
;step
|
||||
: <$railroad text="""
|
||||
[:"!"] operator parameter
|
||||
[:"!"] [:method] parameter
|
||||
"""/>
|
||||
* A step returns a set of tiddlers, in the form of a TitleList
|
||||
|
||||
If the method is omitted, it defaults to `title`.
|
||||
|
||||
---
|
||||
|
||||
;operator
|
||||
;method
|
||||
: <$railroad text="""
|
||||
( keyword [:":" fieldname] | fieldname )
|
||||
operator [:":" suffix]
|
||||
"""/>
|
||||
* Keywords are reserved names (<code>[[is|FilterOperator: is]]</code>, <code>[[has|FilterOperator: has]]</code>, <code>[[tag|FilterOperator: tag]]</code>, etc) of specific filtering functions
|
||||
* A fieldname on its own implies the keyword `field`
|
||||
* An entirely omitted operator defaults to `title`
|
||||
|
||||
The operator is drawn from a list of [[predefined names|FilterOperators]].
|
||||
|
||||
The suffix is additional information, usually the name of a [[field|TiddlerFields]], that extends the meaning of certain operators.
|
||||
|
||||
An unrecognised operator name is is treated as the suffix to the <<doc-clink "field" "FilterOperator: field">> operator.
|
||||
|
||||
---
|
||||
|
||||
;parameter
|
||||
: <$railroad text="""
|
||||
( "[" [{/"any character except ]"/}] "]"
|
||||
( "[" [:{/"anything but ]"/}] "]"
|
||||
|
|
||||
"{" [{/"any character except }"/}] "}"
|
||||
"{" [:{/"anything but }"/}] "}"
|
||||
|
|
||||
"<" [{/"any character except >"/}] ">"
|
||||
"<" [:{/"anything but >"/}] ">"
|
||||
)
|
||||
"""/>
|
||||
|
||||
* `[`...`]` encloses a literal parameter
|
||||
* `{`...`}` encloses a TextReference parameter
|
||||
* `<`...`>` encloses a [[variable|Variables]] parameter
|
||||
|
|
@ -76,5 +92,4 @@ The first run takes `[all[tiddlers]]` as its input, i.e. the set of all non-miss
|
|||
;whitespace
|
||||
: <$railroad text="""
|
||||
{( "space" | "tab" | "linefeed" | "return" | "vertical tab" | "formfeed" )}
|
||||
"""/>
|
||||
* A match for the JavaScript regular expression `\s+`
|
||||
"""/>
|
||||
|
|
@ -1,146 +1,114 @@
|
|||
created: 20140410101941871
|
||||
modified: 20141009180223576
|
||||
tags: Learning
|
||||
title: Introduction to Filters
|
||||
tags: Learning Filters
|
||||
title: Introduction to filter notation
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
This is a step-by-step introduction to how [[Filters]] are used. [[Filter Syntax]] presents a more technical summary of this information.
|
||||
: (This explains the basics of writing a [[filter|Filters]] to select a set of tiddlers. For a more technical summary, see [[Filter Syntax]].)
|
||||
|
||||
! Using Filters
|
||||
|
||||
Filters are a special notation for expressing lists of tiddlers within WikiText.
|
||||
|
||||
Filters are used in the ListMacro, TabsMacro, ListWidget, CountWidget, and many other areas of TiddlyWiki.
|
||||
|
||||
For example, this is how the ListMacro would be used to display the first example below:
|
||||
The simplest case is where you already know exactly which tiddlers you want. Type each title in double square brackets, with a space or linebreak between each one and the next:
|
||||
|
||||
```
|
||||
<<list-links "HelloThere Introduction [[Title with Spaces]]">>
|
||||
[[Recipe book]] [[ScrambledEggs]] [[Mom's apple pie]]
|
||||
```
|
||||
|
||||
The easiest way to experiment with tiddler filters is by typing them into the ''Filter'' tab of the [[advanced search panel|$:/AdvancedSearch]].
|
||||
|
||||
! Simple Filters
|
||||
|
||||
The simplest example of a filter is a list of tiddler titles (if necessary quoted with double square brackets):
|
||||
You can omit the square brackets when a title doesn't contain any spaces:
|
||||
|
||||
```
|
||||
HelloThere Introduction [[Title with Spaces]]
|
||||
```
|
||||
|
||||
The titles must be separated by one or more spaces and/or linebreaks.
|
||||
|
||||
! Filter Operators
|
||||
|
||||
Filter operators are used to select tiddlers in particular ways. For example, this filter consists of a single step that selects all tiddlers tagged ''introduction'':
|
||||
[[Recipe book]] ScrambledEggs [[Mom's apple pie]]
|
||||
|
||||
```
|
||||
[tag[introduction]]
|
||||
```
|
||||
|
||||
The word `tag` is the ''operator'' and `introduction` is the ''parameter'' (sometimes called the ''operand'').
|
||||
|
||||
See [[Filters]] for a complete list of the available operators.
|
||||
|
||||
!! Default Filter Operator
|
||||
|
||||
The operator defaults to `title` if omitted, so `[[HelloThere]]` is equivalent to `[title[HelloThere]]`. If there are no spaces in the title, then the double square brackets can also be omitted: `HelloThere`.
|
||||
|
||||
! Negating Filter Steps
|
||||
|
||||
A filter step can be negated by preceding the operator with an exclamation mark (`!`). This example selects all tiddlers that are not tagged ''introduction'':
|
||||
The double square brackets are actually a shorthand for this:
|
||||
|
||||
```
|
||||
[!tag[introduction]]
|
||||
[title[Scrambled eggs]]
|
||||
```
|
||||
|
||||
! Operator Suffixes
|
||||
|
||||
Some filter operators can take an optional suffix that provides further information. For example, the `field` operator takes a suffix indicating the field to be compared. The following filter returns all tiddlers that have ''JeremyRuston'' in the `modifier` field:
|
||||
… which gives us the <<doc-def "general model">> for any filter:
|
||||
|
||||
```
|
||||
[field:modifier[JeremyRuston]]
|
||||
[method[parameter]]
|
||||
```
|
||||
|
||||
! Field Operator Shortcut
|
||||
|
||||
If an operator is not recognised, then it is instead interpreted as the suffix of the `field` operator. Thus, these two filters both return all the tiddlers that contain the string ''create'' in their `caption` field:
|
||||
For instance, here's how to select all the tiddlers that have been tagged <<doc-tag Recipe>>:
|
||||
|
||||
```
|
||||
[caption[create]]
|
||||
[field:caption[create]]
|
||||
[tag[Recipe]]
|
||||
```
|
||||
|
||||
! Indirect Parameters
|
||||
|
||||
If a filter step has curly brackets around its parameter, then it is taken to be a TextReference to the actual value. For example, this filter selects all tiddlers containing the string contained in the ''$:/temp/search'' tiddler:
|
||||
We can reverse the meaning by adding an exclamation mark `!` just before the method. For example, we can select any tiddlers that do <<doc-em not>> have the <<doc-tag Recipe>> tag:
|
||||
|
||||
```
|
||||
[search{$:/temp/search}]
|
||||
[!tag[Recipe]]
|
||||
```
|
||||
|
||||
! Variable Parameters
|
||||
Tiddlers can be filtered by other fields than just title and tags:
|
||||
|
||||
If a filter step has angle brackets around its parameter, then it is taken to be the name of a variable containing the actual value. For example, this filter selects all tiddlers containing the title of the current tiddler:
|
||||
```
|
||||
[field:serving[4]]
|
||||
```
|
||||
|
||||
That example will select any tiddlers that have <<doc-field-value 4>> in their <<doc-field serving>> field.
|
||||
|
||||
As the word "serving" isn't a standard filter method (and isn't likely to become one), you can safely omit the `field:` prefix:
|
||||
|
||||
```
|
||||
[serving[4]]
|
||||
```
|
||||
|
||||
!Combinations
|
||||
|
||||
The filters we've looked at so far have involved just one step each. But you can <<doc-def run>> several steps together like this:
|
||||
|
||||
```
|
||||
[tag[Vegetarian]!tag[soup]serving[4]]
|
||||
```
|
||||
|
||||
Notice how the entire run is contained in a single pair of square brackets.
|
||||
|
||||
A tiddler has to match <<doc-em all>> of the steps in a run. So the example above retrieves vegetarian recipes (other than soups) for 4 people.
|
||||
|
||||
A <<doc-em sequence>> of runs will select the tiddlers that match <<doc-em any>> of the runs. We can use this to find recipes that serve either 3, 4 or 5 people:
|
||||
|
||||
```
|
||||
[serving[3]] [serving[4]] [serving[5]]
|
||||
```
|
||||
|
||||
If we want to ignore vegetarian recipes that serve 4, we can say this:
|
||||
|
||||
```
|
||||
[serving[3]] [serving[4]!tag[vegetarian]] [serving[5]]
|
||||
```
|
||||
|
||||
By default, each run considers every tiddler in the wiki. But we can use a `+` sign to force a run to consider only the tiddlers that were selected by the preceding runs:
|
||||
|
||||
```
|
||||
[serving[3]] [serving[4]] [serving[5]] +[tag[Vegetarian]] +[sort[title]]
|
||||
```
|
||||
|
||||
This selects recipes for 3, 4 or 5 people, then filters <<doc-em those>> to remove the vegetarian ones, and finally sorts any that are left into alphabetical order of title.
|
||||
|
||||
In a similar way, we can use a `-` sign to <<doc-em remove>> a run's tiddlers from the result so far. Here we select all vegetarian recipes apart from two:
|
||||
|
||||
```
|
||||
[tag[Vegetarian]] -[title[ScrambledEggs]] -BeansOnToast
|
||||
```
|
||||
|
||||
!Special parameters
|
||||
|
||||
The parameter of each step we've seen so far has been in square brackets, meaning that ~TiddlyWiki treats it literally. But two other kinds of bracket are possible:
|
||||
|
||||
<<doc-def "Curly brackets">> `{}` mean that the parameter is a TextReference, and that its value is to be looked up in a specified tiddler. For example, if we have a tiddler called <<tid Preference>> whose text happens to be the word <<doc-field-value Vegetarian>>, we can say
|
||||
|
||||
```
|
||||
[tag{Preference}]
|
||||
```
|
||||
|
||||
as an alternative to `[tag[Vegetarian]]`. This allows the preference to change over time.
|
||||
|
||||
<<doc-def "Angle brackets">> `<>` mean that the parameter is the name of a [[variable|Variables]] whose value is to be used instead. Here we use the built-in <<doc-clink currentTiddler "WidgetVariable: currentTiddler">> variable in a filter that selects any tiddlers whose text contains the title of the current one:
|
||||
|
||||
```
|
||||
[search<currentTiddler>]
|
||||
```
|
||||
|
||||
(The built-in `currentTiddler` variable keeps track of which tiddler is the current one.)
|
||||
|
||||
! ORing Multiple Filter Steps
|
||||
|
||||
You can use multiple filter steps at once. If you write the steps separately, the overall result is the set of tiddlers that match //any// of the steps. Each step is processed separately, adding its tiddlers to the overall result.
|
||||
|
||||
This example selects all tiddlers that are either tagged ''introduction'' or ''demo'':
|
||||
|
||||
```
|
||||
[tag[introduction]] [tag[demo]]
|
||||
```
|
||||
|
||||
Here's an example that returns tiddlers tagged ''alpha'' or ''beta'' that are also tagged ''task'' but not tagged ''done'':
|
||||
|
||||
```
|
||||
[tag[alpha]] [tag[beta]] +[tag[task]!tag[done]]
|
||||
```
|
||||
|
||||
! ANDing Multiple Filter Steps
|
||||
|
||||
A sequence of steps can also be combined by bashing them together and merging the outer square brackets. This is called a "run". The result is the set of tiddlers that match //all// of the steps in the run.
|
||||
|
||||
For example, here we select tiddlers that are tagged ''introduction'' and also tagged ''demo'':
|
||||
|
||||
```
|
||||
[tag[introduction]tag[demo]]
|
||||
```
|
||||
|
||||
Here's another example that selects all tiddlers tagged ''introduction'' that are //not// tagged ''demo'':
|
||||
|
||||
```
|
||||
[tag[introduction]!tag[demo]]
|
||||
```
|
||||
|
||||
! Negating Runs
|
||||
|
||||
Ordinarily, each run //adds// to the accumulated results. Prefixing a run with `-` instead causes the list of tiddlers selected to be //removed// from the results. For example, this example returns all the tiddlers tagged ''introduction'', apart from `HelloThere` and `Title with Spaces`:
|
||||
|
||||
```
|
||||
[tag[introduction]] -HelloThere -[[Title with Spaces]]
|
||||
```
|
||||
|
||||
This example returns all tiddlers tagged ''introduction'' that are not also tagged ''demo'':
|
||||
|
||||
```
|
||||
[tag[introduction]] -[tag[demo]]
|
||||
```
|
||||
|
||||
! Working with Filter Results
|
||||
|
||||
Usually, each run takes the entire store of available tiddlers as its source. Prefixing a run with `+` causes the results so far accumulated to be used as the source instead.
|
||||
|
||||
For example, this filter selects tiddlers tagged ''introduction'' or ''demo'', and then sorts the resulting list by the `title` field:
|
||||
|
||||
```
|
||||
[tag[introduction]] [tag[demo]] +[sort[title]]
|
||||
```
|
||||
```
|
||||
140
editions/tw5.com/tiddlers/styleguide/Documentation Macros.tid
Normal file
140
editions/tw5.com/tiddlers/styleguide/Documentation Macros.tid
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
created: 20150110182600000
|
||||
title: Documentation Macros
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
The following macros are used throughout the documentation.
|
||||
|
||||
!General
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|doc-def |the defining instance of a term |<<doc-def widget>> |
|
||||
|doc-em |minor emphasis within a sentence |<<doc-em not>> |
|
||||
|doc-ph |a placeholder for the user to fill in |<<doc-ph tagname>> |
|
||||
|doc-strong |major emphasis within a tiddler |<<doc-strong Important!>> |
|
||||
|doc-w |a mention of an ordinary word or phrase |<<doc-w "hello world">> |
|
||||
|
||||
!Tiddlers and fields
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|doc-tiddler |a tiddler title|<<doc-tiddler Example>> |
|
||||
|doc-tag |a tag |<<doc-tag Example>> |
|
||||
|doc-field|a field name|<<doc-field example>> |
|
||||
|doc-field-value|a field value|<<doc-field-value "example value">> |
|
||||
|doc-var|a variable or macro name|<<doc-var currentTiddler>> |
|
||||
|doc-widget|a widget name|<<doc-widget list>> |
|
||||
|
||||
!Links
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|doc-link |a link containing WikiText |<<doc-link "^^an^^ ~~example~~" Example>> |
|
||||
|doc-clink |a code link |<<doc-clink `<$list>` ListWidget>> |
|
||||
|
||||
!User interface
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|doc-key |a key on the keyboard |<<doc-key Escape>> |
|
||||
|doc-key-combo |a key combination |<<doc-key-combo Ctrl Enter>> |
|
||||
|doc-input |text entered by the user |<<doc-input "npm install -g tiddlywiki">> |
|
||||
|doc-output |text output by the system |<<doc-output "Serving on 127.0.0.1:8080">> |
|
||||
|
||||
!Tabs
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|doc-sidebar-tab |the name of a sidebar tab |<<doc-sidebar-tab More>> |
|
||||
|doc-more-tab |the name of a subtab of the More tab |<<doc-more-tab Shadows>> |
|
||||
|doc-info-tab |the name of a tiddler info tab |<<doc-info-tab Fields>> |
|
||||
|doc-controlpanel-tab |the name of a Control Panel tab |<<doc-controlpanel-tab Settings>> |
|
||||
|doc-advancedsearch-tab |the name of an Advanced Search tab |<<doc-advancedsearch-tab Filter>> |
|
||||
|doc-toc-tab |name of the tw5.com TOC tab |<<doc-toc-tab>> |
|
||||
|doc-example-tab |an example tab name |<<doc-example-tab "Notes">> |
|
||||
|
||||
!!Parameters for doc-sidebar-tab
|
||||
|
||||
|Open |<<doc-sidebar-tab Open>> |
|
||||
|Recent |<<doc-sidebar-tab Recent>> |
|
||||
|Tools |<<doc-sidebar-tab Tools>> |
|
||||
|More |<<doc-sidebar-tab More>> |
|
||||
|
||||
!!Parameters for doc-more-tab
|
||||
|
||||
|All |<<doc-more-tab All>> |
|
||||
|Recent |<<doc-more-tab Recent>> |
|
||||
|Tags |<<doc-more-tab Tags>> |
|
||||
|Missing |<<doc-more-tab Missing>> |
|
||||
|Drafts |<<doc-more-tab Drafts>> |
|
||||
|Orphans |<<doc-more-tab Orphans>> |
|
||||
|Types |<<doc-more-tab Types>> |
|
||||
|System |<<doc-more-tab System>> |
|
||||
|Shadows |<<doc-more-tab Shadows>> |
|
||||
|
||||
!!Parameters for doc-info-tab
|
||||
|
||||
|Tools |<<doc-info-tab Tools>> |
|
||||
|References |<<doc-info-tab References>> |
|
||||
|Tagging |<<doc-info-tab Tagging>> |
|
||||
|List |<<doc-info-tab List>> |
|
||||
|Listed |<<doc-info-tab Listed>> |
|
||||
|Fields |<<doc-info-tab Fields>> |
|
||||
|Advanced |<<doc-info-tab Advanced>> |
|
||||
|
||||
!!Parameters for doc-controlpanel-tab
|
||||
|
||||
|Info |<<doc-controlpanel-tab Info>> |
|
||||
|Appearance |<<doc-controlpanel-tab Appearance>> |
|
||||
|Settings |<<doc-controlpanel-tab Settings>> |
|
||||
|Saving |<<doc-controlpanel-tab Saving>> |
|
||||
|Plugins |<<doc-controlpanel-tab Plugins>> |
|
||||
|
||||
!!Parameters for doc-advancedsearch-tab
|
||||
|
||||
|Standard |<<doc-advancedsearch-tab Standard>> |
|
||||
|System |<<doc-advancedsearch-tab System>> |
|
||||
|Shadows |<<doc-advancedsearch-tab Shadows>> |
|
||||
|Filter |<<doc-advancedsearch-tab Filter>> |
|
||||
|
||||
!Buttons
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|doc-button |a standard button name and icon |<<doc-button "new-tiddler">> |
|
||||
|
||||
!!Parameters for doc-button
|
||||
|
||||
!!!Tiddler toolbar
|
||||
|
||||
|clone |<<doc-button "clone">> |
|
||||
|close |<<doc-button "close">> |
|
||||
|close-others |<<doc-button "close-others">> |
|
||||
|edit |<<doc-button "edit">> |
|
||||
|export-tiddler |<<doc-button "export-tiddler">> |
|
||||
|info |<<doc-button "info">> |
|
||||
|more-tiddler-actions |<<doc-button "more-tiddler-actions">> |
|
||||
|new-here |<<doc-button "new-here">> |
|
||||
|new-journal-here |<<doc-button "new-journal-here">> |
|
||||
|permalink |<<doc-button "permalink">> |
|
||||
|
||||
!!!Edit-mode toolbar
|
||||
|
||||
|cancel |<<doc-button "cancel">> |
|
||||
|delete |<<doc-button "delete">> |
|
||||
|save |<<doc-button "save">> |
|
||||
|
||||
!!!Page toolbar
|
||||
|
||||
|advanced-search |<<doc-button "advanced-search">> |
|
||||
|close-all |<<doc-button "close-all">> |
|
||||
|control-panel |<<doc-button "control-panel">> |
|
||||
|encryption |<<doc-button "encryption">> |
|
||||
|export-page |<<doc-button "export-page">> |
|
||||
|full-screen |<<doc-button "full-screen">> |
|
||||
|home |<<doc-button "home">> |
|
||||
|import |<<doc-button "import">> |
|
||||
|language |<<doc-button "language">> |
|
||||
|more-page-actions |<<doc-button "more-page-actions">> |
|
||||
|new-journal |<<doc-button "new-journal">> |
|
||||
|new-tiddler |<<doc-button "new-tiddler">> |
|
||||
|permaview |<<doc-button "permaview">> |
|
||||
|refresh |<<doc-button "refresh">> |
|
||||
|save-wiki |<<doc-button "save-wiki">> |
|
||||
|storyview |<<doc-button "storyview">> |
|
||||
|tag-manager |<<doc-button "tag-manager">> |
|
||||
|theme |<<doc-button "theme">> |
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
created: 20140904164608166
|
||||
modified: 20140904164935351
|
||||
modified: 20150110181800000
|
||||
title: Documentation Style Guide
|
||||
tags: documenting [[Improving TiddlyWiki Documentation]]
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
The documentation for ~TiddlyWiki tries to follow a consistent editorial style. It has two main areas, each with its own tone and audience:
|
||||
|
|
@ -9,10 +9,13 @@ The documentation for ~TiddlyWiki tries to follow a consistent editorial style.
|
|||
* [[Instruction Tiddlers]]
|
||||
* [[Reference Tiddlers]]
|
||||
|
||||
Keep the two areas distinct, otherwise beginners will be overwhelmed and experts will be denied quick access to information.
|
||||
We keep the two areas distinct. This avoids overwhelming relative newcomers, while still providing quick access to the information that expert users need.
|
||||
|
||||
* [[Tiddler Titles]]
|
||||
Additional topics:
|
||||
|
||||
* [[Tiddler Title Policy]]
|
||||
* [[Tiddler Structure]]
|
||||
* [[Spelling]]
|
||||
* [[Typography]]
|
||||
* [[Technical Prose Style]]
|
||||
* [[Documentation Macros]]
|
||||
* [[Technical Prose Style]]
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
created: 20150110101500000
|
||||
modified: 20150110181800000
|
||||
title: Instruction Tiddlers
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
<<doc-def "Instruction tiddlers">> talk directly to the reader and guide them through a process. The reader is likely to be a beginner or an intermediate user.
|
||||
|
||||
Such tiddlers can be subcategorised as:
|
||||
|
||||
;Welcome
|
||||
* What is ~TiddlyWiki and why should I care?
|
||||
* Demonstrations of key features and benefits
|
||||
* Frequently asked questions
|
||||
* Examples of ~TiddlyWiki in the field
|
||||
* Information about the project itself
|
||||
|
||||
;Tutorial
|
||||
* An ordered presentation of material for beginners
|
||||
* Each tiddler introduces one new point or concept
|
||||
* Its main content contains very few links
|
||||
* A revealable <<doc-w "Find out more">> section at the end can offer related links
|
||||
|
||||
;Exercise
|
||||
* Accompanying a tutorial tiddler
|
||||
* Solution revealed on demand
|
||||
|
||||
;How-to
|
||||
* A list of numbered steps for performing a small specific task
|
||||
* Concise, with links to reference tiddlers where appropriate
|
||||
* Often has a preamble to clarify the nature of the task
|
||||
|
||||
;Example
|
||||
* Accompanying a [[reference tiddler|Reference Tiddlers]]
|
||||
* Can contain explanations and similar commentary
|
||||
* Kept separate to keep the reference tiddler pure
|
||||
|
||||
Instruction tiddlers talk directly to the reader as <<doc-w you>>. They can be reasonably chatty.
|
||||
|
||||
But they avoid excessively colloquial language, cultural or topical references and attempts at humour, as these can baffle or even offend the international readership. They also avoid potentially frustrating the reader with descriptions of features as <<doc-w convenient>> or <<doc-w easy>>.
|
||||
26
editions/tw5.com/tiddlers/styleguide/Reference Tiddlers.tid
Normal file
26
editions/tw5.com/tiddlers/styleguide/Reference Tiddlers.tid
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
created: 20141226192500000
|
||||
modified: 20150110182100000
|
||||
title: Reference Tiddlers
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
<<doc-def "Reference tiddlers">> offer raw information in a comprehensive interlinked way. The reader is likely to be an intermediate or expert user.
|
||||
|
||||
There are several subcategories:
|
||||
|
||||
;Concepts
|
||||
* With definitions, together forming a glossary
|
||||
|
||||
;User manual
|
||||
* Presenting technical details of ~WikiText features
|
||||
* Subcategorised: messages, operators, widgets, etc
|
||||
|
||||
;Developer manual
|
||||
* Presenting technical details of ~TiddlyWiki's internal architecture
|
||||
|
||||
Reference material is written in a terse, formal style that avoids referring to the reader, and instead focuses on how ~TiddlyWiki itself behaves. The passive voice is often suitable:
|
||||
|
||||
* <<doc-w "the template is specified as a tiddler">> rather than <<doc-w "specify the template as a tiddler">>
|
||||
* <<doc-w "the widget can be used for various purposes">> rather than <<doc-w "you can use the widget for various purposes">>
|
||||
* But <<doc-w "this widget has several possible uses">> is better, because it is less convoluted and more succinct
|
||||
|
||||
Most contracted verb forms are avoided in reference tiddlers. But those ending in <<doc-w "n't">> (<<doc-w "aren't">>, <<doc-w "doesn't">>, <<doc-w "hasn't">>, <<doc-w "isn't">>, etc) are acceptable, as they make it less easy to accidentally overlook the word <<doc-w not>>.
|
||||
|
|
@ -1,12 +1,12 @@
|
|||
created: 20141226192500000
|
||||
created: 20150110182900000
|
||||
title: Spelling
|
||||
tags: documenting
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
Because ~TiddlyWiki is of British origin, its English documentation uses [[British spelling in preference to US spelling|http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences]].
|
||||
|
||||
Words like "customise" are spelled "-ise", not "-ize".
|
||||
Words like <<doc-w customise>> are spelled <<doc-w -ise>>, not <<doc-w -ize>>.
|
||||
|
||||
Standard technical acronyms are written in upper case, without dots: `HTML`, not `html` or `H.T.M.L.`
|
||||
Standard technical acronyms are written in upper case, without dots: <<doc-w HTML>>, not <<doc-w html>> or <<doc-w H.T.M.L.>>
|
||||
|
||||
Avoid arbitrarily abbreviating words and sentences. But the following abbreviations are acceptable:
|
||||
|
||||
|
|
@ -1,14 +1,14 @@
|
|||
created: 20141226192500000
|
||||
created: 20150110182900000
|
||||
title: Technical Prose Style
|
||||
tags: documenting
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
When writing an [[Instruction Tiddler|Instruction Tiddlers]], start by planning a route through the information you wish to present. This should be a simple, logical, direct progression of thoughts, with no backtracking or forward references. Use this approach even within individual sentences: always proceed from cause to effect, from the old or known to the new or unknown.
|
||||
When writing an [[instruction tiddler|Instruction Tiddlers]], start by planning a route through the information you wish to present. This should be a simple, logical, direct progression of thoughts, with no backtracking or forward references. Use this approach even within individual sentences: always proceed from cause to effect, from the old or known to the new or unknown.
|
||||
|
||||
Keep sentences short and simple. A clear technical sentence seldom contains more than one idea. It therefore avoids parenthetical information. Similarly, keep paragraph structure simple. A flat presentation is often easier to understand than a hierarchical one.
|
||||
|
||||
It is often possible to simplify a sentence without changing its meaning merely by adjusting its vocabulary. "Execution of the macro is performed" just means "The macro runs". "Your expectation might be..." just means "You might expect..."
|
||||
It is often possible to simplify a sentence without changing its meaning merely by adjusting its vocabulary. <<doc-w "Execution of the macro is performed">> just means <<doc-w "The macro runs">>. <<doc-w "Your expectation might be...">> just means <<doc-w "You might expect...">>.
|
||||
|
||||
Prefer the active voice by default: "Jane creates a tiddler" rather than "a tiddler is created by Jane". The passive voice can be useful if you want the reader to focus on the action itself or its result: "a tiddler is created". But it may be clearer to proceed from cause to effect and say "this creates a tiddler" in the active voice.
|
||||
Prefer the active voice by default: <<doc-w "Jane creates a tiddler">> rather than <<doc-w "a tiddler is created by Jane">>. The passive voice can be useful if you want the reader to focus on the action itself or its result: <<doc-w "a tiddler is created">>. But it may be clearer to proceed from cause to effect and say <<doc-w "this creates a tiddler">> in the active voice.
|
||||
|
||||
Documentation often presents two items that are parallel either by similarity or by difference. The reader will more easily detect such a pattern if you use the same sentence or phrase structure for both. But this must be balanced with the need to avoid monotony.
|
||||
|
||||
|
|
@ -1,15 +1,15 @@
|
|||
created: 20141226192500000
|
||||
created: 20150110183300000
|
||||
title: Tiddler Structure
|
||||
tags: documenting
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
In accordance with the [[Philosophy of Tiddlers]], documentation tiddlers are typically short and interlinked.
|
||||
|
||||
When a tiddler seems as if it needs to contain subheadings, this is often a sign that it should in fact be split into several tiddlers. But it is reasonable for a [[Reference Tiddler|Reference Tiddlers]] to consist of an untitled introductory section followed by a titled section of details.
|
||||
When a tiddler seems as if it needs to contain subheadings, this is often a sign that it should in fact be split into several tiddlers. But it is reasonable for a [[reference tiddler|Reference Tiddlers]] to consist of an untitled introductory section followed by a titled section of details.
|
||||
|
||||
Consistency of terminology is essential if the reader is not to become confused. Consistent typography and punctuation lend a professional quality to the documentation. Macros can improve the consistency and maintainability of the text.
|
||||
|
||||
Use numbered lists for step-by-step instructions, and bullet points for lists whose order is arbitrary. Use a definition list in preference to a bulleted list if each bulleted item would begin with a term and a colon. If at all possible, avoid burdening the reader with a nested list.
|
||||
|
||||
Use a table when information naturally falls into three or more columns, and also for lists of parameters, attributes, etc in [[Reference Tiddlers]].
|
||||
Use a table when information naturally falls into three or more columns, and also for lists of parameters, attributes, etc in [[reference tiddlers|Reference Tiddlers]].
|
||||
|
||||
The documentation describes the current reality of ~TiddlyWiki. Avoid discussing future aspirations.
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
created: 20150110183300000
|
||||
modified: 20150110190400000
|
||||
title: Tiddler Title Policy
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
Many documentation tiddlers, especially the [[reference ones|Reference Tiddlers]], are concerned with a single concept. Their titles should be succinct noun phrases like <<doc-tiddler "List Widget">> or <<doc-tiddler "Tiddler Fields">>.
|
||||
|
||||
Each of the main words of such a title begins with a capital letter. Minor words such as <<doc-w and>>, <<doc-w or>>, <<doc-w the>>, <<doc-w to>> and <<doc-w with>> do not.
|
||||
|
||||
Tags also follow this pattern.
|
||||
|
||||
Titles of this kind are plural if they denote a category of items, e.g. <<doc-tiddler "Keyboard Shortcuts">> or <<doc-tiddler "Tiddler Fields">>. Such titles are used to tag more specific tiddlers within the category.
|
||||
|
||||
Where a concept is an item rather than a category, its tiddler has a singular title, e.g. <<doc-tiddler "List Widget">>, <<doc-tiddler "Tag Operator">>.
|
||||
|
||||
Avoid starting a title with the word <<doc-w the>>.
|
||||
|
||||
In the past, many tiddlers had CamelCase titles. This is gradually being phased out of the documentation to improve readability. ~CamelCase titles should no longer be used, even for tags, except in cases like <<doc-tiddler ~JavaScript>> where that is the standard spelling.
|
||||
|
||||
[[Instruction tiddlers|Instruction Tiddlers]] often have longer titles that can be more complicated than just a noun phrase, e.g. <<doc-tiddler "Ten reasons to switch to ~TiddlyWiki">> These titles use sentence case, i.e. only the first word (and any proper names) starts with a capital letter.
|
||||
|
||||
How-to tiddlers have titles that begin with <<doc-w "How to">>, e.g. <<doc-tiddler "How to edit a tiddler">>. Avoid titles like <<doc-tiddler "Editing tiddlers">>, because a less fluent English speaker could misunderstand that as the name of a category of tiddlers.
|
||||
19
editions/tw5.com/tiddlers/styleguide/Typography.tid
Normal file
19
editions/tw5.com/tiddlers/styleguide/Typography.tid
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
created: 20141226192500000
|
||||
title: Typography
|
||||
tags: documenting
|
||||
|
||||
Use the [[documentation macros|Documentation Macros]] to keep the text maintainable in the face of change.
|
||||
|
||||
Be wary of arbitrarily applying raw bold or italic markup in a sentence. If there's a suitable macro, use that instead. If there isn't a suitable macro, write one or request one.
|
||||
|
||||
Use simple backticks (<code>`...`</code>) for fragments of WikiText.
|
||||
|
||||
To keep things clean and simple, quotation marks and apostrophes should be straight `'`, not curly `’`, and the ellipsis should be three separate dots `...` rather than `…`.
|
||||
|
||||
Use `"` as the primary quotation mark, reserving `'` for the rare case of a nested quotation.
|
||||
|
||||
Avoid using a single hyphen `-` as sentence punctuation. Instead, use a double hyphen -- which ~TiddlyWiki renders as an en-dash -- with a space on either side.
|
||||
|
||||
Items in lists and tables should only end with a full stop (period in US English) if they are complete sentences. They should have no trailing punctuation otherwise.
|
||||
|
||||
It is very rarely necessary to use an exclamation mark in professional documentation.
|
||||
38
editions/tw5.com/tiddlers/system/doc-macros.tid
Normal file
38
editions/tw5.com/tiddlers/system/doc-macros.tid
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
title: $:/editions/tw5.com/doc-macros
|
||||
tags: $:/tags/Macro
|
||||
|
||||
\define doc-if(cond,then,else) <$reveal type="nomatch" default="$cond$" text="">$then$</$reveal><$reveal type="match" default="$cond$" text="">$else$</$reveal>
|
||||
|
||||
\define doc-def(_) <dfn class="doc-def">$_$</dfn>
|
||||
\define doc-em(_) <em class="doc-em">$_$</em>
|
||||
\define doc-strong(_) <strong class="doc-strong">$_$</strong>
|
||||
\define doc-ph(_) <var class="doc-ph">$_$</var>
|
||||
\define doc-w(_) "$_$"
|
||||
|
||||
\define doc-tiddler(_) <code class="doc-tiddler">$_$</code>
|
||||
\define doc-tag(_) <code class="doc-tag">$_$</code>
|
||||
\define doc-field(_) <code class="doc-field">$_$</code>
|
||||
\define doc-field-value(_) <code class="doc-field-value">$_$</code>
|
||||
\define doc-var(_) <code class="doc-var">$_$</code>
|
||||
\define doc-widget(_) <code class="doc-widget">$_$</code>
|
||||
|
||||
\define doc-link(_,to) <$link to="$to$">$_$</$link>
|
||||
\define doc-clink(_,to) <span class="doc-clink"><<doc-link """$_$""" "$to$">></span>
|
||||
|
||||
\define doc-key(_) <span class="doc-key">$_$</span>
|
||||
\define doc-combo-key(_) <$macrocall $name="doc-if" cond="$_$" then="<<doc-key '$_$'>>"/>
|
||||
\define doc-key-combo(1,2,3,4) <<doc-combo-key "$1$">><<doc-if "$2$" +>><<doc-combo-key "$2$">><<doc-if "$3$" +>><<doc-combo-key "$3$">><<doc-if "$4$" +>><<doc-combo-key "$4$">>
|
||||
|
||||
\define doc-input(_) `$_$`
|
||||
\define doc-output(_) `$_$`
|
||||
|
||||
\define doc-tab(_) <span class="doc-tab">{{$_$!!caption}}</span>
|
||||
\define doc-sidebar-tab(_) <<doc-tab "$:/core/ui/SideBar/$_$">>
|
||||
\define doc-more-tab(_) <<doc-tab "$:/core/ui/MoreSideBar/$_$">>
|
||||
\define doc-info-tab(_) <<doc-tab "$:/core/ui/TiddlerInfo/$_$">>
|
||||
\define doc-controlpanel-tab(_) <<doc-tab "$:/core/ui/ControlPanel/$_$">>
|
||||
\define doc-advancedsearch-tab(_) <<doc-tab "$:/core/ui/AdvancedSearch/$_$">>
|
||||
\define doc-toc-tab() <<doc-tab "TableOfContents">>
|
||||
\define doc-example-tab(_) <span class="doc-tab">$_$</span>
|
||||
|
||||
\define doc-button(_) <span class="doc-button">{{$:/core/ui/Buttons/$_$!!caption}}</span>
|
||||
57
editions/tw5.com/tiddlers/system/doc-styles.tid
Normal file
57
editions/tw5.com/tiddlers/system/doc-styles.tid
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
title: $:/editions/tw5.com/doc-styles
|
||||
tags: $:/tags/Stylesheet
|
||||
|
||||
.doc-def {
|
||||
font-style: normal;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.doc-em {
|
||||
font-style: italic;
|
||||
font-variant: small-caps;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.doc-strong {
|
||||
color: <<colour alert-highlight>>;
|
||||
font-style: normal;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.doc-foreign {
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
.doc-ph {
|
||||
border: none;
|
||||
color: <<color foreground>>;
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
.doc-button,
|
||||
.doc-tab,
|
||||
.doc-tag,
|
||||
.doc-tiddler,
|
||||
.doc-field,
|
||||
.doc-field-value,
|
||||
.doc-var,
|
||||
.doc-widget {
|
||||
background: <<color background>>;
|
||||
border: none;
|
||||
color: <<color very-muted-foreground>>;
|
||||
font-weight: bold;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.doc-button svg {
|
||||
height: 1em;
|
||||
}
|
||||
|
||||
.doc-key {
|
||||
color: <<color very-muted-foreground>>;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.doc-clink code {
|
||||
color: <<colour tiddler-link-foreground>>;
|
||||
}
|
||||
|
|
@ -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.tid
Normal file
91
editions/tw5.com/tiddlers/variables/IteratorVariables.tid
Normal 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>
|
||||
<<<
|
||||
|
|
@ -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.
|
||||
|
|
@ -24,13 +24,13 @@ Variables are defined by...
|
|||
|
||||
!!Using Variables
|
||||
|
||||
Variables are used via...
|
||||
Variables are used...
|
||||
|
||||
; shorthand
|
||||
; via shorthand
|
||||
:`<<variableName>>`
|
||||
; variable substitution within [[macros|Macros]]
|
||||
; via variable substitution within [[macros|Macros]]
|
||||
:`$(variableName)$`
|
||||
; as variable operands in [[filter expressions|Introduction to Filters]]
|
||||
; as parameters to [[filter steps|Filters]]
|
||||
: `[operator<variableName>]`
|
||||
; in [[widgets|Widgets]]
|
||||
: internally, or as widget attributes
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ To edit an existing tiddler, click the {{$:/core/images/edit-button}} button at
|
|||
When you create a new tiddler or edit an existing one, the tiddler will go into draft mode. This presents a control panel for modifying the tiddler in various ways. It has several parts, from top to bottom:
|
||||
|
||||
*''The title field'' - Use this to change the title of the tiddler
|
||||
*''The tag selector'' - Use this to add or remove tags. As you type a tag name in the box, a dropdown list will show you any existing tags that match. You can pick from this list or create a completely new tag. Then click the ''add'' button to add the tag to the tiddler. Each tag is shown as a coloured pill. Clikc the "×" on a pill to remove that tag
|
||||
*''The tag selector'' - Use this to add or remove tags. As you type a tag name in the box, a dropdown list will show you any existing tags that match. You can pick from this list or create a completely new tag. Then click the ''add'' button to add the tag to the tiddler. Each tag is shown as a coloured pill. Click the "×" on a pill to remove that tag
|
||||
*''The text area'' - Use this to edit the main content of the tiddler. Click the ''show preview'' button to see what your changes will look like
|
||||
*''The type selector'' - Use this when a tiddler needs to be displayed in a special way, such as an image. See ContentType for a list of the options. The default is `text/vnd.tiddlywiki`, which means the tiddler contains WikiText
|
||||
*''The field selector'' - Use this to add or remove fields on the tiddler. For example, if you are editing a tiddler that's being used to tag other tiddlers, you can add a [[''list'' field|ListField]] to change the order in which those tiddlers will be listed
|
||||
|
|
|
|||
|
|
@ -204,3 +204,5 @@ Evgeniy Gryaznov, @evgeniy-gryaznov, 2014/12/23
|
|||
Andrew Harrison, @infurnoape, 2014/12/27
|
||||
|
||||
Arlen Beiler, @arlen22, 2014/12/30
|
||||
|
||||
David P Dannemiller, @dpdannemiller, 2015/01/10
|
||||
|
|
|
|||
|
|
@ -74,7 +74,7 @@ RailroadWidget.prototype.renderSvg = function(parser,div) {
|
|||
|
||||
RailroadWidget.prototype.patchLinks = function(node) {
|
||||
var self = this;
|
||||
if(node.hasChildNodes()) {
|
||||
if(!$tw.node && node.hasChildNodes()) {
|
||||
var children = node.childNodes;
|
||||
for(var i=0; i<children.length; i++) {
|
||||
var child = children[i];
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user