Widgets for Dummies

[S. S.]

A new user reads the Widget & Widgets in WikiText tiddlers and then asks - can you please give me a simpler explanation of what is meant by "a Widget"?

A line each from the above tiddlers:

Widgets provide rich functionality within WikiText. They have the same syntax as HTML elements, but the tag name always starts with $.

Each class of widget contributes a specific ability to the overall functionality, such as the ability to display an image or a button, to call a macro or transclude text from elsewhere, or to mark a piece of text as a heading.

How would you answer this question to a new visitor?

Please be aware your answer, or a part of it, may be used on the website!

[TonyM]

Wiki text includes simple ways to change the apperence of text, bold, creating bullet lists and links to tiddlers etc..

It is however possible it include html such as
<code>some text</code> however if html demands javascript to calculate or process it, it will not work without making a plugin, JavaScript macro etc...

Widgets on the other hand are designed for tiddlywiki and take the form;

<$widgetname parameters/>
Or
<$widgetname parameters>
Content of widget
</$widgetname>

Notice how it is similar but different to html

The result of each widget depends on its design and the parameters used. They are tiddlywiki specific, somewidgets can be used inside other widgets as wiki text and html can also. All widgets are documented at tiddlywiki.com. one of the key features of widgets is the use of filters to select zero, one or more tiddlers, tags, fields and field values eg listWidget. Including setting the value of "variables" eg setWidget.

These selected values and other variables can be used inside the content of each widget and often in widget parameters or even html.

Another form of variable is the macro defined with
\define macroname(optional parameters) values parameters variable and widgets on one line
Or
\define macroname(optional parameters)
values parameters variable and widgets on multiple lines
\end

Never leave \defines empty or you get strange results.

A variable or macro defined can be used anywhere in a tiddler or widget where it is defined or globaly when in a tiddler tagged for macros.

Widgets most often introduce the kind of functions or processes you may have used javascript for (but cant), however they are also aware of tiddlywiki specific features, and will refresh based on changes elsewhere in your wiki automatically. Update or tag one tiddler anywhere and it will update all tiddlers and widgets that are currently displaying something with the change you just made.

Widgets form the processing heart of tiddlywiki.

But then there is more... Look into text references and transclusions to access information from throughout your wiki and include it in tiddlers, wikitext, widgets, macros.

Everyone of these things tiddlers, references, links, transclusions, wikitext, widgets, macros can be inside each other and many levels deep. All you need to avoid is biting your own tail, including something inside itself such as you get a transclusion error or infinite loop.

I hope this helps, because it would have helped me at the beginning.

Regards
Tony

Posted from a mobile without code highlighting, I will edit in the forum post.

[S. S.]

TonyM - thanks for getting it started!

The question asked was: can you please give me a simpler explanation of what is meant by "a Widget"?

I was hoping this would be an easy question to answer for experienced users.

This is what I have so far ...

Widgets form the processing heart of TiddlyWiki.

Widgets can be considered TiddlyWiki's personalized extension of HTML, to perform tasks specific to the needs of TiddlyWiki's user's needs and experience.

They are used for tasks such as to:

•     create variables and complex short cuts (macros)
•     create buttons, check-boxes, and radio buttons
•     create, delete, modify, open & close tiddlers
•     edit text and images
  
•     display and manipulate your material (such as text, images, videos)
  
•     display and move to specific areas
  
•     ??
•     and much much more

...

a little help would be appreciated !

Thanks

[@TiddlyTweeter]

S.S. & Tony M.

As far as "widgets" go I have a specific view as an idiot.

I need (1) simple examples; (2) more complex examples that build from 1.

I think you begin to understand them better when you SEE them working.

My tuppence.

Josiah

[S. S.]

Thanks Josiah!

I was thinking more of just an introduction, so as to make a newcomer curious to know what all they might do and how they could be used, and to not go into a daze when seeing the word Widget - like I did when I first read it.

Perhaps starting with something like .......

They could have been called "Tools" or "Elements" or "Identifiers" or "Commands", but in TiddlyWiki, they are called "Widgets"

...

... ???

[TonyM]

Yes,

My answer was complete, not easy, however I belive from my answer we can generate simpler descriptions similar to yours. Perhaps we leave out intermediate things like variables as they are a means to an end eg; widgets help you
Display images, video and audio
List information
Organise information automaticaly
Display and edit dates, text and numbers
Build forms reports and documents
Build interactive websites.
Etc...

Regards
Tony

[Jed Carty]

Widgets are the active elements in a tiddlywiki.

CSS and similar things can change the way the wiki looks but they react to the environment around them, widgets act on their own (or to user input for buttons and similar).

[Mark S.]

A widget is markup text that, if you're familiar with HTML, works identical to that of an HTML tag. Except that the widget has special TW powers. It's form looks like this:

<$thingy atrribute1=abc attribute2=xyz >Sometimes stuff goes here</$thingy>

If you had a widget invoked as <$thingy> then it would be referenced as ThingyWidget in the TW documentation. This is good to know when looking up documentation.

Widgets perform most of the heavy lifting in TW, including listing tiddlers, creating tiddlers, renaming fields, exposing tiddler contents, running macros.

Be careful not to confuse Widgets with WikiText (reference to WikiText). WikiText is a special markup that secretly, behind the scenes, is actually creating and invoking Widgets. For

instance, this wikitext for transcluding a tiddler:

{{myTiddler}}

is actually wikitext shorthand for

<$transclude tiddler="myTiddler"/>

It's important to keep the concepts of WikiText and Widgets separate in your thinking. WikiText can be used inside of Widgets, but Widgets can not be used inside of WikiText.

That is, you can do this:

<$transclude tiddler=<<mymacro>>/>

but you can not do this

{{<$transclude tiddler="mytiddler"/>}}

.....

.

[S. S.]

It's taken a month of on-and-off giving it some attention.

Here's the result!

Widgets for Beginners

Feel free to thrash it and make it better by leaving some critical comments.

[Mohammad]

Hello S.S.

Great stuffs.

Is there any sidebar Contents for these new materials? or is it https://00ss.github.io/documentation/tiddlywiki.html#Widgets%20for%20Beginners?

Keep going on.

Cheers

Mohammad

[Jeremy Ruston]

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

--
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 tiddlywiki+...@googlegroups.com.
To post to this group, send email to tiddl...@googlegroups.com.
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/b86ff0f5-f9fb-478c-bbd7-4cdda2124a07%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[stefano franchi]

Great work S. S.! Super-helpful to anyone just getting into TW.

And many thanks to Jeremy for the technical background. I am still wrapping my head around the design of TW and texts of this kind go a long way toward making it clearer.

Cheers,

Stefano

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.

--

__________________________________________________
Stefano Franchi

stefano...@gmail.com
http://stefano.cleinias.org

[S. S.]

Mohammad,

For now I am keeping all the Introduction Level Beginner material at: https://00ss.github.io/help/Adding-a-table-of-contents-to-the-sidebar.html - and it is regularly updated with all changes. I estimate it is about 57.5% done.

To put them all into a master TiddlyWiki ( like at tiddlywiki.com ) requires some changes to Documentation macros and their styling, for which I have not received any feedback yet on github issue #3711.

Also the naming style of the material needs to be finalized. There was some lively discussion on GG tiddlywikidocs here: Beginners help for Table of Contents

Jeremy suggested the 1st style, and I preferred the 2nd :

1. Widgets - an Intro
2. An Intro to Widgets

There is also a stumbling block of how best to present the material being discussed on github issue 3664. This issue also led to Joe Armstrong's post: Named story rivers (or trails)

An important step is my submitting the issue - Introduction set of Documentation - on github - which I am not yet ready to do.

I don't see much point getting the material properly named and formatted so as to be ready for merging into the master TiddlyWiki till enough discussion has taken place on the above types of issues, so that decisions can be made based on them.

There is still time, as we all have to go through each Intro tiddler to check it properly addresses a new user's needs.

Regards

[Mohammad]

Hi S.S.,

Many thanks for clarification. I found theme really useful not only for beginners but also for advanced users.

I think Tiddlywiki features and capabilities have not been demystified and this wonderful resource is a great step in this way.

I follow your updates.

Cheers

Mohammad 

[S. S.]

in the tiddler : Widgets for Beginners : there is this line

It's important to keep the concepts of WikiText and Widgets separate in your thinking. WikiText can be used inside of Widgets, but Widgets can not be used inside of WikiText. Try and remember this rule, as it is a stumbling block for all new users.

Is this actually the right way to phrase the warning? I need help to phrase this more accurately. Below is my (probably wrong) attempt:

WikiText can be used as an attribute value of Widgets, but Widgets can not be used as a parameter value of WikiText.

Thanks.

[Ste Wilson]

THIS IS AWSOME!

[Jed Carty]

S.S.

I believe you are correct.

Wikitext contains widgets anytime a tiddler has a widget in it, so that part isn't true.

I would make a slight modification to what you said:

WikiText can be used as an attribute value of Widgets, but neither Widgets nor wikitext can not be used as a parameter value of a WikiText macro.

That is unless you use the macrocall widget, which is cheating because it is a widget.

I think that is as accurate as I can make it without going into things like how macros and widgets are evaluated and I think that falls outside the scope of what you are making.

[S. S.]

This is probably an accurate way of explaining the limitations:

WikiText can be used as an attribute value of Widgets, but neither Widgets nor WikiText can be used as a parameter value of a WikiText macro.

... but it would be almost impossible for a beginner to understand. That is something to be avoided.

I don't know how to phrase it in a simpler way.

Maybe just a more general warning of some sort - without being too specific - and then a link to a NEW (non-beginner) tiddler that explains it with some examples.

So I still need help with how to phrase that General Warning.

Thanks

[Jed Carty]

I think that this is something that would be best explained with examples. You could have the statement there as well and then have some examples to show it and link to a tiddler with a more in-depth explanation for people who want it.

Something like:

This works:

<$list filter=<<SomeFilter>>>

</$list>

this doesn't:

<<list-links <<SomeFilter>>>>

and put in some more examples and maybe a quick explanation of why, like the one that doesn't work is trying to use a macro calling a macro. I think that it would be ok to have only one or two examples on the main part and then link to more examples for people who want them.

In this sort of thing I think a good general design principle is to start with the shortest and simplest, or most direct, explanation possible and then let the person reading it decide if they want more by giving links to more in-depth explanations and examples.

Unfortunately saying that is easy, making something that is that way is the hard part.

We could add something like 'as a general guideline, if it starts with this <$ it can have this << inside it and not this <$, but if it starts with this << it can't have this <$ or this << inside it.'

[TonyM]

Jed

 or better yet

<$macrocall name=list-links param=<<SomeFilter>> />

After identifying the name of param.

To all

In relation to the overall thread, the emphasis I believe should be placed on the fact wikiText is "evaluated" before Widgets are actioned, or we would not be able to feed widgets with changing variables as in the above example 

<<SomeFilter>>

 must be "evaluated first" to allow its result to be passed to the widget.

Thus when we say

<<list-links <<SomeFilter>> >>

What is to be evaluated first?

<<list-links <<SomeFilter>> (notice we open and close "<< >>")
<<list-links >> then <<SomeFilter>> illogical
<<SomeFilter>> then <<list-links resulthere>> that is what we mean is it?

So this example 

<<list-links <<SomeFilter>> >>

fails to be clearly defined because something needs to be evaluated before the whole is evaluated.

Arguably Tiddlywiki could be designed to tear this statement apart, and deal with the nesting implicit in this, however why do all that when you can turn it into a widget call and have the parameters evaluated before calling the widget?