Gutenberg: Advanced RichText controls displayed even when disabled for the block

[gziolo]

Describe the bug
There are all formatting controls disabled for Search block:
https://github.com/WordPress/gutenberg/blob/master/packages/block-library/src/search/edit.js#L37
However, there are advanced RichText formatting controls still displayed for the block which is rather not expected in this case. /cc @noisysocks @talldan

To Reproduce
Steps to reproduce the behavior:

1. Go to the editor
2. Click on inserter
3. Pick Search block
4. Click on the arrow down icon

Expected behavior
There are no RichText controls added to the block toolbar

Screenshots

Desktop (please complete the following information):

• OS: macOS
• Browser: Chrome
• Version: 72

[ellatrix]

Why is RichText used, if you do not wish rich text?

It sounds like we might want a setting noFormats or something if people like to use rich text without the formatting functionality.

[ellatrix]

Previously buttons added by plugins would still display for this block.
Any content you paste in this field will also be rich text.
The formattingControls prop is not a good way to prevent all formatting.

I would suggest moving forward as follows:

• Introduce a disallowFormats prop which signals that no formatting should ever be added to the value. In this case, RichText works just like PlainText, the only difference is that looks just like RichText. It could still allow autocompleters etc. It could also accept an array of formats to disallow, which will then be removed from the UI, filtered on paste, etc.
• Deprecate the formattingControls prop.

[noisysocks]

Why is RichText used, if you do not wish rich text?

I forget why we went with formattingControls={ [] } for the Search block. Thinking about it now, I can't see a reason why we ought to disallow formatting in the label and button since both <label> and <button> support having formatting tags (e.g. <strong>) in them.

In other words, I'd be okay with removing formattingControls={ [] }.

[demo-igor]

Is it possible to manage More Rich Text Controls.
How I can affect to this one https://github.com/WordPress/gutenberg/blob/8625b82f240e4371704909f6e29e8d1a8a2e61ee/packages/block-editor/src/components/rich-text/format-toolbar/index.js#L21 ?

[jg314]

We've noticed this issue as well for our custom blocks that use the RichText component with formattingControls={ [] }. We would prefer no formatting options appear for the input, but we still see "Code", "Inline Image" and "Strikethrough".

[noisysocks]

My very general advice that I have found helpful when developing blocks is:

1. If the attribute must not contain HTML, use an <input> and style it how you like.
2. If the attribute may contain HTML, use <RichText>. I suggest not specifying a formattingControls prop at all, because usually there is no reason _not_ to allow users to use the formatting that they want.

[jg314]

Thanks for the response @noisysocks. A few questions based on your response:

1. When you mention using an <input> would you usually suggest utilizing the <TextControl> component or just using a basic <input> field?
2. I think part of the issue right now is that while anyone who uses <RichText> components should allow some formatting, there are needs for flexibility. For example, I could see someone wanting to allow for a strikethrough to be applied, but not allow an inline image be added. Does that use case seem to fit with the way you all are thinking about it?
3. I've noticed the <RichText> component is not included in the Component Reference documentation at https://developer.wordpress.org/block-editor/components/, although it is included at https://developer.wordpress.org/block-editor/packages/packages-rich-text/. Can you give us some idea of why that's not included? I think part of the problem we're running into when building these blocks with the <RichText> component is knowing when and how to use it. Do you think including it in the components documentation would help?

Thanks a ton.

[noisysocks]

When you mention using an would you usually suggest utilizing the component or just using a basic field?

I'd suggest <TextControl> if newlines are permitted, and <input> if not.

For example, I could see someone wanting to allow for a strikethrough to be applied, but not allow an inline image be added. Does that use case seem to fit with the way you all are thinking about it?

Would what @ellatrix has proposed to do in https://github.com/WordPress/gutenberg/pull/14542 work for this use case? e.g. one could specify disallowFormats={ 'core/image' }.

Can you give us some idea of why that's not included? I think part of the problem we're running into when building these blocks with the component is knowing when and how to use it. Do you think including it in the components documentation would help?

It would definitely help! There was no conscious decision to exclude RichText. As with most things in open source, it's likely just that nobody has written anything yet 🙂 Would you like to volunteer to contribute some documentation? I'd be happy to guide you through the process.

[jg314]

Thanks for the quick response @noisysocks.

Would what @ellatrix has proposed to do in #14542 work for this use case? e.g. one could specify disallowFormats={ 'core/image' }.

I definitely think that could work as long as you have the ability to disallow all formatting options without having to list them all out. Based on that pull request though it looks like that's possible.

It would definitely help! There was no conscious decision to exclude RichText. As with most things in open source, it's likely just that nobody has written anything yet 🙂 Would you like to volunteer to contribute some documentation? I'd be happy to guide you through the process.

I'd be happy to give it a shot. I've been wanting to contribute at some point, but like a lot of people, just wasn't sure of the best way to do it. That said, my background is more on the PHP side and less on JavaScript, but that might actually help ensure the documentation is understandable for everyone.

I do see documentation at https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/rich-text, but I don't see that anywhere on https://developer.wordpress.org/block-editor/. I apologize if I'm missing it.

If you'd still like me to take a shot at it, let me know the best way to get started.

[noisysocks]

I definitely think that could work as long as you have the ability to disallow all formatting options without having to list them all out. Based on that pull request though it looks like that's possible.

That's right, in that PR you can specify disallowFormats={ true } which will disallow all formatting.

That said, my background is more on the PHP side and less on JavaScript, but that might actually help ensure the documentation is understandable for everyone.

Absolutely! In my experience the less familiar one is with the codebase the more approachable their explanations are.

I do see documentation at https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/rich-text, but I don't see that anywhere on https://developer.wordpress.org/block-editor/. I apologize if I'm missing it.

RichText isn't a totally independent component like, for example, Button is. This is because RichText only makes sense in the context of a block editor. Therefore, RichText is in the @wordpress/block-editor package and not in the @wordpress/components package. This means that its documentation does not appear in the _Component Reference_ section.

There is a little bit of documentation for RichText in the package's documentation, i.e. _Package Reference > @wordpress/block-editor_. This is very hard to find though.

I'd recommend creating a new page underneath _Developer Documentation_ called e.g. _RichText Reference_. This could be a more introductory reference that complements the more technical documentation at https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/rich-text.

To do this, fork the Gutenberg repository and clone the source code. Then, create a new markdown file in docs/designers-developers/developers and update docs/toc.json to point to it. Finally, submit a PR! Join us in the #core-editor channel on the WordPress Slack if you need any help.

[jg314]

Thanks for the breakdown @noisysocks. I really appreciate it. I'll put something together, hopefully in the next few weeks, and send it over via a PR.