[UX] CKEditor - Provide default styles

[stpaultim]

Description of the need Make it easier for new users to figure out how to edit the styles menu option in CKEditor.

I just spent a few hours trying to figure out how to get this to work. In the end, my problem was silly human error in that I was trying to get an h1 style to work while h1 were not listed as part of the allowed HTML tags for that text format. But, having default styles available at the start, would have made it much easier for me to see that they were working and to have debugged my problem. Having no styles available left me with the impression that the feature might be broken and discouraged me from even trying to find the problem.

Not having any default styles to start with seems very counter-intuitive to me.

Here is an issue I opened while trying to figure this out: https://github.com/backdrop/backdrop-issues/issues/4232

Proposed solution Provide some default styles in styles list for the Filtered HTML text format.

These could be added in the install profile to make the styles menu useful out of the box, but mostly to demonstrate to new users how it works and make it easier for people to figure out how to edit them.

Just need to figure out what some sensible styles would be to provide by default. Keep in mind, that they styles menu is not even available by default. So these default styles would only be used or even visible if a user tried to add this option to their WYSIWYG menu.

Alternatives that have been considered Related issues (some of which might mitigate need for this): https://github.com/backdrop/backdrop-issues/issues/1520 https://github.com/backdrop/backdrop-issues/issues/2980

An alternative would be to include a "No styles configured" message under the styles menu in the WYSIWYG if the styles menu is enabled, but not configured.

Additional information

This is what you see in the WYSIWYG after adding the styles option to the toolbar (but before adding any custom styles).

Once you click on it, you get an empty box - this feels very broken.

[olafgrabienski]

Related issues (some of which might mitigate need for this): #1520 #2980

In https://github.com/backdrop/backdrop-issues/issues/2980#issuecomment-508772952 @docwilmot suggested to add tags from the Styles list automatically to the Allowed HTML tags. I guess, that would have been helpful in https://github.com/backdrop/backdrop-issues/issues/4232. For #2980, there is even a PR by @quicksketch that should add the tags but it needs work.

[olafgrabienski]

Just need to figure out what some sensible styles would be to provide by default.

Here are some candidates from https://github.com/backdrop/backdrop-issues/issues/2980#issuecomment-366750627:

Besides "small" tags, there are a number of other inline tags that CKEditor does not provide dedicated buttons for, including:

• abbr
• acronym
• big
• cite
• code
• q
• samp
• var

However, some of them aren't very common. For a start I'd suggest:

• abbr
• big and small
• cite
• code

[Graham-72]

I like this idea and would like to include at least one span style in order to show how to allow the user an opportunity to allow application of colour to words or phrases, e.g. span.l-blue|Light Blue span.m-blue|Mid Blue with of course appropriate entries in the CSS files.

[stpaultim]

Giving this the "good first issue" tag with some hesitation. It does require a little knowledge of how CKEditor works, but I think this is fairly simple. A note to any first time contributor that there is likely to be much discussion about the right mix of tags to include, but providing an initial PR would get this issue moving.

[stpaultim]

I've provided a simple PR that may have a few problems, but I'll need feedback on it.

My goal here is a simple improvement that does the following:

1. Makes the Styles widget functional when enabled so it doesn't appear broken.
2. Provide some examples for anyone interested in adding their own custom styles to their theme or sub-theme of Basis. Configuring these custom styles can be very confusing.

This PR does the following in the standard install profile:

1. It adds that three text color styles (Green, Blue, and Red) by default. They are not available to users until the Styles widget is added to a text filter.
2. It adds the <span> tag as an acceptable tag in the HTML filter. (Needs discussion)
3. It adds this to the basis.info file: ckeditor_stylesheets[] = css/ckeditor-iframe.css
4. It adds css/ckeditor-iframe.css
5. It adds a couple of rules to css/skin.css

This PR will not effect existing sites. I avoided the tags suggested by @olafgrabienski, because they would require adding even more tags to the html filter (and we don't have this yet - https://github.com/backdrop/backdrop-issues/issues/2980).

Specific questions:

1. Is my approach reasonable. Am I putting my css in the right place?
2. What are some sensible Styles to include by default, within the constraints of current site config and functionality.

NOTE: In the sandbox, I've added the "Styles" widget to CKEditor tool bar in the "Filtered HTML" text format. This would not be enabled by default and this change would only impact sites that enabled that widget/tool in the CKEditor toolbar.

[olafgrabienski]

@stpaultim I've just tested the PR, works like a charm!

I'm skeptical if it's a good idea to add <span> to the allowed HTML tags. It can lead to many unwanted tags in text fields due to copy & paste operations from other pages or websites.

Regarding your 2nd question, a style with a highlight background color would be interesting.

[klonos]

I like where this is going @stpaultim 👍🏼 ...I would like to see:

• a "highlight" option (which would be black text over a yellow "marker" background)
• a "Button" style, which converts links into button-styled links ("pill buttons")
• some "monospace" or "code" option perhaps?

I'd suggest a "quote" preset, but we already have a dedicated button for that, so I don't have any other ideas at the moment.

Not necessarily within the scope of this issue here:

• I don't think that "Styles" makes for an intuitive and self-explanatory UI element. Could we make that be "Formatting" or something like that? What do popular desktop apps like Word/Writer call their respective menu with text formatting templates?
• Can we find a place in the admin UI where we either directly explain which files need to be edited in order to tweak those presets, or link to online documentation about it?
• Would it be possible to allow editing these formats via the admin UI, without ever having to touch code/files directly?

PS: can you please rebase the PR branch?

[klonos]

...hmm 🤔 ...Word offers these options (and it calls them "styles"):

[klonos]

Noting that our Drupal brethren have been contemplating the same problem here: https://www.drupal.org/project/drupal/issues/2674412 ...they ended up updating their documentation, but people that have commented in that issue have been asking for a "simpler" solution.

[klonos]

Would it be possible to allow editing these formats via the admin UI, without ever having to touch code/files directly?

This is what I'm talking about: https://www.drupal.org/project/ckeditor_standalone_styles

This module allows specifying what styles are available in the CKEditor "Styles" dropdown selection using configuration entities. Site builders can add, edit, and delete individual styles. Because each style is a config entity, themes can provide their own default styles as well.

While Drupal core already provides an interface for managing these styles, it's embedded in the CKEditor configuration form. Using this module allows you users to manage the styles separately from the entire CKEditor and text format configuration.

This module also does something that core doesn't: It will dynamically add the specific CSS classes you define for your styles to the allowed HTML filter.

...unfortunately, only D8/9 versions available 😓

[indigoxela]

There seems to be some confusion regarding "structure" and "styles". Adding special HTML tags and apply CSS are IMO different things.

Personally, I use CKEditor styles to let users apply predefined CSS classes to tags, without the need for them to know what "tag" or "class" means. Having a more intuitive admin UI to provide these styles would be a cool thing.

The Ckeditor module in Backdrop has several hooks, so this might also be a good contrib candidate. I don't think, we can provide really useful styles OOTB, that fit every site.

[klonos]

I don't think, we can provide really useful styles OOTB, that fit every site.

Yes, but the OOTB experience when adding the styles button is not ideal. What could help would be a "no styles defined yet" pseudo-element. Ideally, that element should be a link to online documentation.

In the meantime, providing a couple of styles OOTB that people can either remove, or tweak to their needs seems like a nice alternative. It's easier for people to do that rather than having to create new styles from scratch.

[stpaultim]

The Ckeditor module in Backdrop has several hooks, so this might also be a good contrib candidate. I don't think, we can provide really useful styles OOTB, that fit every site.

I understand the difficulty of choosing useful styles OOTB that fit every site, but that is not the goal of this PR. The first line of the original issues states it pretty clearly:

"Description of the Need: Make it easier for new users to figure out how to edit the styles menu option in CKEditor."

I'm pretty good with Backdrop and I struggle with this every time I try to do it. Having some examples would have made it MUCH easier for me to configure my own. Also, it's seems really weird to me to provide a Styles menu/option without any styles under it. It looks broken to me.

My goal is not to provide the "right" set of styles for everyone. My goal is to provide at a minimum a couple of sensible styles that will 1) make the tool appear less broken 2) make it easier for anyone to understand how custom styles work, so that they can create their own (I don't think we should need a contrib module to make a core feature understandable).

Personally, I'm open to alternative ideas, but the problem (a feature that appears broken and is very difficult to use) is in core and I think we need a solution to those problems in core.

[klonos]

I'm pretty good with Backdrop and I struggle with this every time I try to do it. Having some examples would have made it MUCH easier for me to configure my own. Also, it's seems really weird to me to provide a Styles menu/option without any styles under it. It looks broken to me. ...the problem (a feature that appears broken and is very difficult to use) is in core...

Yup, that ^^ pretty much sums it up 👍🏼

[olafgrabienski]

make it easier for anyone to understand how custom styles work, so that they can create their own

Full agreement with the scope, but I guess even with the PR only a few people will manage to create their own styles. Depends on the individual situation (skill set, Basis vs. other theme, sub-theme or not) but will remain quite complicated.

If we don't automate / abstract the difficult things for the time being, I'd suggest to add a documentation page and provide a link to it.

[klonos]

If we don't automate / abstract the difficult things for the time being, I'd suggest to add a documentation page and provide a link to it.

Yes, let's also do that 👍🏼 ...but in addition to some default presets that people can either remove, or tweak.

[olafgrabienski]

@stpaultim As a basis for documentation, can you outline roughly how to create own styles on top of your PR?

[jenlampton]

I love where this is going! I tested in the sandbox yesterday at Backdrop Live and noticed that when you apply one style (like making the text red) and then attempt to apply another style (like making the same red text, blue) the second change does not apply.

It could be a bug with CKEditor, but noting here incase there is anything we can do to address that.

[klonos]

We discussed this issue during the biweekly UX/design meeting, and it seems that this is twofold:

1. It seems that we have consensus on the fact that we need to fix the UX problem at hand. I suggested the following plan of action:
   1. add some "dummy" placeholder text in the styles dropdown that says something along the lines of "no styles created yet"
   2. create a documentation page in docs.b.org, which outlines the process of creating custom styles for CKEditor (+ some examples too)
   3. add some help text in the text format configuration page (when the styles button is added to the toolbar), which links to the documentation page
2. Next thing would be to decide if we are to provide some simple/popular styles OOTB, and if so then decide:
   • what these styles should be
   • should they be implemented in the theme (Basis) or elsewhere

[jenlampton]

We discussed this again in the design meeting today. Some things we noted:

• the examples we commit should not include color because it needs to work with all themes, and that can be really hard to do. (Color is in the current PR, but that is only an example and we expect to change it before commit)
• If we absolutely need to include color, maybe we should add the editor.css in the basis theme, and match the basis colors. Then there would be an example of the feature in use in core that people could copy, but people would not be able to use that feature with any other theme.
• There are a few things we could do in core that would be theme agnostic, ideas include:
  • using "standard" classes that are added by core (things like button-primary and button-secondary). These would have already been overridden by most themes if they wanted different styles than the defaults.
  • adding examples that relate to layout only (things like a <ul> that displays in 2 columns, 3 columns, or 4 columns)

edit: oops, cross-posed with @klonos. Thanks and sorry!

[izmeez]

I don't see the Styles option on the editing windows, do you have to do something to get this to appear?

[stpaultim]

@izmeez - Yes, in CKEditor 4 you have to edit your text editor and add the styles to the toolbar.

Having said that, I'm not sure that this issiue is still relevent given our move to CKEditor 5. I'll need to do some testing to see how this works in CKEditor 5.

[indigoxela]

I don't see the Styles option on the editing windows,

@izmeez Yes, I know, that's weird UX. In order to be able to add styles, for example on admin/config/content/formats/filtered_html, you first have to drag the "Styles" button into the active toolbar. That's the same for CKE4 and CKE5 (in 5 it's in a vertical tab).

So, you can add styles via admin UI, but it's not obvious how.

[izmeez]

@indigoxela Thank you for the details. With CKE5 it looks like you have to drag the "Styles" button into the active and then also populate the Styles dialog in the vertical tab.

[izmeez]

The PR #3694 cannot be tested because it has expired, but code looks like it may be a good start. Another shine for the new cke5, maybe?

[stpaultim]

The PR was still for CKEditor 4, so I'm sure that this needs work. I did some testing and I think the basic idea here may still make sense. But, it will need to be updated for CKEditor 5.