feat: update Breadcrumb usage

tiddly-gittly · Oct 29, 2024 · 9079823 · 9079823
1 parent 2a6b0a9
commit 9079823
Show file tree

Hide file tree

Showing 4 changed files with 95 additions and 20 deletions.
diff --git a/src/streams-outliner-lib/language/en-GB/Readme.tid b/src/streams-outliner-lib/language/en-GB/Readme.tid
@@ -16,7 +16,9 @@ title: $:/plugins/linonetwo/streams-outliner-lib/language/en-GB/Readme
 
 <<lingo Description>>
 
-!! Usage
+Read the interactive doc on [ext[https://tiddly-gittly.github.io/streams-outliner-lib/]].
+
+!! Outliner Usage
 
 Create an outliner that will add information to tiddler [[Index]]'s fields:
 
@@ -53,3 +55,35 @@ Note that it only takes effect on the second node (create a random node first, t
 
 <<wikitext-example-without-html """<<stream-outliner Index4 newNodeTiddlerTemplate:"$:/plugins/linonetwo/streams-outliner-lib/language/en-GB/Name" id:stream-outliner-5>>""">>
 
+!! Other Tools
+
+!!! Breadcrumb Navigation
+
+It's probably not useful to use it directly, it's generally used by adding it to a tiddler viewing template, such as the one below.
+
+You can modify the `tags[XXX]` part to precisely match the tiddlers provided by your plugin. Keeping it precise here prevents your tiddler view template from having an effect on the tiddlers of other people's plugins, who may not want to show breadcrumb navigation.
+
+
+```tid
+tags: $:/tags/ViewTemplate
+list-before: $:/core/ui/ViewTemplate/body
+title: your-breadcrumbs-view-template
+
+<%if [<currentTiddler>has[stream-type]tags[XXX]] %>
+  <<stream-show-breadcrumbs>>
+<%endif%>
+```
+
+Or show breadcrumb navigation only on outline node tiddlers in [[Index]] tiddlers (each outline node is a tiddler, and they are available via the `get-stream-nodes[]` filter), and do a quick pre-filter with `[<currentTiddler>has[stream-type]]` to avoid performing time-consuming filter node filters on every open non-outline node tiddler.
+
+When you use it, remember to modify `Index` to the name of the tiddler you care about.
+
+```tid
+tags: $:/tags/ViewTemplate
+list-before: $:/core/ui/ViewTemplate/body
+title: your-breadcrumbs-view-template
+
+<%if [<currentTiddler>has[stream-type]] +[[Index]get-stream-nodes[]title<currentTiddler>] %>
+  <<stream-show-breadcrumbs>>
+<%endif%>
+```
diff --git a/src/streams-outliner-lib/language/zh-Hans/Readme.tid b/src/streams-outliner-lib/language/zh-Hans/Readme.tid
@@ -16,7 +16,9 @@ title: $:/plugins/linonetwo/streams-outliner-lib/language/zh-Hans/Readme
 
 <<lingo Description>>
 
-!! 使用方法
+阅读 [ext[https://tiddly-gittly.github.io/streams-outliner-lib/]] 上的互动文档。
+
+!! 大纲使用方法
 
 创建一个大纲，将信息添加到条目 [[Index]] 的字段里：
 
@@ -42,7 +44,7 @@ title: $:/plugins/linonetwo/streams-outliner-lib/language/zh-Hans/Readme
 
 <<wikitext-example-without-html """<<stream-outliner Index4 newNodeTitle:"<<stream-root-title>>-<<now [UTC]YYYY0MM0DD0hh0mm0ssXXX>>" id:stream-outliner-4>>""">>
 
-!! 用来作为新的节点模板
+!!! 用来作为新的节点模板
 
 这个条目将用作新节点的模板。您需要在这里填写一个现有的条目的标题。
 
@@ -51,3 +53,37 @@ title: $:/plugins/linonetwo/streams-outliner-lib/language/zh-Hans/Readme
 注意它只有在第二个节点才开始生效（先随便创建一个节点，然后按回车来创建第二个节点看看）。
 
 <<wikitext-example-without-html """<<stream-outliner Index5 newNodeTiddlerTemplate:"$:/plugins/linonetwo/streams-outliner-lib/language/zh-Hans/Name" id:stream-outliner-5>>""">>
+
+!! 其它工具
+
+!!! 面包屑导航
+
+<<wikitext-example-without-html """<<stream-show-breadcrumbs>>""">>
+
+直接使用它可能没什么作用，一般是把它加到一个条目查看模板上使用，例如下面这个条目。
+
+你可以修改 `tags[XXX]` 这部分来精确匹配你的插件提供的条目。在这里保持精确可以避免你的条目查看模板在其他人的插件的条目上产生影响，其他人可能不希望展示面包屑导航。
+
+```tid
+tags: $:/tags/ViewTemplate
+list-before: $:/core/ui/ViewTemplate/body
+title: your-breadcrumbs-view-template
+
+<%if [<currentTiddler>has[stream-type]tags[XXX]] %>
+  <<stream-show-breadcrumbs>>
+<%endif%>
+```
+
+或只在[[Index]] 条目里的大纲节点条目上展示面包屑导航（每个大纲节点都是一个条目，通过 `get-stream-nodes[]` 筛选器可以获取到它们），并使用 `[<currentTiddler>has[stream-type]]` 来做一个快速的预筛选，以免在每个打开的非大纲节点条目上都要执行费时的筛选器节点筛选器。
+
+你在使用时，记得修改 `Index` 为你关心的条目名。
+
+```tid
+tags: $:/tags/ViewTemplate
+list-before: $:/core/ui/ViewTemplate/body
+title: your-breadcrumbs-view-template
+
+<%if [<currentTiddler>has[stream-type]] +[[Index]get-stream-nodes[]title<currentTiddler>] %>
+  <<stream-show-breadcrumbs>>
+<%endif%>
+```
diff --git a/src/streams-outliner-lib/templates/breadcrumbs.tid b/src/streams-outliner-lib/templates/breadcrumbs.tid
@@ -1,22 +1,20 @@
 title: $:/plugins/linonetwo/streams-outliner-lib/breadcrumbs-view-template
 tags: $:/tags/Global
 
-\whitespace trim
 \procedure stream-show-breadcrumbs()
-<$list filter="[<currentTiddler>has[stream-type]]">
-	<$list filter="[<currentTiddler>has[parent]]">
-		<$set name="currentTiddler" filter="[{!!parent}]" select="0">
-			<<stream-show-breadcrumbs>>
-		</$set>
-	</$list>	
-	<$list filter="[<currentTiddler>!match<storyTiddler>]">
-		<$wikify name="display-title" text={{{ [<currentTiddler>!is[binary]get[text]!is[blank]] ~[{!!title}] }}}>
-			<span class="sq-breadcrumbs-fragment">
-			<$link to=<<currentTiddler>>>
-				<$text text={{{ [<display-title>split[]first[50]join[]] }}}/>
-			</$link>>
-			</span>
-		</$wikify>
-	</$list>
-</$list>
+\whitespace trim
+<%if [<currentTiddler>has[parent]] %>
+	<$set name="currentTiddler" filter="[{!!parent}]" select="0">
+		<<stream-show-breadcrumbs>>
+	</$set>
+<%endif%>
+<%if [<currentTiddler>!match<storyTiddler>] %>
+	<$wikify name="display-title" text={{{ [<currentTiddler>!is[binary]get[text]!is[blank]] ~[{!!title}] }}}>
+		<span class="sq-breadcrumbs-fragment">
+		<$link to=<<currentTiddler>>>
+			<$text text={{{ [<display-title>split[]first[50]join[]] }}}/>
+		</$link>>
+		</span>
+	</$wikify>
+<%endif%>
 \end
diff --git a/wiki/tiddlers/streams/IndexExampleBreadcrumbs.tid b/wiki/tiddlers/streams/IndexExampleBreadcrumbs.tid
@@ -0,0 +1,7 @@
+tags: $:/tags/ViewTemplate
+list-before: $:/core/ui/ViewTemplate/body
+title: IndexExampleBreadcrumbs
+
+<%if [<currentTiddler>has[stream-type]] +[[Index]get-stream-nodes[]title<currentTiddler>] %>
+  <<stream-show-breadcrumbs>>
+<%endif%>