Feature #1666

Custom TinyMCE Toolbar Buttons

Added by Dominic Giglio over 9 years ago. Updated over 9 years ago.

Priority name:
Category name:
WordPress (misc)
Target version:
Start date:
Due date:
% Done:


Estimated time:
2.00 h


Now that the TinyMCE editor shows the "kitchen sink" by default, I'm going to customize and reorder the formatting buttons.

ms_word_toolbar.png (30.8 KB) ms_word_toolbar.png Dominic Giglio, 2012-02-29 08:57 PM
wp_default_tinymce_toolbar.png (23.4 KB) wp_default_tinymce_toolbar.png Dominic Giglio, 2012-02-29 08:57 PM
cac_custom_tinymce_toolbar.png (25.8 KB) cac_custom_tinymce_toolbar.png Dominic Giglio, 2012-02-29 08:57 PM
tinymce.jpg (26 KB) tinymce.jpg Matt Gold, 2012-02-29 11:23 PM
Screen_Shot_2012-03-01_at_10.39.53_PM.png (18.6 KB) Screen_Shot_2012-03-01_at_10.39.53_PM.png Matt Gold, 2012-03-01 10:40 PM
cac_custom_tinymce_toolbar2.png (27.6 KB) cac_custom_tinymce_toolbar2.png Second version of CAC custom tinymce toolbar with viper Dominic Giglio, 2012-03-04 01:06 PM

Related issues

Is duplicate of CUNY Academic Commons - Feature #1662: Customize Button Order in TinyMCEDuplicate2012-02-29


#1 Updated by Dominic Giglio over 9 years ago

I've customized the TinyMCE toolbar with formatting buttons that resemble MS Word 2003 as close as possible. I've attached three screenshots showing Word 2003, WP default TinyMCE and the new CAC custom TinyMCE. I look forward to any and all feedback.

#2 Updated by Matt Gold over 9 years ago

Nice work, Dom. Here are some proposed revisions. I started by moving buttons related to the font/paragraph over to the left of the top row. Then I tried to keep buttons related to the movement/alteration of text together, before ending that row with functions related to the page as a whole (paste from Word, spell-check, etc.). I put it up here mostly for discussion; I expect Chris to have thoughts.

#3 Updated by Dominic Giglio over 9 years ago

I like it. Formatting on the left and editing on the right. I'm looking forward to Chris' thoughts.

#4 Updated by Boone Gorges over 9 years ago

Added myself and Chris as watchers.

#5 Updated by Chris Stein over 9 years ago

A couple quick things before I get into the real deal:
  • This ticket should be merged with, they're the same.
  • Dominic, when you add a ticket that you think might be related to me in any way don't hesitate to add me as a watcher. I don't just look through redmine so if I'm not on a ticket I don't usually see it.

On to the toolbar, generally I think we're all on the same track. Matt, yours especially is close to what I had. I think the main idea is to group the like functions together.

Both of you removed the show/hide kitchen sink button. I think that's fine.

You added in superscript, subscript, cut and paste. I also think those are good. I have to admit I haven't had time to look at all the options so I can't comment on other possibilities

I do want to push back against the font-family and font-size additions. It could just be the web developer in me but I have two concerns with that. One is that those are really supposed to be the job of the theme. Presumably the theme designer spent a good deal of time figuring out what size and font to make the paragraphs, headings etc. This is opening the designs up to the possibility of people adding in some really ugly font combinations and awkward large or small sizes. Two, is that the only way to change those things is to add in really ugly inline styles that bloat the HTML. Modern web design is based on the separation of content into HTML and styling into CSS, preferably in a separate stylesheet, and this would break that (allowing the color also breaks this but I'm willing to give that smaller concession). If people aren't clamoring to do those things then I don't think we should let them.

Here is a link to my version:
The extra line at the top is what they see in HTML mode. I only did minor reordering and didn't put a lot of thought into it.
The top line is mostly formatting with the last icon, one I didn't understand by looking at it, the Remove Formatting
The second line adds lists and links and other general stuff.

Looking at it again you could probably make the argument the blockquote should be down by the lists and indent as it is similar to them.

I want to push back on adding in

#6 Updated by Matt Gold over 9 years ago

Thanks, Chris. FWIW, I'm totally on board with leaving out the paragraph/font styles -- I think you make a good case for doing so above.

Your version looks really good to me. I'd consider removing the cut button and the RSS button -- not sure we need either. I'm not sure what happens when you click the help button . . . I'd consider taking that out.

Finally, I want to say that we really need to take a look at the existing admin bar, which includes various video short-tags. Will those show up on this new bar, since they'll be activated by a plugin? Attached is a screenshot showing some of those buttons . . . .

#7 Updated by Matt Gold over 9 years ago

Also: your demo rocks. Thanks for putting it together with such care!

I do think your message above got cut off, though (Redmine word limit?)

#8 Updated by Chris Stein over 9 years ago

When you click the help button a modal window pops up over the page with some instructions on editing. I don't know if we have any control over what is there.

I don't know if anyone uses the RSS button inside of posts. I suppose some might use it on a page where they want to show feeds. I'm OK either way. I'm also ambivalent about the cut button. It goes fine with all of the pastes but not sure if people actually will use it much.

Matt, when does that admin bar show up? And does it depend on the browser? I'm not seeing those links right now.

I think I cut myself off in the last post. I moved some text around and left a straggler.

Including them at all or not a good question. There are too many services out there to include all of them but it makes sense to make it easy to embed media from some of the most popular ones. Which ones is still a question.

I guess if I had my way those would be options in the new Upload/Insert link but I don't think that's possible (or at least not without a lot of code).

Maybe we can make the reordering changes to tinyMCE and then do a new ticket to hash out what media embeds we want to do?

#9 Updated by Dominic Giglio over 9 years ago

I also agree with Chris on the formatting. I only included them because I was trying to replicate the Word formatting bar as closely as possible for a starting reference point. The help, RSS and Remove Formatting buttons can probably go as well. I've never used them and don't know anyone who has. I'm ambivalent about the cut button too, we're attempting to help users who probably don't fully understand cut/copy/paste anyways. :-)

I'm not familiar with that toolbar of media insert buttons either. If you tell me what plugin provides that functionality I'll try and replicate it on my end to see if my code interferes with them.

I haven't done anything with the formatting of the html editor toolbar buttons. I don't think we should do anything to the toolbar used by someone advanced enough to change to html editor mode. Will probably cause more confusion than benefit.

#10 Updated by Matt Gold over 9 years ago

I may be wrong (if so, Boone can correct), but I think that the media buttons are provided by the Viper's Media Quicktags plugin, which (I think) is activated on a sitewide basis (ie., in mu-plugins). Boone, can you confirm?

#11 Updated by Boone Gorges over 9 years ago

Yes, I think the buttons are from Viper. No, I don't think it's activated sitewide.

More generally, any plugin has the power to add items to the TinyMCE toolbar. So it'll be futile to spend too much time trying to control where/whether to place all of the added buttons. My advice is to turn off all plugins, make your best configuration based on WP's default buttons, and be satisfied with that.

On a related note, I do not think that we should be removing any buttons that are being added by plugins (though it would be possible to do so using Dom's method). We aren't really in a position to know whether anyone is using this buttons, and in any case it has the potential to confuse users when buttons intended to be there by a plugin (and possibly mentioned in documentation) are not there.

#12 Updated by Chris Stein over 9 years ago

Thanks for the clarifications on the video buttons. I also agree that it is best to make our configuration on the default buttons and then to allow individual blog users to modify those with plugins as they see fit.

#13 Updated by Dominic Giglio over 9 years ago

I'll be integrating all these ideas into my code tonight, will post an updated screenshot for review once the changes have been made.

#14 Updated by Chris Stein over 9 years ago

Sounds good Dominic.

About the videos, do you think we should have a link or any kind of help that explains to people if they have a YouTube or Vimeo video they can just paste in the URL in Visual Mode? Scott has a nice post on this

but I'm not sure if many of our users are aware that it can be just that simple. Perhaps when we do the writeup on this change we can add something about that.

#15 Updated by Dominic Giglio over 9 years ago

An explanation of how to get embedded content into the editor definitely belongs in the documentation (codex). I am unsure if we can add anything to the editor to help with this. I will investigate while adjusting my current custom button code. Maybe I can get into that help button and customize the content that gets displayed in the modal window. However, I don't think many people click help buttons, so I don't know how beneficial it would end up being. In my experience, if a user doesn't know what a button does, then they never click on it. And I also believe, personally, that when a user comes from a windows background (as most users do) they tend not to use "help" functionality since the help functionality in windows really isn't all that helpful. To be fair Apple's "help" isn't that much better. :-)

Getting the average Commons user to become more familiar with WordPress/BuddyPress/Commons functionality is probably the job of an outreach program. I believe getting users to the proper documentation is a UX issue. I'm just not sure where/how to get that help into the admin UX. I'll be investigating the new WordPress Screen API (which provides a new way to create content under the admin section's help tab) for a future article. Although, getting helpful information into that section of the admin will suffer from the same failing of a user not clicking the help tab! LOL

Chicken and egg my friends, chicken and egg...

#16 Updated by Dominic Giglio over 9 years ago

The viper plugin was throwing my code for a loop so I had to rewrite it. The first version was changing how the buttons were rendered internally which prevented viper from displaying its buttons. This is a good thing though, my code is now more robust which should prevent it from interfering with other TinyMCE plugins. I searched the WordPress plugin repo for "TinyMCE" which returned 387 results. There's no way (that I know of) to test my code against that many plugins so if it is interfering with another plugin used somewhere on the Commons I'll have to fix it in a new issue.

I've attached a new screenshot showing the custom buttons with viper enabled. I went into viper's settings and moved it to the second row just to make sure showing the kitchen sink by default wasn't interfering with viper's ability to be displayed on the second line. I also tested it on the CAC dashboard as well as another site's dashboard to make sure it was working across the board. As long as it works on one site it should work on them all.

Let me know if you're all ready for me to push this code or if you'd like me to change anything else.

#17 Updated by Matt Gold over 9 years ago

I think that looks really great, Dom! Nice job!

Question: will your alterations to Viper be undone when/if we update that plugin?

#18 Updated by Dominic Giglio over 9 years ago

I didn't do anything to viper. I changed how I was customizing the buttons because my technique was preventing viper from displaying its buttons (and I assume any other plugin that creates custom buttons in the same way). I altered my code to work with viper, not the other way around.

If you're talking about viper being displayed on the second row I don't think an update to the plugin would alter that setting. However, the attached screenshot shows viper on my local environment. You will not see viper on the second row in the live site's TinyMCE, I only changed that setting on my machine to make sure the code I added to show the kitchen sink by default didn't break viper's ability to be moved to different toolbars. Viper has its own admin settings page on which one of the options allows you to display it on rows 1-4.

#19 Updated by Matt Gold over 9 years ago

Got it. Thanks, Dom!

#20 Updated by Chris Stein over 9 years ago

Excellent, thanks for your work on this. I think it will really help people out, especially those new to the Commons and WP in general.

#21 Updated by Dominic Giglio over 9 years ago

@boone, I've pushed my code up to master. Let me know if you have any problems with the code on your end before I close this issue.

#22 Updated by Boone Gorges over 9 years ago

  • Target version changed from Future release to 1.4

Great - thanks, Dom.

I'm not 100% sure how this plays with plugins. You're adding a filter to the mce_buttons value, but you're not actually examining that value (or even passing it to the function). Are you counting on plugins adding their buttons later on, after you've already done your rearranging?

I'm thinking here especially of, eg, BuddyPress Docs. There are some places where that plugin steps in and adds/removes buttons.

I say this not having tested :) I will do so sometime tomorrow or the next day.

#24 Updated by Dominic Giglio over 9 years ago

Sorry, I keep forgetting to paste the GitHub commit URLs in these updates. :-(

The functions in my code don't accept the $buttons argument because I'm not "updating" or "adding" or even "removing" buttons. My two functions attach to the mce_buttons and mce_buttons_2 filters and just return an array of our custom button layout (I'm basically completely overriding and replacing all buttons by returning a new array of buttons). The information I found while researching this issue states that all plugins should work with these filters when altering the layout of TinMCE's toolbar. For example:

This page:

Says to use:

array_unshift($buttons, 'styleselect');

when customizing buttons. As long as plugin developers adhere to that advice there shouldn't be any problems with my code. Of course there's no way to be sure that plugin authors are following that specific "best practice."

If I understand correctly, because bp-custom.php is executed before a plugin has a chance to get its hands on TinyMCE's toolbar, our buttons will already be customized by the time their code is executed. If they're using array_unshift() (or something similar) to add custom buttons then there should be no conflict with the CAC custom buttons.

Please correct me if you think (or know) that I'm wrong on this point.

I'll take a look at BuddyPress Docs to see how (and more importantly when) you're accessing the buttons.

#25 Updated by Boone Gorges over 9 years ago

As long as plugin developers adhere to that advice

because bp-custom.php is executed before a plugin has a chance to get its hands on TinyMCE's toolbar

Sorta. bp-custom.php is loaded from BuddyPress, but strictly speaking it's just a plugin like any other. It's loaded after mu-plugins, but before most other stuff. In any case, file load order is only a secondary determinant of priority for plugins. The first is your filter priority (the third parameter of add_action() or add_filter()). In other words, something hooked like this

add_filter( 'mce_buttons', 'foo', 5 );

will load before

add_filter( 'mce_buttons', 'bar' );

regardless of when the file is loaded (file load order can sometimes break ties).

So an adequate solution is probably just to hook with priority 1. It'd be marginally safer to do some robust checking at the time of reordering, but it's probably overkill.

Let me know how the experiments go. I'll take a look myself in the upcoming days. Thanks for you work on this.

#26 Updated by Boone Gorges over 9 years ago

  • Status changed from Assigned to Resolved

I did some experiments of my own, and it looks like my intuition was correct - if a plugin loads its custom MCE buttons in the right way (namely, hooked to mce_buttons etc earlier than 10), they would get wiped out by your plugin. And it turns out that we do have a couple of plugins in our collection that attempt to load buttons earlier (at priority 5) - see

grep -nR 'mce_buttons' wp-content/plugins/

By switching the priority to 1, we minimize the possibility of conflict. It's not totally eliminated - if another plugin attempts to modify buttons at mce_buttons:1, there may still be conflict - but the alternative would be to add a ton of logic for looping through the $buttons passed to the filter, and reordering based on that array, rather than hardcoding the order as it is now. Probably not worth it.

I've made the change in

Great job on this one, Dom - the buttons look much better in this order.

#27 Updated by Dominic Giglio over 9 years ago

  • % Done changed from 0 to 100

I had thought about using a priority of 1 when creating those filters, can't remember why I left it out; prob just forgot. :-)

I think (in this particular situation) "minimizing the possibility of conflict" is the best approach. This particular fix can easily be updated in the future if a plugin introduces an edge case where its buttons are affected by the complete override implemented in my custom filter functions.

I'm glad everyone is pleased with my first contribution!

Just had a pretty big exam in Disc. Math (propositional logic and set theory), a subject that I was having a little difficulty with; now that its out of the way I'll be moving on to the pagination issue brought up by Scott and the (Google) Analytics issue. I'd like to tackle those to get a little more familiar with the code base before jumping into the featured post plugin. That one seems like it's going to get pretty involved.

#28 Updated by Matt Gold over 9 years ago

Fantastic work, Dom!

#29 Updated by Dominic Giglio over 9 years ago

Thank you sir. :-)

Also available in: Atom PDF