@nikosdion thanks a lot - and I will label this also for accessibility.

Although d-none hides the description visibly and from the accessibility tree it does not work as you expect in this situation.

Because the field has an aria-describedby that point to the description the screen reader will always announce it. Obviously that is not your intention.

@brianteeman What is the correct way to prevent it from being announced by the screen reader? Should I remove the aria-describedby attribute from the control?

Clarification: Should I remove the aria-describedby from the control when the description is visually hidden and add it back when the description is visually displayed?

oops deleted my comment as you worked it out. I think thats the only option (but could be wrong)

Is it intentional to have an empty class

@brianteeman The empty class is added by core code. Apparently it's intentional. Doesn't make sense to me either.

OK, I will work on toggling aria-describedby.

Personally I would position the button on the right hand side with the options and help buttons

To do this you will need to edit

I am willing to spend the time necessary to go through the entire backend and write concise help text.

and I am willing to rewrite the text into understandable english. Unfortunately @nikosdion just like my brother-in-law who is also non-native english speaker with excellent english you write in a very correct way but one that is not how real people read & write.

This one for example requires a very high reading level

Surrounds text generated by language strings in ** (two asterisks). Corollary: text not surrounded by two asterisks is hard–coded in your view template files or template overrides and needs to be converted to language strings to become translatable

Please, do simplify my English. FWIW that's the level of English we speak at home and matches the level of Greek I normally speak. Corollary: our daughter is picking up vocabulary in both languages beyond her age ?

FWIW that's the level of English we speak at home

Don't forget that many site builders will keep the site in english because that is what their clients even though their own level of english is not at such a high level

I've checked "corollary" about 4 times in the dictionary and I'm still not convinced it is the correct word. However it can be just deleted and the sentence still makes sense.

In general I like the idea of a single show/hide button when I first visit the page but it does have some drawbacks

1. We can fall into the old trap of adding a description for everything
2. You don't know in advance if there is additional information
3. You have to move away from your focus to enable the extra information and then navigate back to read it. Try doing that with just your keyboard and not a mouse and you will see how annoying it is.

Perhaps a solution to the above is to add, in addition to the page level display, a field level display just for that field

@brianteeman These are valid points and I had considered them. I am glad someone finally asked about the choice of interface ?

I was trying to find a good way to not get in the way of expert users while providing lengthier context for the newcomers and those who could use a refresher — count me into the latter, I couldn't remember off the top of my head what Default Access Level was about, I never had to touch it.

I approached this form the same way I observed users approach every unfamiliar page during user testing. They scan the page top to bottom, most of them without even touching the mouse. That's why I put the button at the top of the form and not the bottom. The typical use for those who need the inline help the most is to first click on that button then move their pointer towards form elements. People who get lost midway through a form will indeed have to lose focus but it's the least likely use case... except for us experienced users testing this PR.

It is true that people will feel the urge to add useless descriptions everywhere. This can be primarily solved by means of a solid beating... um... I mean by us here patiently explaining to them that no description is better than no description i.e. a description must add value by either explaining something newcomers might find challenging / not know at all or conveying hidden / abstract / non–obvious context for this option. Ideally, we should have a UX research team do user testing but as I alluded to in the discussion that preceded this PR I keep my hopes low for realistic reasons (there is no budget to hire someone and we have already spent the good–will card with the UX community). As a result we aim for the best result possible with the conditions on the ground.

Regarding the suggestion for the help mark, I was reluctant because it requires keeping tabs on the global state of the form (help shown/hidden). I can definitely make that happen if we are willing to make a reasonable concession: if the user clicks on every single form field's help icon and sets them to the opposite state than the recorded global then the first click to the Show / Hide Inline Help button will appear to do nothing.

What I mean is this. A form is displayed with no inline help. There are, say, three fields with inline help and the user clicks each and every one of them to show the inline help. At this point the recorded state of the inline help is “hidden” but the visible state is “shown”. Clicking the top button will set the recorded state to “shown” and show all fields... which are already shown, therefore nothing will seemingly happen. Trying to divine the global state when clicking each individual show/hide button may have a detrimental performance impact on longer forms, e.g. the Global Configuration.

I'll try to implement it without the concession but if it takes more than a dozen or so milliseconds for the DOM to respond I'll apply the concession for pragmatic reasons. Does that sound fair?

Another question is whether we are talking only about settings or also about editing views?

I know that for many the editing views help is useless, but as I've written more than once, it can be essential for newbies. Like in cases where a second parameter is referenced to some other parameter.

J4:

J3:

Of course, it occurs to all of us when reading the help that it is obvious that the "Show Category" must be set to "Show" in order to apply the link. But that will occur to us when we see the help. Without the hint, we may miss/overlook the second parameter and then have to guess why the "Link Category" parameter doesn't work. And I'm talking about people who already have some experience with the system, not people who are seeing it for the first time. Newcomers may have no idea what "Link Category" means at all.

@PhocaCz Definitely also for edit views. That would be Phase III of further work. I forgot to write it down. I'll make an edit in the PR's description.

(i am refraining from further comments on the text you have suggested and treating it as lorem ipsum while the feature is developed)

You can make comments on the text. If I start working on other components I would be following the same philosophy for documenting. I know there are a few options you think the text is useless but I have reasons to believe it's not. If we address this here, now it will be easier to come to a consensus.

i dont want to distract from the code part. one step at a time

@brianteeman You can email me directly. The faster we come to an agreement about what needs to be documented and how, the more likely is we can help Joomla users before the Joomla 4.1 merge window closing on December 18th.

@nikosdion I am offline now for 24 hours due to jewish holy days

Understood :)

A few days ago you asked me to place a help toggler in the label itself. I decided to NOT implement it and I can tell you why.

There were several options to do that, none of which is right.

Option A. Have JavaScript append it to the label.

This is how I do it in Akeeba Backup, BTW, so I am intimately familiar with this method. The problem is that the JavaScript is now responsible for creating an HTML element with specific attributes. It cannot be overridden by a template. This would mean that this feature would have a hard dependency on Bootstrap 5. While acceptable for a backend product like Akeeba Backup it's unacceptable for a mass–market, frontend facing product like Joomla. So, this is not happening.

Option B. Have the joomla.form.renderlabel layout render it.

On paper, this sounds great. It can be overridden, so it can be made to match the design. If a template developer doesn't want to render it, no problem, just remove that part of the code and go on your merry life, the JS side doesn't care.

This requires passing this layout information about the field description, information which is currently only passed in the joomla.form.renderfield layout. While we can make the abstract FormField class do that in the protected getLabel() method it causes two major gotchas:

1. Any field implementing its own getLabel method — not just the 12 core fields but also any number of third party fields — would need to do the same in their overridden method. This creates a b/c break which wouldn't be addressable until Joomla 5 which may be in a year or in 10 years. We can't leave our users in the lurch for a year, let alone another 10...
2. It creates an unnecessary and invisible dependency between the implementations of the joomla.form.renderlabel and joomla.form.renderfield layouts AND is architecturally incorrect because the LABEL needs to know how the REST OF THE FORM FIELD is set up.

Option C. Append the toggler to the label, but outside the <label> element

This requires only changing the joomla.form.renderfield layout BUT it's wrong on many levels. The toggler is not part of the label which causes layout issues. It's not announced on screen readers as part of the label. It's generally a bad idea.

Option D. Magic label editing

The final option I had would involve editing $label being passed to the joomla.form.renderfield layout. If it ends with </label> (regardless of spaces) we could inject the toggler before that closing tag. This solves the following problems:

• Option A's hard–coded HTML. It is overridable in the layout.
• Option B's backwards compatibility break. Existing fields, core and third party, would still work fine.
• Option B's invisible dependency issues. The entire solution is restricted in a single layout file.
• Option C's accessibility, layout and structural problems. The toggler is part of the label.

However, I consider this solution EVIL because it messes with the content of the label.

Moreover, since it requires using a RegEx search and replace for each and every form label rendered it poses performance issues.

Conclusion

Having considered all the potential implementation approaches there is only one viable, it's evil and it causes performance issues.

Weighing the pros and cons of having a per–label toggler I am coming to the conclusion that it doesn't make sense to do that. Inline help is something the user will need on first contact with the form. If they are familiar with the form they don't need it — that's why it's hidden by default. If they are unfamiliar or need a refresher they will click on the Toggle Inline Help button and proceed to perusing the form.

What we were trying to solve is the far less likely case that someone is halfway through the form and they need some help using it.

What is the interaction we have now, as of Joomla 4.0.3? Stop what you are doing. Move the focus to the toolbar. Click on Help. Oh, great, a popup opens with a freaking novel in it. Try to read through the novel. Forget what you were trying to do. Close the modal. Go back to the form. Ah, right, there's this option three quarters down the form I wanted help with. Repeat and try to skim through the freaking novel until you find its documentation. It's useless. Feel lost and frustrated. Wasted time: about 15' and no solution found to your problem.

What is the interaction we propose instead? Stop what you are doing. Move the focus to the toolbar. Click on Toggle Inline Help. Move your focus back to the field that gave you trouble. Aha! That's what it does. Keep going through the form. Wasted time: 15 SECONDS and you found a solution to your problem.

I reckon that while an imperfect solution — no solution involving a frustrated user reading something can be perfect — it is far better than the existing non–solution, even if the help pages were magically edited overnight to actually document what each option does and what are its implications. With regards to usability, it is marginally worse than tooltips for users who do not require accessibility accommodations and much better than tooltips for users who do require accessibility accommodations.

Overall, having the Toggle Inline Help button solves a multitude of issues for users regardless of their experience level (even Joomla co–founders who run Joomla training businesses are under the false impression that SEF URLs have anything to do with search engines) or their requirements for accessibility accommodations. The critical requirement for this feature to work is having concise, well thought out help text. As I said this CAN be provided and if time and budget permits it can be revised based on real–world user testing in the future.

So let's stop getting distracted with marginal improvements and focus on the fact that we have a real, major improvement in usability staring us at our faces and just freaking include it in Joomla so we can continue making PRs to apply it everywhere else, not just the Global Configuration.

Not commenting or testing any further. Clearly some people prefer to shout and complain and not test things - I won't be wasting my time any more.

I can't comment on the technical aspects of the proposal and so I won't. Nick has provided us with a sound rationale for exploring the merits and demerits of implementing various ideas that may address the primary objective. The primary objective that I understand is to offer novitiate J! 4 users some short, simple, on-page contextual help without having to (a) download volumes of documentation, assuming the documentation has been written, (b) spending too much time sifting through the documentation, (c) becoming frustrated with the lack (or unsuitability) of the documentation and/or (d) spend even more time searching for "help" (e.g. asking questions and wait for replies on their discussion forum of choice).

I really don't mind if Brian has decided to not contribute to this discussion further. The world will move on around him. As I have commenting before, how people accept J! 4 is not a question about the faith that the development team has in the product nor is it a question of how much of a flogging the marketing team must do: market acceptance will be demonstrated by consumer take-up, continued use, acceptance or rejection.

Thanks, Nick. You've done a terrific job. I'm just a simple "user", really, with no "IDE" knowledge; that's above my pay-grade. I can fumble my way around J! 4: I spend a lot of time reading documentation, trial-and-error (a helluva lot of error), and following discussions where I [sort of] get the gist of them. But there are some things I have no tolerances for and characterising people as carping ignoramuses is one of them

I'm sorry that Brian feels that way — though I'm not surprised. I spent my Sunday afternoon and evening exploring his suggestion in good faith, coming up with four different implementation ways and documenting in detail why neither wasn't particularly workable. I could have done a number of different things with my time off but I chose to spend it on this PR because I want to contribute positively to Joomla and help its users.

A lesser developer would simply slap hard–coded HTML elements in JavaScript (Option A), screwing over template developers and Joomla's users throughout the Joomla 4 release. Nobody would have caught it because tests would be successful as they are only based on “does this work on my browser”.

I am not infallible and I'm all for constructive criticism. That said, temper tantrums by full grown men are far from constructive. More so when it's possible to resolve worse temper tantrums my 3 ½ year old has by talking calmly, finding a mutually beneficial solution and moving on. If an adult here feels incapable of showing the same emotional maturity as a preschooler, please, do feel free to excuse yourself.

As an aside, I'd like to note that this is not normal behavior for adults. There is a number of mental issues which can cause it. If you've been around long enough you may have seen that I was doing the same. In my case it was undiagnosed and untreated ADHD. It came to a point where I couldn't function properly anymore. This prompted me to go to a specialist, I was prescribed medication and I can now function better than before, even coping with situations like what I had to manage in this PR's comments. Mental health is important. If you feel you are not yourself please seek help. And fuck the stigma surrounding seeking help for mental health issues. That's my 2 minute aside / TED talk, thank you for listening.

Anyhoo. Can we please move on? Is this something the project is interested in? Should I invest more time in it? I'm all down for it, I just need some leadership feedback. Thanks.

my comment was not addressed at you @nikosdion

can you please fix the conflicts so it can be tested

Dunno why Git was having such a hard time with the rebase. Now it reports ALL files in the rebase as part of the PR. So, I am closing this PR and I am giving up. I don't have the time to redo it and the discussion thus far wasn't exactly encouraging to begin with.

WHAT THE ACTUAL!!!! CLOSING THE PR FIXED GITHUB'S STUPID INTERFACE. Now only my 31 files appear as changed instead of 249 file previously reported ? So, I am re–opening the PR.

WHAT THE ACTUAL!!!! CLOSING THE PR FIXED GITHUB'S STUPID INTERFACE. Now only my 31 files appear as changed instead of 249 file previously reported ? So, I am re–opening the PR.

Thanks, we need it

Hi,

maybe I am somehow lost in this PR. What is the current status? When I apply this patch and run npm now, then I get:

Call to undefined method Joomla\CMS\Toolbar\ToolbarHelper::inlinehelp()

@PhocaCz Something sounds very broken in the patch tester or your site. The method does exist and GitHub does report it as being included:

There are two possibilities here. Either the patch failed to actually be applied on your site OR you have an OPcache issue.

I will go with the former. I was asked to fix the merge conflicts which means that my PR is valid only if applied against a site created with the 4.0-dev branch as of September 27th, 2021 at 9:00 am GMT. Anything older, including Joomla 4.0.3, will make it impossible to apply the patch as the hunk references in the GitHub generated diff file will be wrong and inapplicable.

If you want to test this PR please checkout my branch, run npm ci and install a site from it:

git clone -b feature/inline-help https://github.com/nikosdion/joomla-cms.git pr35610
cd pr35610
npm ci

Sounds like you hit a limitation of patchtester whereby it seems to have a maximum number of files.

I was asked to fix the merge conflicts which means that my PR is valid only if applied against a site created with the 4.0-dev branch as of September 27th, 2021 at 9:00 am GMT. Anything older, including Joomla 4.0.3, will make it impossible to apply the patch as the hunk references in the GitHub generated diff file will be wrong and inapplicable.

No thats not correct for pathctester as it is a crude file copy and not a diff.

What I would recommend if you don't use git is to click on the download Details

Then set your update server to the url displayed

And just update your test joomla install

But... it's just 31 files. Is patch tester really so limited?! ?

But... it's just 31 files. Is patch tester really so limited?! ?

I don't know but as I have seen this before that's my suggestion for the problem

the advantage of the update method I described above is that if its a pr with npm changes then you do NOT need to run npm ci

Then set your update server to the url displayed

Yes, this did the trick, thank you.

Another question is, what we are testing now? Only the Global Configuration part? If yes, I don't get any problems there and for me it works OK, so I can mark it as "tested successfully".

As for the general outlook. In my opinion, this solution is much better than the missing descriptions. It gives everyone a chance:
a) the developer may or may not write the description. If he/she wants to write one,
b) then the user may or may not see the it.

Yes, there may be a small delay when scrolling up to the button, but it's still better than opening popup window and searching help documentation.

This PR works and does what it says. I still dont agree with the length of the descriptions. It would be good to get tests from the accessibility team as @chmst previously ommented](#35594 (comment))

My2Cent: If a field needs a novel for explanation, something is wrong in the feature an this is an issue against the a11y principle (understandable) .

I have tested this item ✅ successfully on 26a6725

I am late to this party and have not been able to test the implementation because I have trouble merging more than 30 files. However, I have read every word of the discussion and completely agree with the objective. I worked on the Help files a lot and tried to improve them but could not help feeling they were mostly a statement of the obvious with not much actual help. So I am willing to help with this project.

Hi, is there any change regarding this issue?

I got a question today about "extended valid elements" in tinyMCE plugin options. What is the difference between "valid elements" and "extended valid elements"?

I really don't understand why "valid elements" parameter includes description and "prohibited elements" or "extended valid elements" not?

This not only confuses standard Joomla users but it even makes others not able to help :-(

I really don't understand why "valid elements" parameter includes description and "prohibited elements" or "extended valid elements" not?
This not only confuses standard Joomla users but it even makes others not able to help :-(

Seems that the answer is one click away...

Seems that the answer is one click away...

Unfortunately, this is too much :-(

But anyway, I clicked once and see nothing related?

BTW maybe another accessibility issue, the Help in Popup does not have any clue navigation, after clicking on some detail info - I was lost without having the option to go back to TOC :-( That's even worse than I thought, now I understand why people are so lost. :-(

BTW can you paste me some info, how did you find this page on screenshot? I am now spending 10 minutes on search but cannot find it. :-(

now I understand why people are so lost

@PhocaCz I'm surprised that ADMINISTRATORS have issues with the backend options. Normal users should never be exposed to these options...

What I'm trying to say is that these options should be known for administrators (or they're not qualified as administrators). Now I'm getting that many devs think that Joomla should be a solution for any not tech-savvy person but with all these options, with or without in place help, that will not happen. The problem is the number of options, NOT if those options have a popup explanation...

My 2c

@dgrammatiko

But maybe you don't count on the fact that there are beginner administrators. Today I just got a question in our community about tinyMCE, which deletes some parts of HTML code. When I pointed out the possibility of exploring tinyMCE parameters, I just wasn't able to tell without help what is the difference between "valid elements" and "extended valid elements". I haven't found the help yet.

This is simply a real world example. We are humans, not machines. So no, I really don't know the meaning of each parameter in Joomla.

The problem is the number of options, NOT if those options have a popup explanation...

The problem here is missing descriptions, not number of options.

The number of options is common problem and there are many solutions for this. E.g. move some parts to CSS (design parameters), skip some parameters and allow template override, etc. etc. But this is another story.

The problem here is missing descriptions, not number of options.

I haven't seen many modern CMS's with popups or other inline help and I've been using most of the new blood out there. I will stick to my opinion that:

• Joomla has options exposed to the UI when it shouldn't
• Joomla has a bad overall UI and some very awkward workflows (unchanged since 1.0 or 1,5)
• The inline help (either this one or the Guided Tour) is a patch that DOESN'T solve the underlying usability problems

Also, I'm not really interested to argue here on others' work or perceptions...

@dgrammatiko

You should understand that standard users just care about completely different things than were changed in Joomla.

They did not ask to remove description, the way how it worked was fantastic in Joomla 3. Users who wanted to get help just had such help in tooltip. Users who didn't want such help weren't bothered with text they didn't want to read.

So there was no reason for change.

But e.g. features which are more than 10 years old, like AJAX save were not implemented. Just imagine, you set up the page and wants to see what happens when you change some option. With AJAX save (BTW it can be seen in Gantry where it works very well), you just save the options and still your position is in current parameter. So you see the frontend and you can easily change the parameter again. This is not possible now, you need to scroll and search the parameter after saving again.

So people just asked completely different features and features which were OK were just removed or changed. Then we can't be surprised that people are leaving Joomla.

People ask:

• AJAX save
• Edit in place
• Select columns
• Filtering options

but not removing tooltips with help.

They did not ask to remove the description, the way how it worked was fantastic in Joomla 3. Users who wanted to get help just had such help in tooltip. Users who didn't want such help weren't bothered with text they didn't want to read.

You're delusional, Joomla was kept losing ground during the 3.x lifetime. Your perception that nothing should have changed because it was perfect is based on your own perception when in reality most of the CMS users have either already moved or planning to move.

People ask:

Where did they ask?
Point me to those issues?

Or is it by people you mean yourself?

Where did they ask?
Point me to those issues?

Or is it by people you mean yourself?

I am a part of Czech, Slovak, German, Russian and many other Joomla communities with over 50.000 answered questions (or more because I don't count answers on emails, chats, phones, etc.). I communicate daily with other developers, with standard users, ... So these questions do not make any sense.

Your perception that nothing should have changed because

Your answers are very manipulative because a statement like "nothing should have changed" is simply a lie.

So if I say:

People ask: AJAX save, Edit in place, Select columns, Filtering options

Then this means, "people ask" and there's no reason to dispute that.

Then this means, "people ask" and there's no reason to dispute that.

I've asked you to point me where in Github (or any other Joomla official channel, Forum, Glip, etc) these questions have been asked. Also if you gather such information/polls/requests and you never open an issue then I guess the problem is not on the maintainers/contributors but rather on you, because you never shared those...

@dgrammatiko Sorry, but I'm not going to spend my time here searching through all my discussions from the last 10 years. You know very well that I publish such things because you often reply to them.

Dimitri, you are wrong. Jan is FAR from being delusional; he is being reasonable and far more patient with a toxic fanatic than he should ever be expected to be.

If you want to see what real world people think about Joomla all you need to do is take a look at the Joomla Facebook group (that's where the TinyMCE question popped up) and the Joomla subreddit. I won't even tell you about the Greek Joomla Facebook group or the Joomla forum because most of the questions there are of such a low quality that would make your eyes bleed. You are also welcome to take a look at the public support tickets and forums of third party extensions and template developers.

You have shown time and again that you deliberately choose to ignore everyone who has a different opinion than yours. You don't care about Joomla users and Joomla itself, you only care about doing things your way. You are a fanatic, not an Open Source developer.

This is our difference, mate. I can do without inline help. I don't mind. I don't need it. I know my way around Joomla(*) and I know how to use Google to make targeted searches for the things I am unclear. For everything I can't figure out I can read the code. I wrote this PR because I have seen people in the aforementioned public discussion places being frustrated with the perceived lack of any help in Joomla that makes it unusable for them. These are the people who are using Joomla. This is Joomla's target audience. It's not the 0.1% of super high experience people like you and me. WE ARE THE EXCEPTION, NOT THE RULE. We want to keep the 99.9% of people who are using Joomla otherwise none of us have a reason of existence and Joomla's dead as a dodo. So I took time out of my business and my family to help Joomla's real world users.

If we're talking about wishes and hypotheticals, I would NOT implement this like that at all. I would make it so that each form field can define a help URL, rendering a help button right next to it. Clicking on it would open the help popup to the exact page and paragraph / item where it is documented (using the not–exactly–arcane power of the anchor part of a URL and id attributes in HTML elements!). It's admittedly more work for us contributing to Joomla but far easier for the user. Opening the help in context does not confuse users. Instead, it lets them read the documentation for the feature they had trouble understanding and the other options around it which might enlighten them in a way they didn't expect. Most importantly, it does NOT detract them from the work they have to do.

Things like that don't take a genius or a fancy degree to know about. You just need to observe people building and using sites. If only there was a term for that... ah, right, user testing. Sounds like we already discussed that and Joomla is simply not interested in doing any.

PS: About my knowing my way around Joomla. You falsely claimed that help for TinyMCE is “one click away”. No, it's not. Are you just trolling? First you click Help. You see a seemingly unrelated page about plugins in Joomla — most people will close that thinking Joomla is broken. Then you need the MAGIC KNOWLEDGE (years of experience) that you need to find and click the Editors Group link in a sea of links. Then you need to click on Editor - TinyMCE in the toolbar which is borderline acceptable. Finally you need to scroll four (4) pages down to find the documentation of the option you were looking for. Three clicks, one piece of magic knowledge and finding a needle in a haystack is FAR from being “one click away”. Yeah, there is something, somewhere but good luck finding it if you don't already know where it is — in which case you don't bloody need to find it in the first place!

@nikosdion just a reminder that I have introduced countless UX/UI features that simplify the workflow and thus made Joomla easier for non-tech-savvy users over the past 6 years. Eg Joomla till 3.4 required users to write {include moduleName} (or something similar) in the editor to insert a module in an article but since #8064 has a simple UI. Later other contributors expanded that same concept and Joomla now has a simple UI for contacts, etc.

My point is:

• you're calling me ignorant of what the non-tech-savvy users expect when I have a good amount of contributions that prove the opposite
• you're calling me toxic because I asked Jan where were those issues (I honestly haven't seen them)

Anyways, it wasn't my intention here to do some irrelevant conversation over what's wrong with the CMS. We might have a different point of view...

@dgrammatiko

But we're not talking about cool new features here. We are talking about cancelling working features.

When I speak:

• with users, administrators - they have a problem to imagine something under the name of a parameter. In Joomla 3 even a small, short description helped
• with the translators - they are upset because their over a decade of work trying to capture the point of the parameter in a short form has been deleted
• ...

If I understand correctly, Tooltips in terms of accessibility are not a problem. Neither is Nick's solution.

We're not criticizing some new feature here, we're trying to find a way to bring back something as fundamental and natural as a short Tooltip.

If I understand correctly, Tooltips in terms of accessibility are not a problem.

Tooltips the way they were on J3 are a huge a11y problem. Getting them to work on a label is also tricky. Nick's solution is ok although it cancels the Guided Tour work (which could have provided the same functionality)

We're not criticizing some new feature here, we're trying to find a way to bring back something as fundamental and natural as a short Tooltip.

I DID NOT criticise anything here, I just said that the help already exists (apparently I lied it's 2 clicks)... So please don't make your own conclusions from my words...

@dgrammatiko

Do you speak English?

Where exactly I wrote about you criticize something? I wrote: "We're not criticizing some new feature here ..." means: I or other with the same or similar views as mine ... nothing about you in this sentence.

Maybe it's because you don't read my words properly that these problems arise.

Just finish the pr and move on

@dgrammatiko

Maybe it's personal, but I'll ask anyway. From your statements, it seems to me that you like modern things, Javascript and speed (page loading, management).

If I tell you that:

People ask: AJAX save, Edit in place, Select columns, Filtering options

Then why you're so upset and want me to prove these things. I mean, these things are supposed to fit your ideas. They are handled by JavaScript, they should be more modern than existing methods, and they speed up the administration significantly. A person like you shouldn't contradict this but rather be happy that people want this.

I don't understand it at all.

Tooltips can be an accessibility concern the way they are implemented in Bootstrap. An alternative way would be to have a help button which opens a modal with the tooltip text which then gets announced but whether that's a UX improvement is hard to gauge because nobody else is doing that and we don't have a user study to back that up.

Another alternative was inline help text but it soon becomes a wall of text for sighted users and for users who need visual accessibility accommodations.

Inline help text which can be toggled for both sighted users and for users who need visual accessibility accommodations is a compromise solution exactly because we don't have the resources to carry out a user study.

I disagree that it cancels the guided tour. A guided tour will only tell you about a few basic features to get you started and, most importantly, how these interact and combine with each other to do something. It cannot and should not drill down to each and every option.

Each thing (guided tour, inline help, documentation) has its own distinct place in a real world user's workflow. You don't have to believe me. Hire a UX team to do user testing. I did for my software and that's how I found out that no, my documentation (which is FAR better than Joomla's) was nowhere near enough. That's how I ended up paying to make video tutorials (that's the form of guided tour people prefer, not the click through type) and how I ended up providing tooltips and inline help in my software. Apologies for trying to apply my knowledge free of charge to the CMS that was butchered by people who did none of that and think of themselves as the absolute authority on everything. Some of us believe in listening to users instead of the voices in our head.

Then why you're so upset and want me to prove these things.

Dude, I'm not upset, I was genuinely asked where was the issue (mainly because I would like to blame myself for not using it when I was fighting for some features for J4).

A person like you shouldn't contradict this but rather be happy that people want this.

Asking where's the issue doesn't mean I'm polarised against it I don't know why you even think I'm against it. The same goes for this PR. That said asking questions or challenging the solution it might be because I might see issues/missed opportunities/etc that were overlooked.

Please stop mentioning me. We are quite rude hijacking Nick's PR...

So you started lying and attacking me and then you write this:

Please stop mentioning me. We are quite rude hijacking Nick's PR...

Are you OK?

and attacking me

Are you serious now?
Where did I attack you?
Asking a question is now considered an attack?

So you started lying

Are you serious now? Do you think that my response one-click away was a deliberate lie?

@dgrammatiko
You lie, you manipulate, you put thoughts in my mouth that I never said and you do it on purpose and you know it because you've been warned about it several times.

@dgrammatiko @PhocaCz could you please calm down a bit, I don't think this is the place for personal fights.

@rdeutz Yes, maybe we can continue here again:
#35610 (comment)

In the light of this discussion if have posted an item on the General Questions forum about a component I have produced to present Joomla documentation in Manual format. It should be of interest to contributors to this thread. For example: all of the Help pages in an easy to find index. Forum link:

https://forum.joomla.org/viewtopic.php?f=808&t=989919

Illustration:

https://github.com/ceford/j4xdemos-com-jdocmanual/blob/master/resources/joomla-manual.png

@ceford: For the reasons put forward by @nikosdion at the beginning of this discussion:

... people behind firewalls (e.g. enterprise), on spotty/slow connections (e.g. rural areas) or high–latency connections (e.g. satellite Internet, most of Africa etc) cannot possibly access the on–line documentation at all. Even if they can and they pay a lot of money (think by–the–minute charges in PSTN or by–the–Mb charges on sat Internet) and wait forever for it to load they will be frustrated and angry at the lack of any usable information ...

I am sympathetic to overhauling and improving the documentation repository but this discussion is about contextual help within the J! backend—the desirability, feasibility and mechanics of delivering contextual help within the J! backend where such contextual help may exist. (I've written earlier in this discussion about the removal of large slabs of contextual help.) ? It appears to me that there are strong views about the desirability in providing contextual help within the J! backend (but not to waste people's time "explaining" the obvious) and there are equally strong views about the undesirability of implementing a toggling mechanism to turn on/off the contextual help text. Further, there has not been a strong appetite to approve of @nikosdion's method which is why this discussion has remained in a torpid state for so long.

good plan

after this PR is RTC we could have three phases:
Phase I: Add help text to the backend core components' Options pages.
Phase II: Add help text to the backend core components' edit pages.
Phase III: Add help text to the frontend core components' configuration (basically com_config) and edit pages.

I have tested this item ✅ successfully on 26a6725

RTC

This really should have a positive test from the accessibility team https://issues.joomla.org/tracker/joomla-cms/35610#event-645267

as per bug squad rule: 2 successful test -> set RTC

let's speed up thing's.. a little bit

No a11y issues found. The challenge will be for translators to write understandable descriptions, which also is part of accessibility.

As the 2 commits after the human tests just changed a language string and code style, I've added back the previous test results, and the RTC status is still valid.

thanks @nikosdion I like the PR and would merge it but since it's a new feature and it's far from complete (x other fields in y forms are missing (your as mentioned in you 3 phase plan) I would please you to rebase it on 4.1.

Never the less I tested it and it works great, 2 things annoyed me a bit.
First, text is to close to the input field.
Second it would be great when then the view position could be the same after toggle. Now if you scrolled down and toggle the inline help you see different fields. Not sure if this is easily possible, a javascript guru may help here.

@HLeithner I'll rebase sometime next week when I have some more time.

Regarding the positioning of the help text, please note that this is controlled by Bootstrap. The margin between the field and help text is a function of the base margin/padding size. Changing that would change the whitespace throughout the entire CMS. I also trust the Bootstrap developers to know much more than us random Joomla folks about UX.

Regarding losing the position on the page, this is not something that can really be addressed. We are showing a bunch of content that was previously visually hidden. Addressing that would require per–field show/hide buttons which is a subpar solution (it's way too tiring; that was the first approach I had tried long before this PR and never made it to production). Besides, if users use this feature so much as for the jumping around to become a problem we would have proved that removing the inline help by default was wrong, this feature would have to be reverted (that's easy!) and have the field descriptions display at all times. I think this won't be the case. I expect new users to click on that button every time they are editing something moderately unfamiliar to them until they get more experienced / confident.

@nikosdion thanks, I'm with you on the BS topic. And ok if you tried it and didn't found a good solution I can live with it. As you say normally you activate it and keep it... at least I would activate it only when I need it on a field so maybe the the common user for this feature.

@HLeithner If you read the discussion above I have already covered it. It boils down to this. If I need help with a field I must be someone who is not familiar with this edit page. It's best to show help for all fields that have help text because I will find out some non–obvious things in options I thought I understood and also because some options may interact and I don't want to click on each one individually to discover how they interact. The more you ask people to click the less they are likely to click anything and the more they are likely to complain the interface is hostile.

@HLeithner If you read the discussion above I have already covered it. It boils down to this. If I need help with a field I must be someone who is not familiar with this edit page. It's best to show help for all fields that have help text because I will find out some non–obvious things in options I thought I understood and also because some options may interact and I don't want to click on each one individually to discover how they interact. The more you ask people to click the less they are likely to click anything and the more they are likely to complain the interface is hostile.

@nikosdion
I think you miss understood me, I think it's better to have one button to activate all at once instead of many buttons or tooltips.
Why I mean was that I have to change one setting at the end of the page and may not know what it does exactly. Then I activate the additional information. But I think it's not a big deal if this change the viewport position like "onshow" does.

To the casual observer looking at this discussion that began two months ago as the result of a fairly major change in J! 4 that saw the removal of a bucket-load of contextual help, and the resistance evident within the J! development community to (a) accept that removing the contextual help has not only made things more difficult but, in fact, is hurting the project, and (b) adopting any suggestions that may alleviate these matters, I'm stunned.

I'm not saying that the facility proposed by @nikosdion should be adopted in J! 4.0 or postponed until later and I'm not saying that the facility is the best idea on the table.

While I agree that, from an accessibility perspective, the use of tooltips over the years has been fraught with problems. Whether or not someone has "normal visual acuity", the fact that contextual help is available within J! is a major selling point (regardless of whether that contextual help is meaningful or not). Sometimes the help text is helpful and sometimes it isn't and, in such cases, the documentation library offers some assistance. However, the fact is that J! 4.0 has not elevated Joomla! in the minds of prospective users.

Over the past few years, J!'s market share has fallen from the second most-used CMS to fourth place and it is likely that it will slide into sixth place within the next couple of months. (That, alone, won't affect my choice in continuing to use J! in my webcraft.) It's unfortunate that prospective new users may be deterred by additional "learning curve" hurdles but it's a shame that J!'s leaders have their own "visual acuity" problems and are blind to the decline.

@sozzled - that comment contributes nothing to getting this merged

The question about why this is being merged in 4.1 vs 4.0 is a valid one, albeit the commentary surrounding it wasn't on topic. Please let me reply as to why in 4.1 and not 4.0 — and why I am more than happy with this.

I am for merging this in 4.1. I am adding a new feature which can be used by 3PDs: inline help can be hidden by default and shown by the user on demand. 3PDs will need to know which version this is supported in. Since it's implemented in XML forms where you are unable to provide a version conditional it makes far more sense to tell 3PDs “Joomla 4.1.0 and later...” than “Joomla 4.0.whatever and later”. They can communicate that more easily to their users, too.

It also gives us a bit more time to apply that code to all core backend components at the very least and even start offering some tooltips. The integration code–wise will be complete by 4.1, tooltips may be added/removed in future minor (4.x) releases. To me this sounds better than rushing this PR through the door and only have com_config support this feature.

When I submitted this PR it was unclear a. when 4.1 would be released and b. if the production leadership is even interested in this feature. Now we know that 4.1 will be released in February 2022 and the production leadership is interested in this feature so let's go full steam ahead! As for the timeframe, no, it's not taking too long. In my experience this is a quite swift turnaround and I'd like to thank @richard67, @alikon, @chmst and of course @HLeithner for working towards this. These people deserve our respect and being told that they are doing good work for free; don't just pile on them out of habit. Thank you.

I've rebased my repo and updated the merge branch in the PR. I am not sure why the tests are failing. Appveyor and Drone say that the PR is not mergeable... but GitHub says it's mergeable. Anyone with more insight...?

Seems drone and appveyor didn't catch the branch change, that's strange. @HLeithner any idea to fix that?

Possibly the issue is caused by the 4.0-dev branch having been a few commits in advance compared to the 4.1-dev branch. If that is the problem, it will be fixed with the next update of the 4.1-dev branch. => Ping @bembelimen : Any plans for the next upmerge?

Seems drone and appveyor didn't catch the branch change, that's strange. @HLeithner any idea to fix that?

seems to work now

I did a quick glance so I apologize if this has been already discussed.

A possible improvement in a separate PR:

Change the question mark icon to an eye/eye-slash to show its state like the Toggle Editor button under Content > Articles.
or
Change text to be Show Inline Help or Hide Inline Help like Expand All or Collapse All button under Smart Search > Filters.

@Quy When this is merged I would agree that these items should be additional PRs. At-mention me when you file a PR for them so I can review them.

Very nice addition, thank you to all contributors and especially Nicholas

@bembelimen Thank you for the merge ❤️

Should I continue working on more backend components? If so, should it be one PR per component?

Also, anyone interested in helping (contributing help text, proofreading, testing) please at-mention me here. We'll figure out how to make it work as a group.

@Quy Now is the time to work on those changes you proposed! Make a PR and I'll review it as soon as humanly possible (this week will be hectic between Black Friday and kid staying home because of a Covid-19 case in her school but I'll try to be responsive nevertheless).

Should I continue working on more backend components? If so, should it be one PR per component?

Yes, would be nice.

Just a quick note that I have not dropped off the face of the Earth and I have not lost interest. Between work, child in preschool (and all the fun respiratory viruses she contracts amidst a pandemic, causing many a near heart attack among us concerned parents), the holidays and fixing other things broken in Joomla I haven't had a chance to work on this just yet. I expect to have some more time next week or maybe even as early as this weekend.

@nikosdion Apologies for asking this here but can't find anything to guide me. How do I add this inlinehelp button to my component config.xml?

@nikosdion found it, will add a solution in JSE. Cheers and thanks for a beneficial enhancement.

This PR had not added the toggleable help for third party components. The PR which added that is #37158 I'm glad I provided the plumbing and people take it further :)

Hello,
In the com_modules of the administration I don't see the description of any fields of the form when the module is edited.
When i take a look i found than the class "hide-aware-inline-help d-none" is present there:

I am not able to found a button called "Show Inline Help" or similar stuff there to revert it. And i dont understand why is hidden by default if it is comming from other config screen to enable or disable it.

No tooltips or popovers working when i move the mouse over the field label

This one before was working fine and now seems crashed.

Can you take a look?, please.

Thank you. Valc.

@Valc Please test #37819 . Thanks in advance.

@richard67 I think the problem is that nobody has added the magic line of XML code in the config.xml file of most core extensions. @cyrezdev added the support for that in #37158 but someone needs to edit these XML files and add the line still.

FWIW I tried that in my own extensions and it works as advertised. If I wasn't in the middle of a veeeeeeeery long PR (TFA improvements) I'd give it a shot but I'm already drowning in work as it is. Sorry.

@richard67
I have tested that #37819 patch on Joomla 4.1.3 and no luck.
After apply the patch some core modules, when edited from admin zone, have start getting the desc text but almost all them still not displaying it. And with my site module no one is displayed when it is edited. In any case no "inlinehelp" button is showed when the module is edited from the admin zone.
When you test your linked patch, for you is working correctly at same locations i am testing?

I have also tried to test the @nikosdion suggestions and, no luck with the issue i am explaining:

Here now is effectively showing the button, and it works perfectly on that page. But, when i "save", all return to default "hide"

Also, no matter if is set there to "Show", when i edit a site module from com_modules, no desc text is displayed.

To test again, i have edited the breadcrumbs xml to add after "config" the same line:

But at site module modules edition no way to revert the default hidden config.

Meanwhile is solved at all why is not set as default to "show" an leave it failing with "hide" status"?
Why this feature is starting as hide by default if it seems there are a lot of task to apply it on all views and extensions than now are hidding the desc?
Regards.

@Valc I see here, your PR #37819 report testing, but not on the concerned PR.
Your edit of config for module edition will have no effect, as not the same way to implement the inline help button in edit view.
I will do a PR for article edition next week, and if time, will start to implement in other core components.

The goal of the PR #37819 is to not change behavior when no inlinehelp toggle button. So could you report your test on the PR for this issue of hidden description ? (and no need to edit any config files to test it ;-) )

Thanks!

@nikosdion I was busy too on my side, but i may start next week to do more integration in core ;-)

@nikosdion question: "descClass" field option attribute is not defined (and not usable as a form field attribute).
Maybe i can add it to my PR #37819 ?

This will allow to use a custom class for description (and to show by default a specific field with descClass="hide-aware-inline-help") .

In a new component edit view I have this in the addToolbar function:

ToolbarHelper::inlinehelp();

And I have added the ..._DESC fields in the xml form files with text in the ini file. It works fine. Really pleased!

My issue is solved with this patch applied #37819 (comment)

@cyrezdev descClass is not a form attribute, it is display data you send to the joomla.form.renderfield layout. This is the default layout for all FormField child classes. You can change it through the $options array of the renderField method of those classes or by overriding the getLayoutData method of that class.

I recommend AGAINST letting the users change it through the XML form file as it will very likely break Show Inline Help for developers who mess with it.

I recommend AGAINST letting the users change it through the XML form file as it will very likely break Show Inline Help for developers who mess with it.

This is what i was wondering afterward...
Do you see any issue with inlinehelp attribute to check about availability of the inlinehelp toggle button as in my PR https://github.com/joomla/joomla-cms/pull/37819/files#diff-2992469037ac7f89c29b3b3c1da6bc564a584f5bc38130455dd2f26b65d2c1a7 ?

@cyrezdev I would not do that at all. The whole point of adding hide-able, inline help was to fix exactly this problem you are reintroducing.

There were too many descriptions, so what happened is that virtually all descriptions got removed to decongest the form. The problem is that unless you are at the very least a moderately experienced user, even the simplest options need some sort of description to make sense.

The solution was to reintroduce descriptions on everything that's not blatantly self-explanatory. This would congest the forms. Hence the descriptions are hidden by default and only shown when you click on the button.

What you are trying to do is UNDO this change by allowing descriptions to be shown despite having the Show Inline Help button. This will lead to congested forms again which will once again lead to the removal of the descriptions, to the detriment of new and less experienced users.

Therefore I am against your proposed change.

Anyway, your change was merged so for all I can tell Joomla has no sense of direction. Each release lead can take an arbitrary decision about the product's UX with zero feedback from users and no oversight. Sigh...

I am agree with what @nikosdion say: if is allowed override this one by field param with a sort of "ignore the inlinehelp" i think will generate the impresion that the button is crashed or not working.

Also, IMHO, if this feature is focused to "decongest forms" but only is suggested really for super admins in "God mode"
If Joomla is "for all" as always is explained, i can not understand how this one is set by default to "hide".
If one is filling he is in god mode i think is easy for that person go to search the button within "options" and check "hide the light", but.. for not God mode users???

I can not imagine if you try to do the same at installation proccess to avoid "forms congest".

Anyway, your change was merged so for all I can tell Joomla has no sense of direction. Each release lead can take an arbitrary decision about the product's UX with zero feedback from users and no oversight. Sigh...

Thank you for your feedback!
And you’re right. I will do a PR next week to remove the possibility to set a form field attribute and focused only on inline help button control if enabled.