[UX] Make optional description fields show/hide via #states.

[klonos]

There's a couple of places in the admin UI where we allow the site admin/builder to enter some descriptive text. Off of the top of my head, there's the "Description" field for content types and also in the same form the "Explanation or submission guidelines" field in the "Submission form settings" section:

Although I do not have solid evidence for this (hint: backdrop-ops/backdropcms.org#99), I have a very strong hunch that these are rarely used and take much vertical space that adds to the scrolling required to reach the submit buttons of the form. UX--.

We do a much better job with views descriptions:

---

PR by @klonos (for the content type add/edit form): backdrop/backdrop#2704

[klonos]

PR up for review: backdrop/backdrop#2704

Before/after screenshot that shows vertical estate gain on mobile:

[olafgrabienski]

Although I do not have solid evidence for this (hint: backdrop-ops/backdropcms.org#99), I have a very strong hunch that these are rarely used and take much vertical space ...

Interesting question! Based on my personal experience, I guess the content type "Description" is far more often used than the "Explanation or submission guidelines". Disclaimer: I find the "Description" also quite useful.

Another interesting question: would showing a checkbox instead of a textarea lead to less usage of the respective option?

Either way, if we implement (one of) the suggested changes: Let's keep labels like "Description" without the prefix "Provide". Scanning the page, it can be hard to get the point when there are multiple instances of "Provide (...)": Provide X", "Provide Y" and so on.

[klonos]

Thanks for reviewing @olafgrabienski 👍

Yes, I also believe that the "Explanation or submission guidelines" field is less-used compared to the "Description" filed.

...would showing a checkbox instead of a textarea lead to less usage of the respective option?

My personal experience is that site builders do not use any of these options. My current role in the agency I work for includes support for 100+ government sites, and these usually have many content types defined. The ones that come with the distribution (GovCMS) all include a description, but no submission guidelines; the ones that are custom-created don't have either of the two things. So my guess is that site builders simply to not bother with these (I am assuming they just want to get things done fast, so they don't bother with the details - unless the customer complains) 😞 ...sad as this may be, less usage of 0 is still 0 😅

The goal of this issue here was to improve the UX when creating content types on mobile (if we reduce them to a checkbox when not used, there's considerably less scrolling required). It was not my intention to "hide" these, with the end goal being to reduce visibility/usage of the feature. In fact, if you look at the PR code, you will see that I have added CSS to make sure that the "Provide description" label remains bolded (the default for field labels is to have normal font weight), same as the current label before the PR changes.

An alternative solution here would be to have a "Help text" vertical tab, and move those 2 fields in it. That way, on mobile these would be inside a collapsed accordion section, which would have the same effect. I have chosen the current implementation instead, because it is a pattern that we are using in the Views UI as well.

Another thought would be to have this solution (checkbox toggle) kick in only on mobile, since this is when the UX problem I am trying to solve is manifesting itself. Unfortunately, the Field API does not support breakpoint conditions though, so such an implementation would require considerably more code/effort.

Either way, if we implement (one of) the suggested changes: Let's keep labels like "Description" without the prefix "Provide". ...

I understand what you are saying, and I have thought of that, but this change was intentional. The reason is because it is not actually the label of the text field; it is the label of a checkbox/toggle. The label of the field itself, although hidden visually, is still there:

<div class="form-item form-type-checkbox form-item-description-enable">
  <input type="checkbox" id="edit-description-enable" name="description_enable" value="1" class="form-checkbox">
  <label class="option" for="edit-description-enable">Provide description </label>
</div>

<div class="form-item form-type-textarea form-item-description" style="display: block;">
  <label class="element-invisible" for="edit-description">Description </label>
  <div class="form-textarea-wrapper resizable textarea-processed resizable-textarea">
    <textarea id="edit-description" name="description" rows="5" cols="60" class="form-textarea"></textarea>
  <div class="grippie"></div></div>
</div>

^^ notice the 2 labels; the one for the checkbox, and the second for the text field. If I left the checkbox label as "Description", then users with screen readers will have 2 consecutive fields with the same label, which would be confusion. I hope that the decision makes more sense now.

[klonos]

...noting that the from for adding/configuring vocabularies also has a description field, but that is a single-line text field rather than a multi-line one (so that form does not have the UX issue we are trying to solve here):

Also noting that by default, all terms for vocabularies come with a "Description" field, but that is more like a body field (has a WYSIWYG etc.), rather than a description/help (so the UX issue is not applicable there either):

[olafgrabienski]

If I left the checkbox label as "Description", then users with screen readers will have 2 consecutive fields with the same label, which would be confusion. I hope that the decision makes more sense now.

I see! Downgrading the UI for one group (non screen reader users) for the sake of another group (screen reader users) shouldn't be an option, though.

[bugfolder]

I agree that "Provide..." is appropriate.

Regarding usage, my own experience is that for types that are only created by "educated" creators (site builder, senior editor), minimal instruction is needed, but for types created by junior editors or ordinary authenticated users (for example, calendar event submissions), fairly detailed description and submission guidelines are needed.

At any rate, testing of backdrop/backdrop#2704. Tested, and the toggle works for both description and submission guidelines. WFM.

Code reviewed, LGTM.

[quicksketch]

I wasn't 100% sure about hiding the description field by default, but @klonos makes a good point that the same thing is done on the Views Add View page. Since it seems like @olafgrabienski and @bugfolder are also in agreement that this is an improvement, I've merged backdrop/backdrop#2704 into 1.x and 1.26.x.

[klonos]

Thanks for merging this @quicksketch 🙏🏼 ...looking at the changes though, I wanted to follow up on the issue I have described in the inline comments (the PR was filed back in 2019). As part of that, I searched for existing issues in our queue and found that I had already filed an issue for it here: #3817

After testing @indigoxela's suggestion there, I have confirmed that although #attributes does not work with '#type' => 'item', #wrapper_attributes does. So here's a follow-up PR to fix this properly, with less cruft and inline comments in our codebase: backdrop/backdrop#4535

@bugfolder perhaps you want to give the new PR a quick review/testing if you have some time?

[bugfolder]

Tested. Before:

<div id="edit-description-description" class="form-item form-type-item">
 This text will be shown on the <a href="/node/add"><em>Add content</em></a> page.
</div>

After:

<div class="description form-item-description form-item form-type-item" id="edit-description-description">
 This text will be shown on the <a href="/node/add"><em>Add content</em></a> page.
</div>

WFM.

Code reviewed: LGTM. RTBC.

[bugfolder]

Oh, I also updated FAPI docs to remove #attributes from the supported properties of item.

https://docs.backdropcms.org/form_api#item

[klonos]

Thanks for the prompt review + jumping on documentation as well @bugfolder 🙏🏼

[quicksketch]

Follow-up merged as well. Thanks @klonos and @bugfolder!