From d4a571ae79d2aba1a679223bef7c4d32d94c403f Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Tue, 20 Aug 2013 15:18:15 +0100 Subject: [PATCH] Docs updates --- editions/tw5.com/tiddlers/Docs.tid | 1 + .../tiddlers/concepts/SystemTiddlers.tid | 4 +- .../tiddlers/concepts/TextReference.tid | 6 +-- .../tiddlers/concepts/TiddlerFilters.tid | 10 +++- .../tiddlers/mechanisms/DraftMechanism.tid | 16 ++++++ editions/tw5.com/tiddlers/roadmap/RoadMap.tid | 4 +- .../tw5.com/tiddlers/widgets/ListWidget.tid | 50 +++++++++++++++++-- 7 files changed, 78 insertions(+), 13 deletions(-) create mode 100644 editions/tw5.com/tiddlers/mechanisms/DraftMechanism.tid diff --git a/editions/tw5.com/tiddlers/Docs.tid b/editions/tw5.com/tiddlers/Docs.tid index a540c3df7..9f62cb93a 100644 --- a/editions/tw5.com/tiddlers/Docs.tid +++ b/editions/tw5.com/tiddlers/Docs.tid @@ -1,4 +1,5 @@ title: Docs +modified: 201308201324 tags: docs introduction This is the main documentation hub for TiddlyWiki. See also the DeveloperDocs. diff --git a/editions/tw5.com/tiddlers/concepts/SystemTiddlers.tid b/editions/tw5.com/tiddlers/concepts/SystemTiddlers.tid index 37d2f41b8..2b36b333d 100644 --- a/editions/tw5.com/tiddlers/concepts/SystemTiddlers.tid +++ b/editions/tw5.com/tiddlers/concepts/SystemTiddlers.tid @@ -1,9 +1,9 @@ title: SystemTiddlers tags: docs concepts -TiddlyWiki models everything as [[tiddlers|Tiddlers]], including its internal components and configuration. +System tiddlers are any tiddler whose title starts with `$:/`; such tiddlers are automatically hidden from most operations. They don't show up in lists or search results, but linking to one directly works in the usual way. -Thus, even an apparently empty TiddlyWiki actually contains dozens of tiddlers that are necessary to enable it function correctly. To prevent them from confusing casual users, these system tiddlers are hidden from most operations. They don't show up in lists or search results, but linking to one directly works in the usual way. +TiddlyWiki models everything as [[tiddlers|Tiddlers]], including its internal components and configuration. Thus, even an apparently empty TiddlyWiki actually contains dozens of tiddlers that are necessary to enable it function correctly. Using system tiddlers prevents them from confusing casual users. The current system tiddlers are: diff --git a/editions/tw5.com/tiddlers/concepts/TextReference.tid b/editions/tw5.com/tiddlers/concepts/TextReference.tid index 13c0f5eae..f4100615f 100644 --- a/editions/tw5.com/tiddlers/concepts/TextReference.tid +++ b/editions/tw5.com/tiddlers/concepts/TextReference.tid @@ -5,7 +5,7 @@ A TextReference identifies a chunk of text from a tiddler that can be retrieved TextReferences are made up of several parts, most of which can be optional: -* `` - the text field of the specified tiddler -* `!!` - a tiddler metadata field (eg, `modified`, `modifier`, `type` etc) -* `!!` - a metadata field of the current tiddler +* `` - the text [[field|TiddlerFields]] of the specified tiddler +* `!!` - a tiddler metadata [[field|TiddlerFields]] (eg, `modified`, `modifier`, `type` etc) +* `!!` - a metadata [[field|TiddlerFields]] of the current tiddler * `##` - extracts a named property from DataTiddlers diff --git a/editions/tw5.com/tiddlers/concepts/TiddlerFilters.tid b/editions/tw5.com/tiddlers/concepts/TiddlerFilters.tid index 5a24b71b0..247e560cf 100644 --- a/editions/tw5.com/tiddlers/concepts/TiddlerFilters.tid +++ b/editions/tw5.com/tiddlers/concepts/TiddlerFilters.tid @@ -1,6 +1,6 @@ tags: docs concepts title: TiddlerFilters -modified: 201305311232 +modified: 201308201405 Filters are used in TiddlyWiki to choose tiddlers by specifying simple match criteria. @@ -43,7 +43,13 @@ A filter string consists of one or more runs of filter operators that each look * ''tagging'': selects the tiddlers tagged with the currently selected tiddlers * ''links'': selects the outgoing links on the currently selected tiddlers * ''backlinks'': selects the tiddlers that link to the currently selected tiddlers -* ''list'': selects the tiddlers listed in a specified tiddler (newline delimited) +* ''list'': selects the tiddlers listed in a specified [[TiddlerList|TiddlerLists]] +* ''listed'': selects the TiddlerLists that include the current tiddler +* ''each'': selects one tiddler for each discrete value of the specified field +* ''eachday'': selects one tiddler for each discrete day in the specified date field +* ''sameday'': selects all the tiddlers falling into the same day as the provided date in the specified date field +* ''fields'': returns the names of the fields present on the selected tiddlers +* ''search'': returns all tiddlers that contain the specified text An operator can be negated with by preceding it with `!`, for example `[!tag[Tommy]]` selects the tiddlers that are not tagged with `Tommy`. diff --git a/editions/tw5.com/tiddlers/mechanisms/DraftMechanism.tid b/editions/tw5.com/tiddlers/mechanisms/DraftMechanism.tid new file mode 100644 index 000000000..29f42b0a7 --- /dev/null +++ b/editions/tw5.com/tiddlers/mechanisms/DraftMechanism.tid @@ -0,0 +1,16 @@ +title: DraftMechanism +modified: 201308201324 +tags: mechanism docs + +Tiddlers that have a `draft.of` field are treated as pending drafts of the tiddler specified in the field. Draft tiddlers should also have a `draft.title` field that specifies the title that will be given to the tiddler when it is saved. + +Several features work in concert to give the desired behaviour for draft tiddlers: + +* The ListWidget can optionally render draft tiddlers through a different template +* The NavigatorWidget incorporates handlers for the following events: +** `tw-new-tiddler` for creating a new tiddler in draft mode +** `tw-edit-tiddler` for moving a tiddler into edit mode +** `tw-cancel-tiddler` for cancelling a tiddler out of edit mode +** `tw-save-tiddler` for saving a draft tiddler +* Draft tiddlers are automatically excluded from search operations + diff --git a/editions/tw5.com/tiddlers/roadmap/RoadMap.tid b/editions/tw5.com/tiddlers/roadmap/RoadMap.tid index 9dd7bc0cb..a39524846 100644 --- a/editions/tw5.com/tiddlers/roadmap/RoadMap.tid +++ b/editions/tw5.com/tiddlers/roadmap/RoadMap.tid @@ -1,4 +1,4 @@ -modified: 201308141511 +modified: 201308201324 title: RoadMap modifier: JeremyRuston tags: docs planning @@ -35,6 +35,8 @@ The following additional features are under consideration for implementation dur * Built in JavaScript syntax highlighting * Syntax highlighter plugin * Minification of plugins (JS and CSS) +* List editor with drag and drop +* Selective/weighted searching by title, body and fields ! 5.0 Release diff --git a/editions/tw5.com/tiddlers/widgets/ListWidget.tid b/editions/tw5.com/tiddlers/widgets/ListWidget.tid index 9781c1814..68b2d18ae 100644 --- a/editions/tw5.com/tiddlers/widgets/ListWidget.tid +++ b/editions/tw5.com/tiddlers/widgets/ListWidget.tid @@ -1,5 +1,5 @@ title: ListWidget -modified: 201308131914 +modified: 201308201324 tags: widget \define demoMacro(title) @@ -18,7 +18,7 @@ The tiddlers can either be displayed by transcluding each in turn through an opt ! Content and Attributes -The content of the `<$list>` widget is the optional template to use for rendering each tiddler in the list. +The content of the `<$list>` widget is the 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). |!Attribute |!Description | |type |Determines the HTML elements generated for the list: ''plain'', ''ul'' or ''ol'' | @@ -28,21 +28,30 @@ The content of the `<$list>` widget is the optional template to use for renderin |emptyMessage |Message to be displayed when the list is empty | |class |Class to be applied to the list frame element| |itemClass |Class to be applied to the list member elements | -|macro |Specifies a macro to use for rendering each tiddler | +|macro |Specifies an optional macro to use for rendering each tiddler | |listview |Optional name of module responsible for animating/processing the list | |history |The title of the tiddler containing the navigation history | !! Handling edit mode +The `<$list>` widget can optionally render draft tiddlers through a different tiddler than ordinary tiddlers -- see DraftMechanism for a discussion of how this capability is used. + !! `listview` attribute +The `listview` attribute gives the specifies the name of an optional module that can animate changes to the list (including navigation). The core ships with the following listview 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 + !! 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 -!! Using the list widget with the `macro` attribute +!! Using the `macro` attribute -Example of using the list widget with the macro attribute: +Example of using the `<$list>` widget with the macro attribute: ``` <$list filter="[tag[introduction]]" macro="demoMacro"/> @@ -51,3 +60,34 @@ Example of using the list widget with the macro attribute: Renders as: <$list filter="[tag[introduction]]" macro="demoMacro"/> + +!! 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]]"> +<$view field="type" default="untyped"/> +<$list filter="[type{!!type}!is[system]sort[title]]"> +<$view field="title" format="link"/> + + +``` + +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]]" itemClass="tw-menu-list-item"> +<$view field="modified" format="date" template="DDth MMM YYYY"/> +<$list filter="[sameday{!!modified}!is[system]!sort[modified]]" itemClass="tw-menu-list-subitem"> +<$view field="title" format="link"/> + + +``` + +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. +