diff --git a/editions/dev/tiddlers/How to Create a Custom Cascade Entry.tid b/editions/dev/tiddlers/How to Create a Custom Cascade Entry.tid new file mode 100644 index 000000000..d96ceb2bb --- /dev/null +++ b/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]]. + +
+<$view tiddler="$:/core" subtiddler="$:/core/ui/ViewTemplate/tags/default" mode=block format=text/> ++ +!!! 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. + +
+<$view tiddler="$:/core" subtiddler="$:/core/ui/ViewTemplate/tags" mode=block format=text/> ++ +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. + +
+<$view tiddler="$:/core" subtiddler="$:/core/ui/ControlPanel/ViewTemplateTags" mode=block format=text/> ++ +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=<