mirrors/TiddlyWiki5
1
0
Fork 0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2025-12-25 17:56:04 +00:00
Code Issues Releases Wiki Activity

Merge branch 'tiddlywiki-com'

Browse Source
This commit is contained in:
Jeremy Ruston
2025-10-29 14:48:14 +00:00
parent 485051951e bad87c405e
commit 5848d66e96
12 changed files with 166 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
editions/dev/tiddlers/How to Create a Custom Cascade Entry.tid Normal file
View File

@@ -0,0 +1,127 @@
created: 20240802065815656
modified: 20240802065836064
title: How to Create a Custom Cascade Entry
type: text/vnd.tiddlywiki
This guide explains how to add a new [[cascade|https://tiddlywiki.com/#Cascades]] to the ~TiddlyWiki core or your own plugins. This allows third-party plugins to extend the functionality of the core or your plugin.
!! How Cascade Works in the Core
This section explains how the existing WikiText in the core interacts with the new WikiText you’ll add, only for learning purpose. You don’t need to modify the core WikiText when adding a new cascade.
!!! The Default Template as a Fallback
The default behavior in ~TiddlyWiki is defined by [[$:/core/ui/ViewTemplate/tags/default]].
<pre>
<$view tiddler="$:/core" subtiddler="$:/core/ui/ViewTemplate/tags/default" mode=block format=text/>
</pre>
!!! Transclusion of the Active Template
[[$:/core/ui/ViewTemplate/tags]] uses a filter expression to find the cascade filter and the view template you’ll add.
<pre>
<$view tiddler="$:/core" subtiddler="$:/core/ui/ViewTemplate/tags" mode=block format=text/>
</pre>
The `:cascade` clause collects all tiddlers it finds and uses their filter text sequentially. Most filters won’t return any text and will be skipped. The first filter that returns a tiddler title becomes the result of the `:cascade` clause. If no filters return a result, the fallback default filter will be used.
The `:and[!is[blank]else` clause provides additional fallback protection, though it’s often redundant because a fallback is typically tagged with `$:/tags/ViewTemplateTagsFilter`. However, including fallbacks is a good practice for defensive programming.
!! Adding a New Cascade Entry
This section contains the WikiText you’ll need to add to the core. Modify it to suit your needs instead of copying it directly.
!!! Creating a Control Panel Tab
To create a new tab under [[ControlPanel|$:/ControlPanel]] → Advanced → [[Cascade|$:/core/ui/ControlPanel/Cascades]], use the following code:
[[$:/core/ui/ControlPanel/ViewTemplateTags]] uses a filter expression to find the cascade filter and the view template you’ll add.
<pre>
<$view tiddler="$:/core" subtiddler="$:/core/ui/ControlPanel/ViewTemplateTags" mode=block format=text/>
</pre>
Add the following metadata:
```tid
tags: $:/tags/ControlPanel/Cascades
caption: {{$:/language/ControlPanel/ViewTemplateTags/Caption}}
```
!!! Adding a New Language Entry
It’s important to add related language files. Create a file starting with `title: $:/language/ControlPanel/`:
```multid
title: $:/language/ControlPanel/
ViewTemplateTags/Caption: View Template Tags
ViewTemplateTags/Hint: This rule cascade is used by the default view template to dynamically choose the template for displaying the tags area of a tiddler.
```
!!! Adding Default Configuration
Similar to the language file, add a config file starting with `title: $:/config/ViewTemplateTagsFilters/`. For example:
```tid
title: $:/config/ViewTemplateTagsFilters/
tags: $:/tags/ViewTemplateTagsFilter
default: [[$:/core/ui/ViewTemplate/tags/default]]
```
Different templates may have their own config files. Ensure you’re adding to the correct file or creating a new one if it doesn’t exist.
!! Using the New Cascade
This section provides a simplified example based on a real-world use case. It demonstrates how to override the default template with a custom template.
!!! Your Template
Add the content you want to display conditionally. Update `publisher/plugin-name` to your plugin’s name.
```tid
code-body: yes
title: $:/plugins/publisher/plugin-name/EditMode
\whitespace trim
<$reveal type="nomatch" stateTitle=<<folded-state>> text="hide" tag="div" retain="yes" animate="yes">
<div class="tc-tags-wrapper" style="display:flex">
<$transclude tiddler="$:/core/ui/EditTemplate/tags"/>
<$button class="tc-btn-invisible" style="margin-left:1em;">
{{$:/core/images/done-button}}
<$action-deletetiddler $tiddler={{{ [[$:/state/edit-view-mode-tags/]addsuffix<storyTiddler>] }}}/>
</$button>
</div>
</$reveal>
```
!!! The Condition
Write a filter that ends with `then[$:/plugins/publisher/plugin-name/EditMode]`.
```tid
code-body: yes
tags: $:/tags/ViewTemplateTagsFilter
title: $:/plugins/publisher/plugin-name/CascadeEditMode
list-before: $:/config/ViewTemplateTagsFilters/default
[[$:/state/edit-view-mode-tags/]addsuffix<currentTiddler>get[text]compare:string:eq[yes]then[$:/plugins/publisher/plugin-name/EditMode]]
```
!!! A Button to Trigger the Condition
```tid
code-body: yes
tags: $:/tags/ViewTemplate/Tags
title: $:/plugins/publisher/plugin-name/TriggerEdit
\whitespace trim
<%if [<storyTiddler>get[tags]!is[blank]] %>
<$button class="tc-btn-invisible" set={{{ [[$:/state/edit-view-mode-tags/]addsuffix<storyTiddler>] }}} setTo="yes" tooltip="add tags">
{{$:/core/images/new-here-button}}
</$button>
<%endif%>
```

6
editions/dev/tiddlers/from Heigele and Jurke/RootWidget and Rendering Startup.tid
View File

@@ -1,9 +1,10 @@
chapter.of: UI and Rendering Pipeline
created: 20140717175203036
modified: 20140717182314488
modified: 20240802065804331
sub.num: 5
tags: doc
title: RootWidget and Rendering Startup
type: text/vnd.tiddlywiki
The previous parts of this chapter showed how WikiText is transformed to DOM nodes which dynamically react to tiddler changes and a way to compose tiddlers from other tiddlers.
This last part describes how the TiddlyWiki core plug-in starts up a UI build from tiddlers and WikiText.
@@ -29,6 +30,9 @@ and a listener is registered at the store which executes the refresh function of
[[Techniques for including other tiddlers and Templates|Transclusion and TextReference]] are finally used in [[$:/core/ui/PageTemplate]] to build the TiddlyWiki UI only from tiddlers written in WikiText (with widgets implemented in javascript):
For example to implement the list of open wiki pages the [[$:/core/ui/PageTemplate]] contains a [[navigator widget|$:/core/modules/widgets/navigator.js]] which maintains a list of open tiddlers in a field of [[$:/StoryList]] and handles events like ``tm-navigate`` by adding a tiddler specified as parameter to the top of the list in [[$:/StoryList]].
The [[story tiddler|$:/core/ui/PageTemplate/story]] transcluded in [[$:/core/ui/PageTemplate]] then uses a ~ListWidget to transclude all tiddlers in [[$:/StoryList]] through a special template [[$:/core/ui/ViewTemplate]].
The ViewTemplate here is a combination of different fragments, like title fragment and body fragment, each fragment can be override individually using [[Cascade Mechanism|How to Create a Custom Cascade Entry]].
A event of the type ``tm-close-tiddler`` would remove a specified tiddler from [[$:/StoryList]].
The [[Event Mechanism]] would trigger a changed event which triggers a call of the ~ListWidget's refresh function which would remove the tiddler from the list, closing the tiddler.

7
editions/tw5.com/tiddlers/TiddlyWiki Docs PR Maker.tid
View File

@@ -1,11 +1,10 @@
created: 20240313100515958
modified: 20240313103959789
modified: 20251023154747366
tags: Editions
title: TiddlyWiki Docs PR Maker
''~TiddlyWiki Docs PR Maker'' is a special edition of tiddlywiki.com designed to help you contribute to and improve the documentation made by [[@saqimtiaz|https://github.com/saqimtiaz/]].
https://saqimtiaz.github.io/tw5-docs-pr-maker/
''~TiddlyWiki Docs PR Maker'' is a special edition of tiddlywiki.com designed to help you contribute to and improve the documentation.
https://edit.tiddlywiki.com
All changes made to the documentation can be very easily submitted to GitHub -- the pull request will be automatically made, hence the "PR Maker" name of the edition.

3
editions/tw5.com/tiddlers/about/Developers.tid
View File

@@ -1,5 +1,5 @@
created: 20150412191004348
modified: 20240925114810504
modified: 20251022153208584
tags: Community Reference
title: Developers
type: text/vnd.tiddlywiki
@@ -8,3 +8,4 @@ type: text/vnd.tiddlywiki
* Get involved in the [[development on GitHub|https://github.com/TiddlyWiki/TiddlyWiki5]]
* [[GitHub Discussions|https://github.com/TiddlyWiki/TiddlyWiki5/discussions]] are for Q&A and open-ended discussion
* [[GitHub Issues|https://github.com/TiddlyWiki/TiddlyWiki5/issues]] are for raising bug reports and proposing specific, actionable new ideas
* See [[Contributing]] for guidelines on how to contribute to the project.

30
editions/tw5.com/tiddlers/about/Filter Syntax History.tid
View File

@@ -1,22 +1,22 @@
title: Filter Syntax History
tags: [[History of TiddlyWiki]]
modifier: Jeremy Ruston
created: 20250730154331065
modified: 20250730154331065
modified: 20250731162557775
modifier: Jeremy Ruston
tags: [[History of TiddlyWiki]]
title: Filter Syntax History
In response to [[a discussion|https://talk.tiddlywiki.org/t/filter-syntax-history/13058]] about the filter syntax in TiddlyWiki5 I posted this brief personal history.
For context, before TiddlyWiki, I only had practical experience of a very small number of languages: machine code, assembly language, BASIC, FORTH, C, C++ and of course JavaScript. I had a smattering of Java, Pascal and one or two other ancient languages but no experience of actor based languages like Erlang, or modern functional languages.
The story starts with the double square bracket syntax used in wikitext for links. In 2004 this was already an established usage in wikis. However, I switched the ordering of pretty links because I thought Wikipedia's `[[link address|link text]]` was the wrong way around. It broke up sentences: `The file is [[https://site.com/thing|here]]` seems less readable than `The file is [[here|https://site.com/thing]]`. For a long time I regretted this decision, and wished that I had just gone with Wikipedia's established usage. Others have since pointed out that TiddlyWiki's ordering is actually consistent with [[Markdown]], which might be regarded as the winner of the markup wars.
The story starts with the double square bracket syntax used in wikitext for links. In 2004 this was already an established usage in wikis. However, I switched the ordering of pretty links because I thought Wikipedia's `[[link address|link text]]` was the wrong way around. It broke up sentences: `The file is [[https://site.com/thing|here]]` seems less readable than `The file is [[here|https://site.com/thing]]`. For a long time I regretted this decision, and wished that I had just gone with Wikipedia's established usage. Others have since pointed out that ~TiddlyWiki's ordering is actually consistent with [[Markdown]], which might be regarded as the winner of the markup wars.
I looked at the double square bracket link syntax is that it establishes a way to quote page/tiddler titles so that they may contain spaces, and don't have to use CamelCase. Thus, right at the start of TiddlyWiki Classic when I was implementing the first iteration of the DefaultTiddlers feature it was natural to use double square brackets to quote titles containing spaces, making a list of titles to be opened at startup.
I looked at the double square bracket link syntax is that it establishes a way to quote page/tiddler titles so that they may contain spaces, and don't have to use CamelCase. Thus, right at the start of [[TiddlyWiki Classic|TiddlyWikiClassic]] when I was implementing the first iteration of the DefaultTiddlers feature it was natural to use double square brackets to quote titles containing spaces, making a list of titles to be opened at startup.
Soon, I wanted to extend the implementation of DefaultTiddlers so that it could be used to open all tiddlers with a particular tag while retaining backwards compatibility.
A trick that I am apt to use in such situations is to try to engineer things so that the current behaviour is re-interpreted as a shortcut syntax for a new, richer syntax that provides more flexibility. In this case, the idea was that in filters we would interpret `[[mytiddler]]` as a shortcut for `[title[mytiddler]]`. Then we could put any keywords we like in place of "title", giving us an infinitely extensible syntax. A similar example is the way that we implemented filter run prefixes by retrospectively defining the absence of a prefix as implying a default prefix.
The new syntax was first [introduced in 2007] (see [this commit](https://github.com/TiddlyWiki/TiddlyWikiClassic/commit/1928962ea6811b1ca67378ed3cd62059a9806ae9)), with a simplified syntax that only supported a single `tag` operator but was just about sufficient for intended purpose. The only documentation was a comment in the source code (complete with a typo):
The new syntax was first [[introduced in 2007|https://github.com/TiddlyWiki/TiddlyWikiClassic/commit/1928962ea6811b1ca67378ed3cd62059a9806ae9]], with a simplified syntax that only supported a single `tag` operator but was just about sufficient for intended purpose. The only documentation was a comment in the source code (complete with a typo):
```
// Filter a list of tiddlers
@@ -24,19 +24,19 @@ The new syntax was first [introduced in 2007] (see [this commit](https://github.
//# Returns an array of Tiddler() objects that match the filter expression
```
Provision to combine the filter operators had been on my mind from the beginning. When TiddlyWiki 5 started in 2011 I reused the simple implementation from TiddlyWiki Classic. Smashing operators [was finally implemented in May 2012](https://github.com/TiddlyWiki/TiddlyWiki5/commit/8b0703b694e982b2bc448bdb133742164723dd8a). By the time of the launch the filter language had grown into pretty much what it is today -- see the [documentation for TiddlyWiki v5.1.0](https://tiddlywiki.com/archive/full/TiddlyWiki-5.1.0#Introduction%20to%20Filters).
Provision to combine the filter operators had been on my mind from the beginning. When ~TiddlyWiki 5 started in 2011 I reused the simple implementation from ~TiddlyWiki Classic. Smashing operators [[was finally implemented in May 2012|https://github.com/TiddlyWiki/TiddlyWiki5/commit/8b0703b694e982b2bc448bdb133742164723dd8a]]. By the time of the launch the filter language had grown into pretty much what it is today -- see the [[documentation for TiddlyWiki v5.1.0|https://tiddlywiki.com/archive/full/TiddlyWiki-5.1.0#Introduction%20to%20Filters]].
The filter syntax had undoubtedly evolved into something approaching a programming language. As others have probably expressed much more eloquently, a characteristic of the programming languages that I love is that they start with a small number of principles that are consistently applied and combined. In the case of TiddlyWiki, the list would be very roughly:
The filter syntax had undoubtedly evolved into something approaching a programming language. As others have probably expressed much more eloquently, a characteristic of the programming languages that I love is that they start with a small number of principles that are consistently applied and combined. In the case of ~TiddlyWiki, the list would be very roughly:
* Double square brackets for linking and quoting
* Curly braces for transclusion
* Angle brackets for macros (which evolved into variables)
* Double square brackets for [[linking and quoting|Linking in WikiText]]
* Curly braces for [[transclusion|Transclusion in WikiText]]
* Angle brackets for [[macros|Procedures]] (which evolved into variables)
* Double exclamation marks to indicate fields `{{!!myfield}}`
* Double hashes to indicate indexes `{{##myindex}}`
* Smashing together adjacent filter operations by removing the combining `][`
* The dollar sign as a rough signifier of data owned by the system rather than the user
* Smashing together adjacent [[filter operations|Introduction to filter notation]] by removing the combining `][`
* The dollar sign as a rough signifier of data [[owned by the system|Transclusion in WikiText]] rather than the user
As I have written about elsewhere I was privileged to know Joe Armstrong, the co-inventor of Erlang, in the last few years of his life – we were working together on a book about TiddlyWiki when he passed away in 2019. Joe had contacted me out of the blue ten years before to express his admiration for TiddlyWiki, and we had developed a friendship. He was actually a big fan of TW5's filter syntax, and used to make me feel better about it by joking that I had (re-)invented the monad, which sounded impressive to me. That doesn't make the filter language any easier to learn, but it does mean that it is *worth* learning: it's a real language, based on the same principles as other languages.
As I have written about elsewhere I was privileged to know Joe Armstrong, the co-inventor of Erlang, in the last few years of his life – we were working together on a book about ~TiddlyWiki when he passed away in 2019. Joe had contacted me out of the blue ten years before to express his admiration for ~TiddlyWiki, and we had developed a friendship. He was actually a big fan of TW5's filter syntax, and used to make me feel better about it by joking that I had (re-)invented the monad, which sounded impressive to me. That doesn't make the filter language any easier to learn, but it does mean that it is *worth* learning: it's a real language, based on the same principles as other languages.
I find it pleasing that the TW5 filter language has its roots in decisions that were taken in the TWC days. It's still hard to learn, but that's an ongoing paradox of programming: people want to do complicated things, and complicated things are complicated. It's hard to see how we could have made filters any simpler without depriving users of the possibility of doing complicated things.

3
editions/tw5.com/tiddlers/commands/RenderCommand.tid
View File

@@ -1,6 +1,6 @@
caption: render
created: 20170919131752774
modified: 20170919131805871
modified: 20250811164528905
tags: Commands
title: RenderCommand
type: text/vnd.tiddlywiki
@@ -10,6 +10,7 @@ type: text/vnd.tiddlywiki
<$button class="tc-btn-invisible" style="text-decoration:underline">
Show available rendering templates
<$action-setfield $tiddler="$:/temp/advancedsearch" text="[all[shadows]prefix[$:/core/templates/]]"/>
<$action-setfield $tiddler="$:/temp/advancedsearch/input" text="[all[shadows]prefix[$:/core/templates/]]"/>
<$action-setfield $tiddler="$:/state/tab--1498284803" text="$:/core/ui/AdvancedSearch/Filter"/>
<$action-navigate $to="$:/AdvancedSearch"/>
</$button>

4
editions/tw5.com/tiddlers/community/Improving TiddlyWiki Documentation.tid
View File

@@ -1,5 +1,5 @@
created: 20140820151051019
modified: 20240313114828368
modified: 20251023154718268
tags: Community
title: Improving TiddlyWiki Documentation
type: text/vnd.tiddlywiki
@@ -20,7 +20,7 @@ You can choose to edit the documentation using the [[TiddlyWiki Docs PR Maker]]
!! Using [[Docs PR Maker|TiddlyWiki Docs PR Maker]] edition
# Go to https://saqimtiaz.github.io/tw5-docs-pr-maker/ or click the link displayed in the ribbon underneath the title when editing a tiddler on tiddlywiki.com
# Go to https://edit.tiddlywiki.com or click the link displayed in the ribbon underneath the title when editing a tiddler on tiddlywiki.com
# Go through the quick introduction where you will need to provide your ~GitHub username and a ~GitHub access token (you will be guided in creating one)
# Edit or create tiddlers to update the documentation, the wiki will keep track of all changes
# Click the "Submit updates" button and check if all the tiddlers that you edited are included in the submission; if not, drag them into the box

2
editions/tw5.com/tiddlers/filters/syntax/Filter Syntax.tid
View File

@@ -9,7 +9,7 @@ type: text/vnd.tiddlywiki
A <<.def filter>> is a pipeline for transforming an <<.def input>> into an <<.def output>>. Both the input and the output are [[ordered sets of titles|Title Selection]] of tiddlers and fields.
Filters are ''expressions'' constructed from smaller building blocks, called ''runs'', which are built using ''steps''. Eeach of which also transforms an input to an output.
Filters are ''expressions'' constructed from smaller building blocks, called ''runs'', which are built using ''steps''. Each of which also transforms an input to an output.
A filter starts with an empty output. Its runs are processed from left to right, progressively modifying the output.

2
editions/tw5.com/tiddlers/system/ContributionBanner.tid
View File

@@ -12,7 +12,7 @@ https://github.com/TiddlyWiki/TiddlyWiki5/edit/tiddlywiki-com/editions/tw5.com/t
<$list filter="[[$:/config/OriginalTiddlerPaths]getindex<draft-of>]" variable="target" >
<div class="tc-improvement-banner">
{{$:/core/images/star-filled}} Can you help us improve this documentation? [[Find out how|Improving TiddlyWiki Documentation]] to
<a href={{{ [<draft-of>encodeuricomponent[]addprefix[https://saqimtiaz.github.io/tw5-docs-pr-maker/#]] }}} class="tc-tiddlylink-external" target="_blank" rel="noopener noreferrer">edit this tiddler in Docs PR Maker</a>
<a href={{{ [<draft-of>encodeuricomponent[]addprefix[https://edit.tiddlywiki.com/#]] }}} class="tc-tiddlylink-external" target="_blank" rel="noopener noreferrer">edit this tiddler in Docs PR Maker</a>
or
<a href={{{ [<target>addprefix<base-github>] }}} class="tc-tiddlylink-external" target="_blank" rel="noopener noreferrer">edit it directly on ~GitHub</a>
</div>

2
editions/tw5.com/tiddlers/system/Sources.tid
View File

@@ -37,7 +37,7 @@ title: $:/editions/tw5.com/TiddlerInfo/Sources
\end
\procedure make-pr-maker-link()
<a href={{{ [<currentTiddler>encodeuricomponent[]addprefix[https://saqimtiaz.github.io/tw5-docs-pr-maker/#]] }}}
<a href={{{ [<currentTiddler>encodeuricomponent[]addprefix[https://edit.tiddlywiki.com/#]] }}}
class="tc-tiddlylink-external"
target="_blank"
rel="noopener noreferrer"

4
editions/tw5.com/tiddlers/systemtags/SystemTag_ $__tags_ClassFilters_TiddlerTemplate.tid
View File

@@ -1,7 +1,7 @@
caption: $:/tags/ClassFilters/TiddlerTemplate
created: 20221020035738692
description: marks filters evaluated to dynamically add classes to the page template.
modified: 20230326153057521
description: marks filters evaluated to dynamically add classes to the tiddler template.
modified: 20250608225016149
tags: SystemTags
title: SystemTag: $:/tags/ClassFilters/TiddlerTemplate
type: text/vnd.tiddlywiki

5
licenses/cla-individual.md
View File

@@ -618,6 +618,8 @@ Matthew Salmon, @matthewsalmon, 2025/04/24
@jbaldus, 2025/05/28
@yogoshell, 2025/06/08
Wu Peiyuan, @s793016, 2025/06/10
Markus Sauermann, @Sauermann, 2025/06/20
@@ -631,3 +633,6 @@ Christian Byron, @CeeBeeTree, 2025/08/05
Frédéric Demers, @bepuzzled, 2025/08/17
Joseph Yi, @josephyi, 2025/10/14
Rishu kumar, @rishu-7549, 2025/10/25