Hi SS
Great stuff, thank you! I like the way that you’ve gathered input from others
and incorporated it smoothly, managing to keep a consistent tone of voice
suitable for beginners.
As background, it might be helpful for me to explain a little of *why* widgets
exists…
Consider a simple wiki with two tiddlers, Foo and Bar:
“Foo” contains “I am Foo. {{Bar}}”
“Bar” contains “I am Bar”
The result of rendering “Foo” should be “I am Foo. I am Bar”. So, a naive
algorithm for wikification would take the content of “Foo”, look for any
double braces, and then replace them with the content of the tiddler they refer
to. The processing would go something like this:
1. Get “I am Foo. {{Bar}}” from “Foo”
2. Replace “{{Bar}}” with the content of “Bar” yielding “I am Foo. I am Bar”
Now imagine that the text of “Bar” is changed to “I was Bar”, and we want to
update the rendering. We can rerun the algorithm above and get “I am Foo. I was
Bar”, but we have to regenerate the entire rendering, even though only one
tiddler has changed.
Using TiddlyWiki interactively in the browser depends on making the refresh
cycle as fast as possible. For example, when a button is clicked to trigger a
dropdown it actually just sets a tiddler value in the store that causes the
dropdown to be rendered when the display is refreshed. Thus we want to make the
refresh cycle as fast as possible.
In particular, the goal is that, given the example above, when “Bar” changes we
don’t need to re-render the entire tiddler “Foo”.
This is accomplished by building a render tree. The render tree for the example
above would be:
* Text: “I am Foo. “
* Transclusion: “Bar”
** Text: “I am Bar”
Given that render tree, we can efficiently extract the text of the result by
scanning the nodes of the tree and accumulating any “Text” nodes that we find.
If the tiddler “Bar” changes, then we need to scan the tree looking for any
transclusions that reference that particular tiddler. Those nodes will need to
be reconstructed from the new value of the tiddler, but the surrounding nodes
can be left untouched.
So, that gives you the basis for a technical, developers explanation of a
widget: they are the units by which content is refreshed.
There are a couple of further important details that shape the current design.
First, what we call parsing: this is the basic scanning of a block of text to
find bits of wikitext syntax (e.g. finding the “{{Bar}}” transclusion in “Foo”
above). The result of parsing is a tree that we then use to construct the
render tree. As a basic optimisation, we cache the parse tree for a tiddler,
and only regenerate it when the tiddler changes.
Secondly, each node in the render tree may render one or more DOM nodes that
are attached to it.
With those details, you’ve got a lightning overview of how widgets work. It’s
not suitable for beginners but it might help give you some background.
Best wishes
Jeremy
> On 7 Feb 2019, at 08:16, S. S. <[email protected]> wrote:
>
>
> It's taken a month of on-and-off giving it some attention.
>
> Here's the result!
>
> Widgets for Beginners
> <https://00ss.github.io/documentation/tiddlywiki.html#Widgets%20for%20Beginners>
>
> Feel free to thrash it and make it better by leaving some critical comments.
>
> --
> You received this message because you are subscribed to the Google Groups
> "TiddlyWiki" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to [email protected]
> <mailto:[email protected]>.
> To post to this group, send email to [email protected]
> <mailto:[email protected]>.
> Visit this group at https://groups.google.com/group/tiddlywiki
> <https://groups.google.com/group/tiddlywiki>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/tiddlywiki/b86ff0f5-f9fb-478c-bbd7-4cdda2124a07%40googlegroups.com
>
> <https://groups.google.com/d/msgid/tiddlywiki/b86ff0f5-f9fb-478c-bbd7-4cdda2124a07%40googlegroups.com?utm_medium=email&utm_source=footer>.
> For more options, visit https://groups.google.com/d/optout
> <https://groups.google.com/d/optout>.
--
You received this message because you are subscribed to the Google Groups
"TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/tiddlywiki.
To view this discussion on the web visit
https://groups.google.com/d/msgid/tiddlywiki/8A45BF52-DF2F-4E99-ABCB-92D453D36DB6%40gmail.com.
For more options, visit https://groups.google.com/d/optout.
