There was a suggestion in a now closed issue at Github, which imo should still be considered about Images nomenclature in the docs.
Please update the top wiki post if there is something actionable. If it needs further discussion please post it as a new topic.
@twMat see this section in the top post (in reference to Update Filter Run Prefix (Examples) by twMat · Pull Request #7052 · Jermolene/TiddlyWiki5 · GitHub)
Added a note that the tiddler Pragma does not list the new in v5.2.4 parsermode pragma.
Bumping for greater visibility.
Ka-bump
It’s unclear whether we should edit this old wiki post, or reply.
I worry that an edit will get lost at this point? At any rate, here’s a documentation hole I discovered today, while confirming details about the edit-text widget here: https://tiddlywiki.com/#EditTextWidget
The inputActions attribute is described in the table of attributes…
Introduced in v5.1.23 Optional actions that are triggered every time an input event occurs within the input field or textarea.
Introduced in v5.2.1 The variableactionValueis available to theinputActionsand contains the value of the input field.
… But users don’t get any examples of how those actions work. Searching for inputActions — as well as actionValue — yields no further help.
Maybe we should consider keeping this information directly in tw-com? Similarly to how Wikipedia and its derivatives have flairs or banners on top of articles needing major work. E.g a tag or field with a concise comment about what is wrong.
Advantages:
- Easier to manage in the long run, since everything is in one place, lower risk of something getting lost or forgotten
- Viewers of tw-com get a hint that something is missing, better than nothing
Disadvantages:
- Marking a tiddler as “needing work” requires a GitHub commit (though not so difficult with PR Maker) and merging by Jeremy
1 Like
I see the logic of this, and most people suggesting edits/additions are power-users who would be familiar with how to do this. Although I have a github account, I would need a handy reminder about how to flag something at github. (Seems my github learning curve needs to start from scratch once every year or two, lol.)
It seems there are two kinds of cases (perhaps with a bit of shading in between):
(1) I suggest THIS particular edit (fix)
(2) I notice this problem/gap, but I’m not able to formulate the fix myself.
I would only rarely have suggestions in category (1). (Today’s note is definitely trying to pass the baton to someone with a clue about how to fill in the details. 
)
Maybe this wiki-thread here can serve as something like the starting-point of a collective bucket-brigade, and folks who know more can grab a “to-do” issue from the wiki above (even if expressed in novice-user form), carry it to the next step at github, and then cross it off here?
Could you elaborate a bit more on what type of examples you would want? Any action string will work, and if you need the value of the input field it is available in a variable. Or rather is it more about providing examples of where these actions could be useful?
Unfortunately this a personal shortcoming I run into sometimes, where something seems so self explanatory to me that it makes it difficult to to explain it to someone else, the same way that I find it easier to teach calculus than to explain why 6 divided by 2 equals 3.
Right, this is a case where something seems obvious to you, but not at all to me. To say “any action string will work” is to assume that people know what exactly an action string is, how it plugs into the widget-call, what makes a string a single well-formed action string (even if it bundles together multiple actions, as is implied by the plural in inputActions), etc.
When I ask “how it works,” the issue is on both of the fronts you ask about.
(1) I’m not exactly sure how the nuts and bolts connect, syntactically. And I’m wary of going down the rabbit hole of messing with it, troubleshooting why it’s not doing what I want (which could be misguided from the beginning), and giving up. Should I assume the inputActions string must have quote marks around it? (And triple quotes if there’s any risk of quotes internal to the action string?) Does it need to refer to a variable defined outside the widget? Could it be itself determined by a filter condition or field reference?
This risk of going down a rabbit hole of guessing what good syntax looks like (for this attribute) is even more unattractive because …
(2) I’m not sure what’s at stake, what’s to gain… How did the edit-text widget become more powerful when it became possible to specify an action string? I have ideas, but they could be very naive! Would I be specifying an action that will happen whenever I interact with the field, with each keystroke (or conditionally on only certain keystrokes, as in the example that @etardiff just shared for the keyboard widget)? (Could I make a sound play on each keystroke, or each keystroke beyond my desired length limit for the edit-text content?!) Or am I specifying how the contents of this field will interact with an existing action widget that … encloses this edit-text widget?
It feels like an insider’s level of fluency about matters like this affects a great deal of the documentation. That is fine for the “getting it down” phase of any project, but translation for “the rest of us” will avoid lots of perplexity.
Surely you agree that a string like actionValue — a rather technical-sounding term! — should at least be defined somewhere in the documentation, if it’s used at all? Is this a synonym for “action string” as you used that term in your post? (But I’m revealing that even “action string” isn’t super-clear to me in terms of how it plugs correctly into widgets etc.)
When I don’t have a simple example to start with (copy-paste-tinker and learn from) I don’t even know if I’m asking coherent questions.
If I myself find it intimidating (as someone who’s been tinkering with TW since 2005 or so but who also is very much a hobbyist with a totally different dayjob), I worry about the experience of someone with less experience who isn’t connected to this community.
1 Like
Thank you @Springer, I genuinely appreciate the insights from your perspective.
I would like to follow up with some thoughts around comparing and contrasting to other widget documentation, to understand how much of this applies in that context as well and how much is specific to this particular piece of documentation. However it will need to wait a little bit as I am struggling with an inflamed shoulder capsule that has worsened in the last few hours, and is even hindering typing at the moment.
That’s a good question. I think with almost any widget, there are attributes that are more intuitive, and ones that are less so. I’m happy to poke around a bit and see where I notice relative perplexity zones. 
Yikes! Do please take care of the shoulder! All of this documentation wishlist is nothing compared to good health!
\define onInput()
<%if [get[temp]match[springer]] %>
<$action-confirm $message="hello springer!"/>
<% else %>
<$action-confirm $message=<<actionValue>>/>
<% endif %>
\end
<$edit-text inputActions=<<onInput>> field=temp/>
Drop that into a new tiddler at tw .com.
1 Like
Thanks, @CodaCoder
I suspected it might require an action defined outside of the widget itself. Whether or not that’s technically true, your example shows the power of it. Clearly it would be possible to have a sound play with every keystroke, or have a buzzer sound only once there are more than 8 characters, etc.
Surely. Being a dev myself, I can assume what they do… but even then I had to try them to be sure my assumptions were correct.
So they follow the spec (AFAICT) for Element: input event - Web APIs | MDN i.e. (UI Events). All of which means…
You’ll get an input “event” (IOW your action string will be called) for every user-initiated change to the input element (yes, per keypress, as you type) — but notably not changes made via other means, e.g. JavaScript – and without the value needing to be committed (i.e you don’t need to hit return). The example I gave makes this tediously clear
What’s not made clear (above) is that this mechanism is working with the HTMLInputElement .value property, not its value attribute (though you don’t specify that directly in TW anyway).
1 Like
That, ladies and gents, is UX. UX belongs to the user, an embodied experience taken as a whole while using the product/service.
In my other life, I go on and on about this, having to cut away the fat from a lot of online BS about this topic:
“Wow, that’s a great UX!” No, that’s a UI.
“I’m a UX designer.” No, you’re a web designer (if anything).
“We improved the UX.” How? And where’s the feedback? Feedback will “prove” the user experience is good… or not. See https://www.youtube.com/watch?v=9BdtGjoIN4E
@Springer: can I have permission to cherry-pick your text for use in my day job?
1 Like
Bumping this thread. I’ve gone through the wiki list at top, and found a bunch of cruft (stuff long since resolved), and initiated a couple PRs myself around easy fixes (see post below for encouragement to step up and try it).
I’ve set up details widgets around each unresolved issue in the to-do wiki at top. Let’s keep it super-easy to see the big picture of to-do requests. You can decide which details you’re curious about, and open the details as needed.
Issues that seem resolved, to my eye, I moved from the first wiki post (the “to do” list) to the second (resolved).
Having the new v5.3.4 released, this is a great time for us to pull together and see where the documentation is still in need of repair.
Despite some of my own posts earlier on this thread , this thread should stick to straightforward fixes within existing documentation tiddlers and/or super-clear small additions — “low-hanging fruit” that someone with a spare bit of time (and access to GitHub) can patch up.
For issues that require significant new technical text — or coordinated decision-making and judgment calls — my understanding is that such issues may warrant a separate discussion thread.
2 Likes
Let me add also:
As someone who is NOT super-fluent in GitHub, but who does have account there, I want to encourage other documentation bench-warmers to get off the sidelines.
It’s refreshing to shift from just complaining here 
to actually fixing the stuff that’s easy enough for me to fix 
. (I’ll still raise issues here when the “how” of the fix is too hard for me.)
You, too, can help improve documentation! 
If you invoke edit-mode for a tiddler at tiddlywiki.com, you’ll notice there are TWO alternate methods suggested in a strip along the top. Both require a GitHub account, and the docs-pr-maker also requires a one-time GitHub token (which requires only a couple extra clicks).
I’ve now tried initiating a PR through each method. Compared to editing the GitHub code directly, I find the docs-pr-maker approach to be more powerful and intuitive:
- You can see right there (in a cloned tiddlywiki.com interface) how your revised code will look
- You can save a draft if you’re not ready to finish your suggestions all in one sitting.
- You can make related edits to multiple tiddlers as part of one request. (Still, you should not bundle edits that are not related, so that the approval process remains granular.)
- Once you submit, you’ll get a link that enables you to return to your PR request and make further tweaks, which does not seem so easy to do from within the GitHub commit process.
On the whole, this docs-pr-maker approach helps you feel confident about putting your suggestion into the approval pipeline.
Thanks to @saqimtiaz for setting it up and empowering the community this way!
4 Likes