TinyMCE Custom Buttons and Extensibility

[avillegasn]

Issue Overview

TinyMCE allows to add your own buttons to the editor toolbar, and therefore extend the editor's behavior. Apparently, Gutenberg does not provide an 'easy' way to replicate this behavior and plugin authors (like me) won't be able to add features in Gutenberg that already exist in the current editor.

Current Behavior

As aforementioned, the Codex includes documentation on how to extend TinyMCE to add custom buttons and menu buttons via JavaScript. Others also provided articles showing how to add custom buttons (link). Unfortunately, I didn't find something similar for Gutenberg.

It is pretty easy for a WordPress developer to extend the actual editor using JavaScript thanks to the instructions provided. In my case, our plugin UI is as follows:

Expected Behavior

Right now, I found the Extensibility section in Gutenberg's documentation. Apparently, the blocks.BlockEdit filter seems the right way to do that. Unfortunately, I've been unsuccessful trying to extend the BlockEdit to make this work.

I've also explored Gutenberg's source code to try to find another solution with no luck. The file blocks/editable/format-toolbar/index.js is prepared to use customControls. Maybe that's the location where to add the new controls (buttons) I want to include in a block, but again, I was unable to do it (after several attempts trying different approaches...).

Anyway, the solution using blocks.BlockEdit filter seems problematic to me since wp.hooks.addFilter apparently requires the block identifier where the filter applies. I've been using 'core/paragraph' in my attempts, but what should I use if what I want to extend is any block that contains text?

Possible Solution

I'd like to have a specific filter (or set of filters) to be able to tweak this. Something similar to mce_buttons in TinyMCE where developers could modify the set of buttons available (disable/enable/add new ones). Each button should be an object containing at least the following:

• title: the title of the button
• type: menubutton | button
• icon: the icon to show
• disabled: whether the button is active or not
• onClick: the function to call when the button is clicked
• menu: to include the children buttons for hierarchy (when using subbuttons)

That's just a proposal from a React/Gutenberg newbie that had a hard time trying to adapt functionalities from my plugins to the new editor. Maybe I should just wait until everything is clearer, but I'm worried about not being ready for the launch in April.

With the proper mentoring, I could help working on the proposal to make it viable.

[danielbachhuber]

Great questions, @avillegasn. I agree that it'd be useful to work out some solution and make sure it's documented for the next person.

[StaggerLeee]

Please make limit those buttons are not used globally for all blocks, but only for one specific block a plugin add.
I already see how many plugins force it everywhere if allowed,

[avillegasn]

Hey @StaggerLeee I just asked for a way to include the buttons on text blocks (not all the blocks), to keep backwards compatibility. If a plugin forces its buttons everywhere, you have three options: deactivate the plugin, contact the developer to make him/her provide a way to deactivate just the buttons, or directly code a function yourself that deactivates the buttons. That's freedom 😄

[StaggerLeee]

Yes, theory is nice. Ask Yoast to remove all advertising and junk. Good luck. :)

Was telling just hypothetically, did not mean you or your plugin.

[davilera]

@StaggerLeee I understand your concern, because there are some developers who abuse the freedom they're given (and I'm not talking about Yoast specifically)... But I'm with @avillegasn on this one (disclaimer: I work with him): we need a way to extend already-existing blocks (including Gutenberg's core blocks and third-party blocks) with our own actions/buttons.

Just think about the scenario depicted by @avillegasn: you want to add a new action in paragraphs. Your solution would require every developer to create a new paragraph block with their own buttons. The result is cumbersome: a user would have multiple paragraph blocks, each of them with a different set of actions that would depend on the plugin that created the new paragraph block. I think that's a pretty bad solution.

Alternatively, @avillegasn 's solution makes total sense, as it's easy to understand and prevents block-bloating. If a plugin wants to add new formats or actions in a paragraph, let them do that using a Gutenberg filter/action scheme. If properly implemented, those buttons would only appear where and when they're required.

If you're worried about developers abusing this, the solution is quite simple: if those new buttons are added using add_filter or similar, then nobody stops you from getting rid of them using remove_filter ;-)

[StaggerLeee]

OK, if add_filter. Core team has to set clear rules about it.

[davilera]

+1 on filters. Actually, that's what the original solution proposed:

I'd like to have a specific filter (or set of filters) to be able to tweak this. Something similar to mce_buttons in TinyMCE where developers could modify the set of buttons available (disable/enable/add new ones).

and it's completely aligned to WordPress' architecture.

[ellatrix]

It sounds like this is about the extensibility of (all) the rich text areas, which is certainly something that is planned. It would be good to know what sort of functionality people ore looking to add so we can make this extensible in a performant way. Some of the buttons some plugins add to the old editor can be blocks now. Others are looking to extend the formatting (extra tags etc.). What else are people looking to do? Thanks for the feedback!

[avillegasn]

In our case, we want to extend the formatting, wrapping the selected text of "any" text block with an extra HTML tag. Others may want to highlight the selected content and show a comment when hovering or work with the selection in some similar way. If that is planned, we'll be able to adapt our plugin to Gutenberg. Good to know!

[ellatrix]

Yes, that sort of thing is certainly planned. We'd like plugins to be able to insert custom tags and data data that goes with it to any text in any editable field in Gutenberg.

[StephenAtty]

@iseulde - that's precisely what I need... I need some way of injecting a custom tag into the currently active block (i.e. where the cursor is)... and I suspect that functionality is needed by a significant number of other plugins that add functionality to the editor.

[jcklpe]

@iseulde Yes I would like to second @avillegasn 's description of what he would like to see with the extension of default blocks.

To be specific, I can insert a code block. But if I have a short piece of code that I want to have code styling but to appear inline with a descriptive paragraph, then I have to resort to using the Classic Editor Block. Which isn't awful, but.... like I like Gutenberg! I want to use Gutenberg to do that!

Other stuff would be wanting to highlight a piece of text or give it alternative emphasis than just bold or italics etc.

[danielbachhuber]

Just a heads up that I'm working on a more specific migration guide (include how to handle TinyMCE) and welcome everyone's input.

[mboynes]

In discussing Gutenberg with clients, one issue that has surfaced a few times is the minimal toolbar set on the core paragraph block. Personally, I appreciate the minimalist default, as long as I can customize it.

This issue is the piece that I think is missing. If superscript and subscript are very important for a site I'm working on, I want to be able to add them via a PHP or JS filter (akin to mce_buttons, as mentioned above), and adding them should be no more difficult then filtering an array and appending [ 'superscript', 'subscript' ]. If the character map is critical for a site that writes a lot about international currencies, I would want to add charmap. And so on.

[jcklpe]

I was looking at the latest updates to gutenberg and saw something in there about inline styles or inline blocks or something or other. Is that to address this issue?

…

On Wed, Jul 25, 2018 at 10:15 AM Matthew Boynes ***@***.***> wrote: In discussing Gutenberg with clients, one issue that has surfaced a few times is the minimal toolbar set on the core paragraph block. Personally, I appreciate the minimalist default, as long as I can customize it. This issue is the piece that I think is missing. If superscript and subscript are very important for a site I'm working on, I want to be able to add them via a PHP or JS filter (akin to mce_buttons, as mentioned above), and adding them should be no more difficult then filtering an array and appending [ 'superscript', 'subscript' ]. If the character map is critical for a site that writes a lot about international currencies, I would want to add charmap. And so on. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#4658 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AJA4zgFGxcOKxZTYogubjeTv4ZMoiwgdks5uKIt4gaJpZM4RrGcc> .

[MasterK999]

Just to chime in to this discussion I have a WordPress plugin called Change Text Case. The entire point of my plugin is to allow for easily selecting bit of text in the TinyMCE editor and changing the text case to be correct Sentence Case or all Uppercase or whatever depending on need. I wrote this plugin because clients often give me text that has things in all caps that should not be and it has been added to based on requests over time.

This plugin should not have its own block. It needs to be buttons within the Paragraph and Header blocks in order to be useful to people.

I do not know if this type of use case has been given much consideration but I have been totally unable to find any good documentation to help me implement this in Gutenberg so I hope it gets some attention.

I worry that if this type of thing is not handled well and documented. It will result in a real mess with the change over to Gutenberg and delay deployment for WordPress users that have come to rely on a TinyMCE plugin of some sort or another for their daily work.

[jcklpe]

Another Gutenberg update! Oh boy! ohh... 😢 still no inline styles 😭

[GlennMartin1]

Gutenberg is a great start - so take this as commendation and not complaining.

Obviously, the paragraph block will be the most common block. Hence, we need a VERY functional paragraph block in core.

I want Gutenberg to succeed, and for that I believe inline styling is a necessity for the default paragraph block.

[StephenAtty]

There needs to be a well defined and reliable way for plugins to interact with the current / default block - so many plugins which interact with the existing TinyMCE editor need to be able to interact with Gutenberg in the same way and right now they can't, and there seems to be no interest from the Gutenberg developers in making this happen.

[jcklpe]

@GlennMartin1 Oh it was def meant as a commendation! :) Consider me one of the girls screaming at the Beatles.

@StephenAtty I think there is, it's just they're working on some deeper background stuff to get it to work right from what I've read. If you check the PR #6642 you can see they're doing some work making an easy to use format to register new stuff for Rich Text. Seems like a really good idea!

[gziolo]

Related issue raised in #7143 by @hansschuijff:

Somtimes content editors need the ability to change the appearance of parts of a block (esp. paragraphs) and classes and id's enable the theme to facilitate that in a structured manner.

[ellatrix]

Don't worry about this, it's coming soon. #7890 will change the structure of RichText values to be easier to manipulate and format, along with helper functions for this. I think this will help @MasterK999 easily replace the selected text, and we can add extra helpers if they make sense. The helpers make it almost as easy as manipulating a string. You don't have to look at the DOM or HTML at all. Building on that, I'm also working on #10068 which will allow you to add buttons, inserter items, shortcuts, etc. for all RichText fields in Gutenberg. Adding something like subscript or inline styles won't be hard to do.

[youknowriad]

Closing this as the Format API landed. Let me know If I'm missing anything here.

[avillegasn]

Closing this as the Format API landed. Let me know If I'm missing anything here.

Is there any documentation/code example out there?

[gziolo]

It's in progress: #11105. Gutenberg uses this API internally. You can check it in source code before docs are ready.

registerFormatType:
https://github.com/WordPress/gutenberg/blob/master/packages/rich-text/src/register-format-type.js

All format controls:
https://github.com/WordPress/gutenberg/tree/master/packages/format-library/src