Messages upon switching to CKEditor 5 are overwhelming

#3273325: CKE5 and contrib: better "next action" description on upgrade path messages landed and has made a big improvement to the usability/scannability/interpretability of these messages 🥳

I brought this issue to last weeks UX meeting #3275459: Drupal Usability Meeting 2022-04-22. There is a recording with the full discussion, and I'll summarize what I believe to be the key takeaways.

• Several attendees +1'd the notion that the messaging is too much. Nobody -1'd that notion.
• Several in attendance had worked with CKEditor 5 and seen these messages before. Most (perhaps all) did not fully understand what these messages meant until I provided a several-minute explanation as part of introducing the issue.
• It was suggested that in most cases, the switch to CKEditor 5 does not change overall functionality or restrictions. Typically, the only difference is that allowing/disallowing a given tag happens in a different place on the text format form. It may not be necessary to have anything beyond a brief message in these use cases. noteThere's one possible scenario where a CK5 plugin is enabled to support a tag/attribute, and that enabling adds support for additional tags/attributes not supported pre-CK5. In such a scenario, it was suggested that the message should be more visible.
• Several discussion points led to a similar suggestion: If there are any plugins or GHS tags/attributes added, there should be an opening paragraph to contextualize what has happened, followed by a (possibly bulleted) list of shorter items stating what plugins/ghs settings were updated. (i.e. begin it with a TLDR).
• Benji suggested making the message(s) more concise by "separating the what from the why". The status messages would be a briefer "what", and could link to the CKEditor 5 help page for additional details. This would give users the option of learning more if they believe it to be important, but the overall messaging size is reduce, making it more likely to be read fully. Having the info be in the module help page mitigates the risk of referencing an external URL that could potentially change.
• The purpose of adding tags to source editing was not clear, and there was some uncertainty about what field/settings was being references. It was also suggested that having source editing as the active tab if it's been changed could make it easier to make the connection.
• It was suggested the longer versions of the messaging could be written to logs.

Adding UX meeting credits

It was suggested the longer versions of the messaging could be written to logs.

+1 → this is what the plan has been all along for the actual upgrade path (a hook_update_N() or post-update.php implementation) that will get executed during the 9.y.x → 10.0.x update: because there is no UI to show these messages anyway.

The purpose of adding tags to source editing was not clear, and there was some uncertainty about what field/settings was being references. It was also suggested that having source editing as the active tab if it's been changed could make it easier to make the connection.

Interesting suggestion! Seems feasible. Just checking: would this be a problem for accessibility?

It may not be necessary to have anything beyond a brief message in these use cases.

Right — that'd be ideal. The devil will be in the details.

Curious to see what the actual implementation will do here! 🤓 It feels like you have a good grasp on what needs to happen, and perhaps have a vision you want to realize, @bnjmnm?

I received great feedback at the UX meeting, and wanted to come up with a solution that integrated as much of it as possible.

The current (longer) messages will be written to logs
This information could still be valuable so a subset of users, but those users will not likely mind going to logs to learn more.

Leverage the help page at admin/help/ckeditor5 to provide additional details for those who want them
The messages will be informative enough that a user can determine if they want a more thorough explanation, and those explanations will be on the help page that comes with the module, and linked via the status/warning message.

One consolidated status message
Something along the lines of...

To maintain the capabilities of this text format, [Smart default settings](HELP:smart default settings) enabled the following plugins: <plugin list> and added the following to the Source Editing Plugin's [Manually editable HTML tags](HELP: how source editing is used in smart default settings ) setting: <tags list>. Additional details are available in your logs.

The linked "help:" sections are ones that would be created as part of this issue

One consolidated warning message

Updating to CKEditor 5 resulted in this text format supporting some tags/attributes that were previously unsupported: {IF <p>||<br>} <p><br> because [they are required by CKEditor 5](HELP: why they are required) {END IF}. {IF tags/attributes added} At least one of the Plugins enabled supports tags/attributes that were not previously supported: These tags: <tags list> and these attributes <attribute: (<impacted tags>)>. {END IF} Please visit [the help page](HELP: surplus tags/attributes) for more information.

The linked "help:" sections are ones that would be created as part of this issue

Not sure if that's the most intuitive way to represent links to theoretical paths or conditional text but that's my attempt 🙂

I really like your proposal! 🤩 Let's implement it? 😄

I think it could be helpful too if the logs were linked to the "Additional details are available in your logs" so they can be easily accessed/makes that option more visible

I think it could be helpful too if the logs were linked to the "Additional details are available in your logs" so they can be easily accessed/makes that option more visible

We've done this with a if (...moduleExists('dblog')) before, if someone's using a different logger they're on their own, but works for enough people and avoids linking to nothing.

Phenomenal difference:

👏

Posted a review on the merge request, but keeping this marked as needing review to invite others to review as well :)

+1 to the new messages. Should the warning be above the status message? As-is they are closer to the actionable area so I can see why it's below, hopefully people don't stop at the green message :)

I do have one significant issue with the current patch: using formatPlural to do conditional display of links is a bit too clever I'm afraid (I can still hear the screams of translators I used to work with :).

What happens when the plural formula for the language is not "singular/plural" such as arabic which ones should be translated in that case?

I think we should have properly separated strings for that, the different string versions don't convey the fact that it's singular/plural, it's about another condition, not cardinality. It will trip up translators.

Good call on #27 that was a use of formatPlural I hadn't considered.

I've noticed the watchdog messages are written to the log before the text format is saved. As soon as we select the cke5 element from the select in the text format config, the messages are written, even if we don't save the text format form. If the user is on the page, select the CKE5 option see the message about the logs, gets curious and click on the link to see the logs he'll be moved away from the configuration page and will essentially lose theirs config (if we assume back button won't work in all cases). They'll go back to the config page, reselect CKE5, see new messages and new log entries will be written so if he looks at the log at that moment they'll have: No CKE5 editor configured, 2 sets of log messages about changing CKE configuration. Not sure what do do about that, probably not too big a deal since it's a pretty low-traffic area anyway.

If we have a bunch of formats it would be helpful to replace "This format's HTML filters" in the log messages by the actual format name because this is ambiguous when seen out of context.

Discussed this with @Wim Leers, MR implements what we decided + a hefty reroll.

@bnjmnm suggested that we should consider addressing minor issues in followups given the difficulty of keeping this rerolled/updated, and I agree. So things like code comments, minor API cleanups, and iteration on the phrasings of the UI messages can happen in followup issues, and we'll decide which of those issues are stable-blocking on a case-by-case basis. Thanks!

👍

single minor comment on an and string that isn't translatable (and we can probably replace by ",") other than that, good for me :)

I think the untraslatable "and" is something that warrants moving this to needs work. Maybe it could be replaced by a comma like proposed by @nod_.

Comma seems fine to me given this is concatenation within a placeholder, pretty sure we do similar elsewhere.

Switching to NR - the three remaining threads in the MR are all about the same thing. I have some additional info that may help us get to a solution?

FormattableMarkup is better, nice one lauriii :)

This works for me :)

Looks like 3245967-38-95x_100x_101x.patch needs a reroll

rerolls

+++ b/core/modules/ckeditor5/src/SmartDefaultSettings.php
@@ -122,51 +161,64 @@ public function computeSmartDefaultSettings(?EditorInterface $text_editor, Filte
+        $this->logger->info($this->t('The CKEditor 5 migration enabled the following plugins to support tags that are allowed by the %text_format text format: %enabling_message_content. The text format must be saved to make these changes active.',

I realized that we should also use the formattable markup for the logger messages since we don't usually want to make the logger messages translatable.

Addresses #43 + needed rerolling anyway.

👍

+++ b/core/modules/ckeditor5/src/SmartDefaultSettings.php
@@ -249,9 +433,11 @@ private function createSettingsFromCKEditor4(array $ckeditor4_settings, HTMLRest
+            $warning = new FormattableMarkup('The CKEditor 4 button %button does not have a known upgrade path. If it allowed editing markup, then you can do so now through the Source Editing functionality.', [
...
+            $messages[MessengerInterface::TYPE_WARNING][] = $warning;

@@ -287,9 +473,11 @@ private function createSettingsFromCKEditor4(array $ckeditor4_settings, HTMLRest
+        $warning = new FormattableMarkup('The %cke4_plugin_id plugin settings do not have a known upgrade path.', [
...
+        $messages[MessengerInterface::TYPE_WARNING][] = $warning;

These two messages are printed as UI messages so they should be translated. 😅

Since it's a small interdiff, I got a +1 from @lauriii to switch back to RTBC on this change.

Committed b6f4e50 and pushed to 10.1.x. Also backported to 10.0.x, 9.5.x and 9.4.x. Thanks!