Using testcase-widget for documentation

[pmario]

@Jermolene I did create a testcase tiddler "Examples/TOC/SimpleToc" as: text/vnd.tiddlywiki-multiple like so

title: Narrative

- The following code defines a "Simple Table of Contents" using "root" as the base tag.<br>
- Click through all the tabs to get additional info<br>
{{Narrative-extended}}

+
title: root
list: First Third Fourth

The list-field in the "root" tag-tiddler can be used to define the "sort order" of the TOC
+
title: First
tags: root

1st 1st 1st 1st 1st
+
title: Second
tags: First

2nd 2nd 2nd 2nd 2nd
+
title: Third
tags: root

3rd 3rd 3rd 3rd 3rd
+
title: Fourth
caption: fourth-caption
tags: root

4th 4th 4th 4th 4th 

This tiddler contains a caption, which will be shown in the TOC instead of the tiddler title
+
title: Output

<div class="tc-table-of-contents">
<<toc tag:"root">>
</div>

That's OK. -- Now I do want to create a second test, that adds a fifth tiddler with an alt-field, to describe the <<toc captionField:alt ..>> parameter.

The code looks like this and is extremely hard to read and create. The code works as a standard tiddler, with no tag.

<$testcase testOutput="Output" >

<$data title="Description" text="Simple TOC - captionField parameter"/>

<$data title="Narrative-extended" text="""- The "Fifth" tiddler has an alternative "caption-field" """/>

<$data $compound-tiddler="Examples/TOC/SimpleToc"/>

<$data title="Fifth" tags="Fourth" text="5th" alt="alt-caption"/>

<$data title="Output" text="""<div class="tc-table-of-contents">
<<toc tag:"root" captionField:"alt">>
</div>
"""/>

What I would like to do is: Create a second test-tiddler tagged: $:/tags/wiki-test-spec type: text/vnd.tiddlywiki-multiple with something as follows.

• It imports the first tiddler
• It overwrites existing tiddlers which need a different content
• It adds new tiddlers with the new content

So there is minimal "duplication"

\import-compound [[Examples/TOC/SimpleToc]]

title: Description
text: Simple TOC - captionField parameter
+
title: Narrative-extended
text: "Fifth" tiddler has an alternative "caption-field"
+
title: Fifth
tags: Fourth
alt: alt-caption
text: 5th
+
title: Output

<div class="tc-table-of-contents">
<<toc tag:"root" captionField:"alt">>
</div>

[pmario]

I did find a hack, which is not really pretty, but works.
I think the data-widget should get a $compound-filter attribute, that allows us to import several compound tiddlers. This would be easy to use in the $:/core/ui/TestCaseTemplate

title: $:/core/ui/TestCaseTemplate

\parameters (hideIfPass:"no")
\whitespace trim
<$let
	linkTarget="yes"
	displayFormat={{!!display-format}}
	testcaseTiddler=<<currentTiddler>>
>
	<$testcase
		testOutput="Output"
		testExpectedResult="ExpectedResult"
		testActions="Actions"
		testHideIfPass=<<hideIfPass>>
	>
		<$data $compound-tiddler={{!!import-compound}}/><!-- see this hack -->
		<$data $compound-tiddler=<<currentTiddler>>/>
		<$data title="Description" text={{!!description}}/>
	</$testcase>
</$let>

[pmario]

@Jermolene -- What do you think about the possibility to "include" one external compound tiddler by default.
Or
Do you think there should be a new $compound-filter parameter for the data-widget?

[pmario]

@Jermolene -- bump

[Jermolene]

That would certainly be a valid approach, and is probably consistent with the way that we handle the display-format field.

[pmario]

So you think I should change the template and include 1 {{!!import-compound}} field. No $compound-filter parameter?

[Jermolene]

Sorry, we do definitely need the $compound-filter attribute on the <$data> widget. I was thinking that the value of import-compound would be a filter, not a single tiddler.

[pmario]

@Jermolene -- How far can we go with creating new temporary tiddlers in test-casees. eg: state tiddlers are shown in the "tab-view".

To create the new TOC documentation I need to activate the "New Here" or "New Child Here" buttons and I would like it, if they actually work.

If clicked, they do create a new "Draft of..." tiddler. I did modify the testcase templates a tiny bit, to get this:

If OK is clicked it creates a new temporary tiddler

Do you think that's too far?

[pmario]

IMO, for these examples your "New Child Here" button should be implemented with $action-createtiddler so the draft can be skipped altogether. I don't think having the intermediate draft will help the user understand anything about the TOC macro?

NewHere is a real function. So there has to be a Draft-tiddler for the real function. Normally the draft-tiddler is created in the story-river. But with testcases the tabs are the story-river. I want to have the same functionality in the "real" story river than in the test-case for experimenting.

But I don't understand from the above screenshots where the "new child here" buttons are coming from, so I might be missing something.

They are part of the rewritten TOC-macros. They are activated with the variable tv-toc-show-new-child set to "yes"

[pmario]

With the current implementation of the test-case widgets if you create a button which sends tm-new-tiddler, it will create a new tiddler in the "real" wiki. But it should create a tiddler in the test-case-wiki. I did achieve that by "wrapping" the template into a navigator-widget where "stoy-list" and "history-list" are unique per test-case

[pmario]

@btheado -- I did upload a preview to tiddlyhost, where you can play with it.

I did also raise a new issue at GH: [Bug] test-case-widget does not contain action-sendmessages #8458

[btheado]

Thanks. It makes more sense now. It also helped me to look at the code changes in #7961.

I'm not sure whether adding navigator widget by default is overall good or bad.

One drawback is that adding it breaks the "Import" in the test case pull down menu. The navigator widget you added is intercepting and so the testcase tiddlers do not make it into the outer wiki.

where "stoy-list" and "history-list" are unique per test-case
Is that necessary? I thought the template is rendered within the context of the "subwiki" so the tiddler titles are already unique.

[pmario]

You are right the "testcase" widget has its own wiki-object, so history-list and story-list are "isolated". No need to make them unique.

---

I think the whole "testcase functionality" is still in flux. The new UI elements have been added, to make it possible to test them. To see if they work as expected and if they are useful.

For me the testcase "Import tiddlers" is the wrong name anyway. If I click it, I expect, that it imports tiddlers into the testcase. What it does at the moment is: It exports single tiddlers from testcase -> to the parent wiki. So the name definitely has room for improvement.

---

Anyway.

I did a little experiment and gave the navigator widget a "navContext" parameter that is written to this.navContext and tv-nav-context variable similar to tv-story-list. eg: The default is: navContext="root" So for the testcase-template it is set to navContext:"testcase". If the parameter is missing it defaults to root.

The navigator only processes tm-* messages that have the same navContext as the event.tv-nav-context variable. If evnt.tc-nav-context is different to the navigator.navContext it hands over the tm-* event to the parent widget.

So in the testcase-template we can do this (pseudocode):

$let tc-nav-context="root"
$action-sendmessage tm-import-tiddlers 

So the navigator.navContext:"testcase" will hand over the tm-import-tiddlers event to the parent, where the event bubbles up to the navigator.navContext:"root" which catches it.

For this to work we need to adjust all the occurrences of .dispatchEvent("tm-*") with messages that the navigator catches. In the whole source code there are 3 or 4 files, which need to be adjusted. Similar adjustments have to be done for tv-story-list and tv-history-list

---

I did also start to experiment with a "tabbed story-river" using the $list-widget instead of using the tabs-macro in testcase-templates. This change can completely eliminate the need for the $linkcatcher widget and "custom actions". It will use the standard behaviour of a story-river in a "tabbed" fashion.

We already have a custom view-template for the testcase tiddlers. It will be easy to create a custom edit-template, which allows us to modify every field of the test-case for experimenting if needed. (including the possibility to make changes permanent)

just some thoughts

[pmario]

@btheado -- I did just push a new preview to tiddlyhost, where the testcase shows 2 "tabbed views"

1. Using the tabs-macro -- As implemented at the moment
2. A tabbed "Story river" using the same CSS and DOM structure

• The advantage is, that the story river does not need the "linkcatcher" widget to allow navigation between tabs.
• The "Import dropdown" is not fixed in that version. I still think, it should do something completely different.

• I did completely restructure the core/ui/TestCases/DefaultTemplate.tid for better readability.
• And there is a new core/ui/TestCases/DefaultTemplateSourceTabsNEW.tid, which has better focus-handling for editing the draft-title.
• I think for testing testcase should allow us to modify all fields interactively.
• In the end I would like a possibility to create a new "compound tiddler" from my modified testcase-tiddler. IMO with the right template this should be straight forward.

[btheado]

@pmario, thanks for sharing the wiki. I like the factoring out into smaller procedures. It makes it easy to play with the code (using the testcase widget, of course!) to help understand how it works.

Here are some experiments you can paste into your test wiki:

<$testcase>
<$data title=Description text="Use a link to test StoryList"/>
<$data title=Narrative text="IMO it would be better if tabs were created for ~StoryList entries"/>
<$data title=Output text="""~StoryList: {{$:/StoryList!!list}} 

$:/core/ui/testcases/DefaultTemplate <== click this link would be better if the tab appeared for this tiddler"""/>
</$testcase>

<$testcase>
<$data title="Description" text="Render the testcase-fail procedure"/>
<$data title=Output text="""<$let expectedHTML="one" outputHTML="won"><<testcase-fail>></$let>"""/>
</$testcase>

<$testcase>
<$data title="Description" text="Render the toolbar"/>
<$data title=Narrative text="Note the typo in the macro name. 'textcase' => 'testcase'"/>
<$data title=Output text="""<<textcase-toolbar>>"""/>
</$testcase>

<$testcase>
<$data title="Description" text="Render the header"/>
<$data title=Output text="""<<testcase-header>>"""/>
</$testcase>

<$testcase>
<$data title="Description" text="Render the output"/>
<$data title="Narrative" text="Maybe a slightly different factoring of the code could allow more of it to be called standalone without running into recursion?"/>
<$data title=Output text="""<$let displayFormat="plaintext"><<testcase-output>></$let>"""/>
</$testcase>

I like the use of HistoryList!!currentTiddler for the active tab. As I mention in the first testcase, it would be better if tabs were created for StoryList entries.

The "Import dropdown" is not fixed in that version. I still think, it should do something completely different.

I find the functionality in the existing default testcase template useful. I agree it should have a better title. I'm not sure what behavior change you are proposing.

The fix seems somewhat straightforward. If the toolbar is outside the navigator widget, then it should behave as before. I don't see a reason to have the toolbar inside the navigator widget.

[pmario]

Import Tiddlers
... I'm not sure what behavior change you are proposing.

• I want to import tiddlers into the testcase from a JSON file.
• I also want to import JSON tiddlers into a compound tiddler and save is as a compound tiddler.

The fix seems somewhat straightforward. If the toolbar is outside the navigator widget, then it should behave as before. I don't see a reason to have the toolbar inside the navigator widget.

You are right. Keeping it simple is the way to go. I'll change that with the next push.

[pmario]

@btheado -- In general, what do you think about using a "story-river" instead of the tabs-macro for the testcase main UI?

[btheado]

use it with state={{$:/HistoryList!!current-tiddler}} in place of state=<<state>>

Oops. This is wrong. The state attribute needs to take the prefix of a tiddler title as input, not a value

[pmario]

The behavior of the current default template and your experimental version both have less than ideal behavior clicking on shadow tiddler links:

That's an easy fix. I did fix that for the story-river version

[pmario]

The "story river" is much more flexible. I would like to have a "template" and an "editTemplate" parameter in the list-widget. The testcase-story-river would also need a template-cascade similar to the standard story-river.

It would be nice, if the testcase-story-river would also work in the current story river.

[btheado]

I'm having trouble understanding what you mean by "the story-river version". Is this what you shared at the tiddlyhost site or something different?

[pmario]

The tabbed story-river is the second view that can be seen at TH at the moment. It behaves like the standard story river in the main wiki. But it is tabbed.

IMO the tabs-macro is limited in possibilities.

[Jermolene]

Hi @pmario these are interesting experiments, but I am concerned at the unintended side effects of so much added complexity. If the new TOC stuff is particularly demanding to demo with the testcase widget then I'd be inclined to explore a special testcase template for the TOC demos, rather than complexifying the main testcase template.

[btheado]

It would be nice if the the default template UI components could be easily re-used by any special testcase templates. By factoring into procedures as @pmario has done or breaking into multiple tiddlers or however would be best.