Hide–able inline help in back– and frontend forms

[nikosdion]

Pull Request for Issue #35594 .

Summary of Changes

• JavaScript for showing / hiding inline help (a.k.a. form text a.k.a. the description field in form elements) on user's request
• ToolbarHelper::inlinehelp static call to render a “Show / Hide Inline Help” button in the backend
• Example code in com_config's frontend (core configuration only, as a demo) showing how easily the same thing can be implemented in the frontend
• Inline help text in com_config (core configuration only, as a demo), both back– and frontend.
• Necessary language changes

Testing Instructions

** TEST A **

• Go to backend, System, Global Configuration.

** TEST B **

• Go to the frontend and log in as a Super User.
• Visit the URL /index.php?option=com_config&view=config

Actual result BEFORE applying this Pull Request

** TEST A **

Very few options have any text explaining what they do and even these are not particularly helpful. BTW, I left most of them intact to show the contrast between what Joomla currently provides and it can provide with some concerted effort.

** TEST B **

There is no help text. At all. Also, the form is using Bootstrap 2 semantics (yeah, I fixed that because the inconsistency annoyed me)...

Expected result AFTER applying this Pull Request

VERY IMPORTANT: Apply this patch and run npm ci to apply the new JavaScript. OTHERWISE IT WILL NOT WORK!!!

** TEST A **

By default, no option has any help text. However, there is a “Show / Hide Inline Help” button in the toolbar. Click on it. Now you see sensible, concise help text on non–obvious options or options with non–obvious usability, security or functionality/integration implications. Click on the button again. They go away. Keep clicking that button and see them show and hide.

** TEST B **

By default, no option has any help text — like before. However, there is a “Show / Hide Inline Help” button right above the form. Click on it. The two options which need some further explanation have a sensible, concise help text. Click on it again to hide the inline help.

Yes, I know the help under Yes/No sliders has a large top margin. I can't fix that, it's part the bottom margin of the slider. Get someone with better CSS skills to work on it.

Documentation Changes Required

None. This PR is actually providing in–line documentation

Why make this change

Joomla correctly removed tooltips because Bootstrap's implementation has accessibility concerns and a more accessible solution was not found or at least nobody felt inclined to contribute it.

This led to all XML form field descriptions being displayed under every rendered form field, leading to an unwieldy interface.

Since the default language strings were not exactly helpful (basically, the option Enable X had a description of “This options enables X”) they were completely removed.

Unfortunately, this approach made Joomla even less accessible to newcomers. The only source of information is the Help button which leads to the documentation. Most documentation pages are not updated for Joomla 4, novel–length or both. For example, trying to find the documentation on the “Enable Workflow” setting in com_content I read a novella–length documentation page only to find that the documentation for the option I was looking for is literally three dots! This makes it supremely useless for new folks and people who haven't touched Joomla in a while.

Moreover, asking people to go through a long documentation doesn't work. People straight up refuse to read documentation. They don't feel they have the time. In all fairness, most people don't even need it all the time; they just need a quick reminder, a concise description to get a first idea of what this non–obvious to non–hardcore–users setting is or a heads–up about non–obvious implications of a setting. What they need is context! A-ha!

Finally, 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.

FWIW I didn't wake up one day and decided that Joomla forms were useless. I felt like that ever since tooltips became form text and then vanished. The problem is that every time I tried to contribute anything about the visual appearance of Joomla 4 I was met with comments that I don't know what I am doing (I guess having the top rated extension in JED for 14 years is purely accidental and has nothing to do with my ability to write approachable software...) or that the template is still being worked on. So, I just gave up, like any reasonable person would've done. Seeing that this removal of the help text was intentional but also the first step before finding a different solution I felt inclined to provide one that I have already implemented in my own software and tested out there in the real world with real, imperfect humans using it. All I was told in reply was that it would not be possible / it wouldn't work, despite the fact that I have, well, already done it and have seen it does work (as evidenced by the sudden and dramatic reduction in support tickets regarding the software where it was implemented!). So, here we are, showing that it is possible and, frankly, not even technically challenging to boot! The biggest challenge is literary, not technical, i.e. how to write concise help text that adds real value to the product.

About the language strings

My goal providing language strings for com_config was to strike a balance between documenting everything and documenting nothing. I tried to document the following kinds of options:

• What's non–obvious to new people. These are things we take for granted. SEF URLs is obvious to us but for a newcomer it could just as well be called Doobity Yappity URLs with the same effect; it's jargon, it's gibberish, it's unapproachable. Adding a short line to explain the difference provides the lightbulb moment new users are currently missing.
• Items which do have a self–explanatory, technically correct title but the subject matter might not be obvious to non–experts. For example, what is an outbound proxy.
• Items with non–obvious security, usability or integration implications. For instance, all of us here understand (or SHOULD understand) why the system–wide /tmp folder should never be used as Joomla's temporary files folder, yet this is an issue I see on thousands of sites every single year.

I also tried to keep the help text concise. Not too short to make it useless, not too long to make it tedious. What I did here is far better than what I have done for my own software.

Further steps

There are two goals for this PR:

• Show that it's technically possible to implement a sensible method for an inline help system which helps new and intermediate users without getting in the way of the seasoned power user.
• Show that it's literary possible to provide useful and concise inline help text which provides value instead of merely paraphrasing the option label.

I am, however, a sighted user with ADHD which limits my ability to test with a screen reader. The rapid fire speech just rolls off my ears like water on a duck due to ADHD. I have no idea if I hit the mark on accessibility, so I want community members who have accessibility requirements or can test with screen readers to test whether this works. If not, I am open to suggestions and constructive criticism.

If this PR is accepted and merged or at least made RTC — I understand it may be a 4.1 feature instead of a 4.0 — I am willing to spend the time necessary to go through the entire backend and write concise help text for the backend components' Options. For this, I will need approval by the production leadership and the release managers for 4.0 and 4.1. If you want the backend edit pages and frontend edit / configuration pages done as well I will need some volunteers to write the help text.

In short, 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.

Phases I & II can be worked in parallel. Phase III needs to follow Phases I & II to ensure there is consistency in the language strings and which fields warrant descriptions.

I propose that we create a lean Inline Help Task Force which would be dissolved upon completion of all three phases. We could even produce a relatively short document to explain the philosophy of inline help so that future contributors and third party developers can use this feature more effectively. This document would become part of the developer documentation.

Pinging @wilsonge @zero-24 @bembelimen @webgras . CC'ing @rdeutz so you can see that I really do put my time and code where my mouth is. Hailing @brianteeman because he can test with a screen reader and has a vested interest in accessibility. Also notifying @Sulpher — if he hasn't blocked notifications from this project 😢 — because his issue gave me the impetus to make this PR.

Peace ☮

[chmst]

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

[brianteeman]

this is not a button - it is a link in disguise. Please make it a button as there are important differences between the two. Not least of which is that a button can be selected with the space key

[nikosdion]

Unfortunately, that's how Joomla renders ALL toolbar buttons. This is part of the joomla-toolbar-button web component.

IMHO, fixing that is outside the scope of this PR and also outside my skillset. I am not going to touch a web component's implementation! My code is using the standard Joomla 4 method to create a generic button for triggering a JavaScript event. If someone makes a PR which changes that web component to use a real button element my PR will still work fine; I target the class, not the element type.

[brianteeman]

No its not

[nikosdion]

Yes, it does. Here is the proof:

Also, you can read the code. If the Inline Help button exists we add it the ms-auto class and return. No further if–blocks are processed. If the Inline Help button is missing ONLY THEN we go back to the previous code which adds ms-auto either to Help or Options but not both.

[brianteeman]

bloomin cache. I can see it now. wrong thread

[brianteeman]

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.

[nikosdion]

@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?

[nikosdion]

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?

[brianteeman]

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

[brianteeman]

Is it intentional to have an empty class

[nikosdion]

@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.

[brianteeman]

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

joomla-cms/build/media_source/legacy/js/toolbar.es5.js

Lines 37 to 49 in e8ee928

	document.addEventListener('DOMContentLoaded', function() {
	/**
	* Fix the alignment of the Options and Help toolbar buttons
	*/
	var toolbarOptions = document.getElementById('toolbar-options'),
	toolbarHelp = document.getElementById('toolbar-help');
	if (toolbarHelp && !toolbarOptions) {
	toolbarHelp.classList.add('ms-auto');
	}
	if (toolbarOptions && !toolbarHelp) {
	toolbarOptions.classList.add('ms-auto');
	}

[brianteeman]

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

[nikosdion]

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 😉

[brianteeman]

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.

[brianteeman]

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

[nikosdion]

@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?

[PhocaCz]

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.

[nikosdion]

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.

[garkell]

@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?

---

_{This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/35610.}

[garkell]

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

---

_{This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/35610.}

[nikosdion]

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 :)

[Valc]

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.

[richard67]

@Valc Please test #37819 . Thanks in advance.

[nikosdion]

@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.

[Valc]

@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.

[cyrezdev]

@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 ;-)

[cyrezdev]

@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") .

[ceford]

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!

[Valc]

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

[nikosdion]

@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.

[cyrezdev]

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 ?

[nikosdion]

@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.

[nikosdion]

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...

[Valc]

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".

[cyrezdev]

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.