How to further master wikitext by learning system entries

[dongrentianyu]

TiddlyWiki is built by TiddlyWiki itself, which means that wikitext is heavily used in many of TiddlyWiki’s system entries. whenever I look for documentation, I point to those system entries. But the use of wikitext in those system entries looks complicated, so is it possible to come up with a series of tutorials that pick a few of them and explain them in depth.

I often go through the system entries wikitext as a way to get more inspiration. In particular I often copy it into another entry and then modify parts of it to make it work for my needs.

Or it’s nice to have the code of some plugins explained. Because I also often copy the code in a particular plugin and then modify it further to make it meet my needs.

[dongrentianyu]

\procedure single-field-edit(fieldFilter)
<div class="tc-edit-fields">
<table class="tc-edit-fields  tc-edit-fields-small">
<tbody>
<$list filter="[subfilter<fieldFilter>] :and[sort[title]]" variable="currentField" storyview="pop">
<tr class="tc-edit-field">
<td class="tc-edit-field-name">
<$text text=<<currentField>>/>:</td>
<td class="tc-edit-field-value">
<$transclude tiddler={{{ [<currentField>] :cascade[all[shadows+tiddlers]tag[$:/tags/FieldEditorFilter]!is[draft]get[text]] :and[!is[blank]else{$:/core/ui/EditTemplate/fieldEditor/default}] }}} />
</td>
<td class="tc-edit-field-remove">
<$button class="tc-btn-invisible" tooltip={{$:/language/EditTemplate/Field/Remove/Hint}} aria-label={{$:/language/EditTemplate/Field/Remove/Caption}}>
<$action-deletefield $field=<<currentField>>/>
{{$:/core/images/delete-button}}
</$button>
</td>
</tr>
</$list>
</tbody>
</table>
</div>
\end

Example. Above is a procedure. A parameter is passed inside, usually a field name. Its can be used in the following way. The default entry modified is the current entry. You can add another parameter if needed. Then you’ve got a component that can edit fields directly on the page. The reason why use this instead of a micro component like edit-text is that this component contains a lot of css and other configurations and looks a bit better.

<$transclude $variable="single-field-edit" fieldFilter="0023"/>

You can also invoke it more simply as

<<single-field-edit 0023>>

But you’ll have to use the longer form if the value passed (“0023”) is dynamic.

The procedure code above comes from $:/core/ui/EditTemplate/fields, and I’ve only modified a small part of it.

[dongrentianyu]

I see that the category of the post has been changed. If it helps others that’s great too. My intention was not to convey a tip though, but to provide an idea or inquire for more tutorials like this. Perhaps the development team could write some similar documentation to further describe it. I may try to write some sometime in the future, but I don’t know if I’m writing it correctly as there are a lot of things in there that I don’t understand either.

[pmario]

@dongrentianyu

I see that the category of the post has been changed. If it helps others that’s great too. My intention was not to convey a tip though, but to provide an idea or inquire for more tutorials like this.

I did change the category, because I think examples like this one are important. They can be the start for additional info that may be useful for others.

@dongrentianyu

… Perhaps the development team could write some similar documentation to further describe it. …

The problem is, development resources are limited. We try to document the basics. But as you know, creating documentation or tips and tricks that actually work, takes quite some time.

So community contribution is necessary.

We can convert the original post into a wiki. So yourself and everyone, which did some experiments can improve that post. So it can be improved over time. If a post is a wiki, it can be edited. For normal posts editing will be disabled after some time.

[dongrentianyu]

Thanks for the edit and reply. But I was thinking from the point of view of helping newbies to master wikitext.TiddlyWiki is really special, and the person who uses TiddlyWiki can hardly be an end-user of TiddlyWiki if he can’t master these techniques. He can easily be attracted by other emerging note-taking software and leave TiddlyWiki. so I hope to write a tutorial with a historical version. So I hope to write a tutorial with a historical version, telling the newcomer what the macro does, how it can be used, and what it lacks. Then what problems we might encounter, and then how the macro should be considered for improvement. Then show the newbie the improved version, tell them what was changed, why it was changed, and what results were achieved. And work backwards from there. This is what I want to tell the user, which is that they can know why it was done, and what they can do to improve it themselves in the future when they have their own needs. If we just provide an excellent macro to a new user, then they might think it’s a macro I can’t use, but then when they actually want to do something with TiddlyWiki, they feel they don’t have enough knowledge and skills to master TiddlyWiki.

Another reply was that I didn’t mean for the development team to specifically create some explanatory examples. Rather, it’s an explanation of how it’s built using wikitext from the system entries in the core. The most common are list wigets and filters. For example why the filters are written the way they are and what scenarios are considered.

For example, for the following code, which implements a feature where the edit field is controlled by a cascading template. This way when we need a date field, it can behave like any other template.

[<currentField>] :cascade[all[shadows+tiddlers]tag[$:/tags/FieldEditorFilter]!is[draft]get[text]] :and[!is[blank]else{$:/core/ui/EditTemplate/fieldEditor/default}]

In the image above, I have used a special field, cluster, which has a different edit template than the normal field. This shows that the filter above is in effect.

Thus if the user doesn’t know about the cascading prefix filter expression, he may not understand what this means.

[dongrentianyu]

I know the development team works very hard, so I only post questions when I don’t understand something. Maybe we should have tutorials on source code interpretation. Source code deciphering is important to tell users how TiddlyWiki is built, but there seem to be very few tutorials with similar instructions.

[Scott_Sauyet]

I made two minor tweaks

• changing “macro” to “procedure”, since the two concepts are distinct in TW
• adding a short-form << ... >> example of calling it.

There’s one other change I’d like to make, but before changing it, I wanted to hear your thoughts. I think the field name 0023 is fairly unusual. For a documentation example, would something like my-field be better?

[dongrentianyu]

That’s all fine. 0023 is a random field I wrote, and I often test with random numeric field names. But since there is a screenshot, it’s probably best to keep it, and if it’s modified, you’ll need to provide a new screenshot. I think we need more media files like videos or screenshots to illustrate the content. Of course having a demo of the website that would be better, but it takes a lot of effort and time to maintain.