TiddlerWidget - formulate what it does!

[Mat]

Another thread made me realize I've never used the TiddlerWidget and that I probably should.

The Introduction in the docs on TiddlerWidget reads:

The TiddlerWidget sets the current tiddler that applies for processing its content.

IMO this phrase is not easily understood. I'm wondering if the following is a clearer (and accurate) description:

The TiddlerWidget sets a title to be the regarded as current tiddler within the scope of the TiddlerWidget.

Makes sense? Any better suggestion?


<:-)

[Jan]

Hi Mat,
I think you are right, that explains it much better.
It would be important to link this information in the documentation of macros and transclusions, because it is there where most problems regarding this occur.

best wishes jan

--
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/9a50ee73-4a3e-42ad-963d-8a0a5d4711dd%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[PMario]

On Thursday, February 16, 2017 at 9:12:42 PM UTC+1, Mat wrote:

IMO this phrase is not easily understood. I'm wondering if the following is a clearer (and accurate) description:

The TiddlerWidget sets a title to be the regarded as current tiddler within the scope of the TiddlerWidget.

I'm sorry, but this doesn't make more sense. At least not for me. IMO we can't explain it on one sentence.

currentTiddler is a variable, that is used by various core functions and the UI, to show widgets, what's the current "scope" to work with.

So functions like {{!!tags}} which is the same as: <$/transclusion field=tags/> know what's the default tiddler to use, if there is no tiddler=xxx parameter.

The list-widget would need to look like this: <$list filter="a b c" variable=currentTiddler> ... scope ... </$list> everytime you use it. ... This isn't convenient and very error prone. That's why there is a default for many parameters, that widgets use. In the example, the list-widget basically is a loop where currentTiddler is set to   a, b and c  sequentially.

The tiddler widget does the same thing, without the loop. It sets currentTddler within the scope.

<$tiddler tiddler=test>  ... scope ... </$tiddler>

That's it.

-mario

[Mat]

@PMario,

I'm hoping we can improve the Introductory part of the TiddlerWidget docs. That part of widget docs is typically brief - a sentence or two. So, while I agree a greater sense of understanding would require more context, like what you describe, I'm thinking we should still aim to keep it limited to only what the very TiddlerWidget does. But, still, maybe an off-handed mention about what the current tiddler is can pass;

The TiddlerWidget is used to set a value for the current tiddler variable, valid within the scope of the TiddlerWidget.

Better? Maybe we shouldn't even call "current tiddler" that but instead "currentTiddler" which at least to me more clearly shows what it is, i.e a variable (...or is there a conceptual difference between "current tiddler" and "currentTiddler" ? I don't recall ever seeing "current tiddler" used in actual wikitext?)

<:-)

your reply seem to be more about what "current tiddler" is than what the TiddlerWidget does - ?

[PMario]

On Thursday, February 16, 2017 at 11:41:36 PM UTC+1, Mat wrote:

The TiddlerWidget is used to set a value for the current tiddler variable, valid within the scope of the TiddlerWidget.

Better?

For me. .. Yes.
-m

[Mat]

Thanx. PR'ed.

Thank you also to Jan.

<:-)

[Douglas Counts]

Descriptions like what PMario just included should be what one finds within the introductory developer documentation, that is currently lacking in useful examples and basic insights.  Doing a Google search on most TiddlyWiki Widgets normally leads you to a Google Groups post and not to the formal documentation.   

The documentation on Widgets, for example, confusingly states, "Widgets are analogous to elements in an HTML document."  What?!?!  That sounds like widgets are simply nodes within an internally used DOM domain which conceptually are not what widgets are.  My current understanding is that Widgets are better understood conceptually as commands within TiddlyWiki's own Domain-specific language.  I'm not saying that these commands don't affect the browser's DOM or how tiddlers get rendered, but that conceptually, they are not the same thing.

The Widgets documentation even goes on further to confusing use the term "element widgets." But when you search for the term "element" at either   tiddlywiki.com or tiddlywiki.com/dev/ you will find no reference to the term used to explain what a Widget even is. Much of the documentation appears to be written from the perspective/context of being intended to be used solely as mental reminders to that same author that already possesses a comprehensive understanding of how TiddlyWiki functions internally.  

Personal perspective is not the best perspective/context in which to write documentation to an audience that doesn't share that same deep understanding.  Personal mental reminders about a complicated subject are great for one's own personal use and consumption, but place huge barriers of entry to those new to TiddlyWiki development.

Perhaps the developer documentation should add a tiddlywiki.com/beginnerdev documentation site that targets developers new to TiddlyWiki development.  

Thank you,

-Doug

[Lost Admin]

Speaking as an end-user who recently (about a year ago) started using TiddlyWiki, I would like to say that Neither the original sentence nor Mat's first attempt made any sense to me. It was only after reading PMario's explanation that I think I now understand what the TiddlerWidget is used for. I doubt I would have understood Mat's second statement without having read PMario's explanation first.

To give you a little background of where I am coming from as a user, I used to be a software developer in the 90's but now I only get to dig into software as a hobby. I use TiddlyWiki as I imagine it was intended, a convenient way to take notes and organize my ideas.

[PMario]

:)

Yea. .. The main problem is, that widgets are the primary building elements for TiddlyWiki. But they weren't intended to be so visible to "end users" as they actually are. But they where there first. Including some basic docs, for every single one of them.

----------- "off topic" -------------

The initial goal was, to have macros for users. eg: <<list-links>>.

where: <<list-links filter:"[tag[HelloThere]]">> ... creates an unordered list
and: <<list-links filter:"[tag[HelloThere]]" type:ol>> .. creates an ordered list.

This user macro was created + documentation. Where creating usable docs, most of the time is much more work, that creating the macro!

The immediate user response was. ... That's nice, but I want to create a table and no list. ... How do I do that?

We should have created a new macro eg: <<list-table>> ... + docs ... Where creating a simple macro may need 15min plus docs 60+min. ... So what does every developer do?

Post something, that is built in 5 minutes and no docs needed. Since the list-widget already has a doc and the user is happy, with the stuff that works for his/her usecase.
It mixes pure HTML and widgets ... It's much more complicated than macros, but much more powerful and flexible.

<table>
  <thead>
    <tr class="evenRow"><td align="left">title</td><td align="left">info</td></tr>
  </thead>
  <tbody>
    <$list filter="[tag[HelloThere]]">
      <tr class="oddRow"><td align="left">{{!!title}}</td><td align="left">{{!!description}}</td></tr>
    </$list>
  </tbody>
</table>

The main advantage of the above code is, that someone else maintains the html-table docs. Mozilla in this case.
Styling with CSS is also documented by someone else and highly standardized.

So the user is happy and the developer is happy. ....

As I wrote, it would be trivial to put the above code into a macro, _but_ .. creating the docs takes time, which is OK, if there wouldn't be something called: "maintenance". ... Maintaining and expanding the docs, is close to impossible for only one person!

IMO that's the main reason, why there are only a view "sofisticated" macros (eg TOC) and a lot of "html - widget" combinations out there.

just some thoughts.

have fun!
mario

[Arlen Beiler]

That and no easy way to share macros... besides...WikiBooks, GitHub gists, GitHub wikis, Reddit wikis etc, Shared Dropbox pages, federation etc. And pretty much everything else we haven't used yet.

What if Jeremy would enable the wiki feature on the TiddlyWiki Five GitHub repo and let anyone edit it?

--
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+unsubscribe@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/284f8d41-e10f-40fa-bd1a-df8d870a66cc%40googlegroups.com.

[PMario]

On Friday, February 17, 2017 at 8:31:15 PM UTC+1, Arlen Beiler wrote:

That and no easy way to share macros... besides...WikiBooks, GitHub gists, GitHub wikis, Reddit wikis etc, Shared Dropbox pages, federation etc. And pretty much everything else we haven't used yet.

What if Jeremy would enable the wiki feature on the TiddlyWiki Five GitHub repo and let anyone edit it?

If you want to edit the github wiki, you can also create pull requests, for the "real" content.
-m

[Josiah]

Ciao PMario

Fascinating thread. I perhaps read it a bit different than others.

I find you "hit a nail on the head" about it not being intended to be that visible to "end users".

My question is: WHO are the "end users"? :-)

I hope its not just only the people here in this group :-). Lovely as they are.

Best wishes
Josiah