Merge 254f2ed00130006e62c42cd79afd233d1e8772c1 into 961e74f73d230d0028efb586db07699120eac888

editions/dev/tiddlers/How to Create a Custom Cascade Entry.tid

@@ -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%>
+```

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

@@ -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.