New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

TinyMCE Custom Buttons and Extensibility #4658

Closed
avillegasn opened this Issue Jan 24, 2018 · 25 comments

Comments

@avillegasn
Copy link
Contributor

avillegasn commented Jan 24, 2018

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:

tinymce-menu-button

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

This comment has been minimized.

Copy link
Member

danielbachhuber commented Jan 24, 2018

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

This comment has been minimized.

Copy link

StaggerLeee commented Jan 25, 2018

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

This comment has been minimized.

Copy link
Contributor Author

avillegasn commented Jan 25, 2018

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

This comment has been minimized.

Copy link

StaggerLeee commented Jan 25, 2018

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

This comment has been minimized.

Copy link

davilera commented Jan 25, 2018

@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

This comment has been minimized.

Copy link

StaggerLeee commented Jan 25, 2018

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

@davilera

This comment has been minimized.

Copy link

davilera commented Jan 25, 2018

+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.

@gziolo gziolo added this to To do in Extensibility Jan 31, 2018

@iseulde

This comment has been minimized.

Copy link
Member

iseulde commented Feb 1, 2018

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

This comment has been minimized.

Copy link
Contributor Author

avillegasn commented Feb 1, 2018

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!

@iseulde

This comment has been minimized.

Copy link
Member

iseulde commented Feb 1, 2018

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

This comment has been minimized.

Copy link

StephenAtty commented Mar 23, 2018

@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.

@danielbachhuber danielbachhuber added this to the Merge Proposal milestone Apr 11, 2018

@karmatosed karmatosed modified the milestones: Merge Proposal, Merge Proposal: Back Compat Apr 12, 2018

@iseulde iseulde self-assigned this Apr 23, 2018

@jcklpe

This comment has been minimized.

Copy link

jcklpe commented Apr 26, 2018

@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

This comment has been minimized.

Copy link
Member

danielbachhuber commented Apr 26, 2018

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

This comment has been minimized.

Copy link
Contributor

mboynes commented Jul 25, 2018

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.

@gziolo gziolo referenced this issue Aug 6, 2018

Merged

Annotation API #7718

0 of 4 tasks complete
@jcklpe

This comment has been minimized.

Copy link

jcklpe commented Aug 7, 2018

@MasterK999

This comment has been minimized.

Copy link

MasterK999 commented Sep 9, 2018

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

This comment has been minimized.

Copy link

jcklpe commented Sep 22, 2018

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

@GlennMartin1

This comment has been minimized.

Copy link

GlennMartin1 commented Sep 22, 2018

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

This comment has been minimized.

Copy link

StephenAtty commented Sep 22, 2018

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

This comment has been minimized.

Copy link

jcklpe commented Sep 22, 2018

@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

This comment has been minimized.

Copy link
Member

gziolo commented Sep 24, 2018

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.

@iseulde

This comment has been minimized.

Copy link
Member

iseulde commented Sep 24, 2018

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.

@iseulde iseulde referenced this issue Sep 27, 2018

Merged

Format API #10209

4 of 4 tasks complete

@gziolo gziolo added this to To Do in API freeze via automation Oct 22, 2018

@youknowriad

This comment has been minimized.

Copy link
Contributor

youknowriad commented Oct 27, 2018

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

Extensibility automation moved this from In Progress to Done Oct 27, 2018

API freeze automation moved this from To Do to Done Oct 27, 2018

@avillegasn

This comment has been minimized.

Copy link
Contributor Author

avillegasn commented Oct 29, 2018

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

This comment has been minimized.

Copy link
Member

gziolo commented Oct 29, 2018

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

@avillegasn avillegasn referenced this issue Nov 21, 2018

Closed

Documentation: Format API #11105

0 of 7 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment