[UX] Add help text to explain what the ordering of text editors & formats does.

[ghost]

On the 'Text editors and formats' page (/admin/config/content/formats), you can re-order the formats by dragging them up and down or by setting a weight. But there's no indication as to what this is for.

Knowing Drupal, and assuming nothing's changed in this regard, the order determines which format will be used by default based on the order and what a user has access to. However this isn't explained at all and so may be confusing for users. Drupal had help text here that explained that, but Backdrop seems to have removed it...

Suggesting adding help text back in to explain the purpose and use of the ordering of text formats.

---

PR by @klonos: backdrop/backdrop#2384
PR by @BWPanda: backdrop/backdrop#3075

[ghost]

I just noticed the same thing with the Content Rankings on this page: /admin/config/search/settings - no description of what the numbers mean. I seem to recall only recently realising that I'd been doing them wrong on all my Drupal sites for years (putting them in the opposite order to what I thought). Wondering if this should become part of this issue (to be renamed something like 'Provide descriptions for ordering stuff') or whether to create a new issue for the Search page...

[klonos]

@BWPanda separate issue for /admin/config/search/settings I think.

[klonos]

Screenshot of what the help text looked like in D7:

Actual text:

Text formats define the HTML tags, code, and other formatting that can be used when entering text. Improper text format configuration is a security risk. Learn more on the Filter module help page.

Text formats are presented on content editing pages in the order defined on this page. The first format available to a user will be selected by default.

"Filter module help page" linked to /admin/help/filter which is not available in Backdrop. Here's what that page had:

About

The Filter module allows administrators to configure text formats. A text format defines the HTML tags, codes, and other input allowed in content and comments, and is a key feature in guarding against potentially damaging input from malicious users. For more information, see the online handbook entry for Filter module.

Uses

Configuring text formats
Configure text formats on the Text formats page. Improper text format configuration is a security risk. To ensure security, untrusted users should only have access to text formats that restrict them to either plain text or a safe set of HTML tags, since certain HTML tags can allow embedding malicious links or scripts in text. More trusted registered users may be granted permission to use less restrictive text formats in order to create rich content.

Applying filters to text
Each text format uses filters to manipulate text, and most formats apply several different filters to text in a specific order. Each filter is designed for a specific purpose, and generally either adds, removes, or transforms elements within user-entered text before it is displayed. A filter does not change the actual content, but instead, modifies it temporarily before it is displayed. One filter may remove unapproved HTML tags, while another automatically adds HTML to make URLs display as clickable links.

Defining text formats
One format is included by default: Plain text (which removes all HTML tags). Additional formats may be created by your installation profile when you install Drupal, and more can be created by an administrator on the Text formats page.

Choosing a text format
Users with access to more than one text format can use the Text format fieldset to choose between available text formats when creating or editing multi-line content. Administrators can define the text formats available to each user role, and control the order of formats listed in the Text format fieldset on the Text formats page.

Filter administration pages

• Text formats
• Configure Filter permissions

"Text formats page" links point to /admin/config/content/formats
"Configure Filter permissions" links to /admin/people/permissions#module-filter, which we don't need in Backdrop, since we added the ability to set permissions (actually allow selecting user roles) in each text format config page:

...which just reminded me of #1086 😄

[klonos]

I think that if not all of this, at the very least we should add back this bit:

Text formats are presented on content editing pages in the order defined on this page. The first format available to a user will be selected by default.

Lets decide and I'll file a PR.

[klonos]

In D8, the first sentence of the help text was changed to this:

Text formats define how text is filtered for output and how HTML tags and other text is displayed, replaced, or removed...

[klonos]

I have filed a PR for this, but I am having some trouble with placing the help text above the table in that form. I have tried using #weight to place the help text above the table, but no matter what weight I have tried, the help text always gets rendered between the table and the submit buttons 😞

Text I have used:

When editing content with fields that use a rich text editor, such as the body field, text formats are presented as available options. The order in which these options are listed is defined by the order of the text formats in the table below. The options listed are also limited to only the text formats each user has permission to use, and the first format available to a user will be selected by default.

[ghost]

I've made a PR based on @klonos' one (I don't think there's a way I can add to his instead...?) backdrop/backdrop#3075

The problem you had with the weight @klonos was that this page is rendered as a theme function and it was manually displaying the table before any other form elements. My PR fixes that.

[ghost]

Oh! I also changed the wording to match D8's which I think is less verbose but still explains it well:

Text formats define how text is filtered for output and how HTML tags and other text is displayed, replaced, or removed.

Text formats are presented on content editing pages in the order defined on this page. The first format available to a user will be selected by default.

[klonos]

...this page is rendered as a theme function and it was manually displaying the table before any other form elements.

Thanks for figuring this out @BWPanda 👍 ...I wouldn't mind being slightly more verbose though, if we were to be more precise. How about this:

Text formats are presented as options in text fields, when creating or editing content. They automate operations such as the removal, replacement, and styling/formatting of HTML tags and text, before final output.

The table below allows specifying the order in which these options are shown, with the first format available to a user being the default.

[klonos]

...pinging @jenlampton re words ^^ 😉

[ghost]

I think the less text there is the more likely someone is to read it (and the opposite is true too). But I'll let you/others decide on the final wording. My main issue with your original wording (other than the length) was that you mentioned 'rich text editor' which wasn't accurate (formats apply to text areas without an editor too).

[ghost]

Well it seems this was snuck in as part of #1575, so it's apparently fixed already. I'm not so fussed about the wording that I want to keep this open for more discussion, so closing this issue.

[jenlampton]

I like the current text: The order of the text formats below determines the order in which they will appear in the Editor selector when creating content (depending on permissions for the text formats). @klonos if you want to improve that we could either re-purpose this issue or open a new one. But I agree with @BWPanda that the urgent need here has been met. :) Thanks @BWPanda!