NOTE: This post is part 2 of a guide on creating custom editor functionality in WordPress. In part 1 I covered making a simple shortcode to allow contributors to add quotes with author and citation, producing the appropriate HTML and not requiring those contributors to get their hands dirty with any coding outside the shortcode typing. If you haven’t read that article yet, I’d recommend it, as we’re going to build upon that shortcode in this guide.

Shortcodes are great – they save time, reduce coding errors and help to keep things looking consistent. But they’re not always intuitive for everyone and lack the more familiar GUI integration many people prefer. In this guide, we’re going to create a plugin for the TinyMCE editor, inside our WordPress theme. When we’re done, we will have a new button in the editor’s toolbar, which will trigger a modal window. This window will offer the user three text fields, where they can add the author, citation and citation URL in a more simplified fashion. Confirming these properties will convert the selected text into a shortcode for the blockquote, and insert any defined attributes automatically.

Our final blockquote functionality with custom button

File structure

We’ll start with the file structure. As with the previous tutorial, we’re going to write our PHP in the regular functions.php file, although again, I’d recommend having a separate functions folder with dedicated files, and requiring those, for a tidier approach.

We will need to create a js folder (if you don’t already have one), and inside that, create a tiny-mce folder in which we’ll create an img folder and a tiny-mce.js file. So, your theme folder should contain the following:

js
|- tiny-mce
| |- img
| |- tiny-mce.js

Create an icon

You can do this however you want, but you’ll want to end up with a 48px x 48px image file. Our file will be called quote.png.

Currently, we have an empty function for our plugin. We’ll go ahead and add that plugin beneath the function. Rename the placeholder names to suit your theme.

The second parameter of the create method, is where the meat of our plugin exists. It’s an object, and we’ll put in two methods: the init method, which contains the meat’s meat, and the getInfo method, which provides some information about our plugin:

The getInfo method calls a function that returns the values above, which should be self-explanatory. Let’s work on the init method next.

The function called by init contains two parameters we’ve defined above as ed and url. ed is the editor object, and url is the URL relative to the folder in which the current .js file resides.

Inside the function, we will call a couple of methods against the ed object, addButton and addCommand. addButton, err, adds the button, and addCommand binds the functionality to that button exclusively.

We’ll add the unique name of our button as the first parameter of addButton, and then the object that forms the second parameter will contain our image, the title of the button (shown on mouseover), and the icon image (using url):

Comprehensive documentation on TinyMCE’s available field types is hard to find; I found that this Stack Overflow question and answers contained the most useful breakdown of available options. The above code should be pretty easy to interpret. name should be unique for each button, so its value can be referenced later. value ought to be empty unless you want to define some default text to populate the field.

We pass e as the object containing all the info from the submission. This includes e.data, an object containing all the button data. Next, we simply create a params array, push relevant values to that array (if they’re not empty), and then make it a string, joined by a space, to add to our shortcode as attributes. Then, we insert the new content with paramsString in a functionally similar way to how we did on Skip.

We add the name we defined in the tinymce.PluginManager.add method in our .js file as a new element in the $plugins array we pass into the tiny_mce_add_buttons function. Then, we point the value to the location of our custom JavaScript file and return the revised array.

Next, register the buttons in a separate function, bringing in the current buttons array, defining our new buttons in a separate array, and finally returning a merged array.

Almost done! Now we just need to call these functions with the appropriate hooks. We create one final function to add these two functions as filters, and then we call this final function as an init action.

All done! Upload your revised theme files and test out your post editor. You should now be able to highlight your text, hit your new button and customize how your blockquote is made. Here’s how it should look:

Our final blockquote functionality with custom button

Shortcodes are great – they save time, reduce coding errors and help to keep things looking consistent. But they’re not always intuitive for everyone and lack the more familiar GUI integration many people prefer. In this guide, we’re going to create a plugin for the TinyMCE editor, inside our WordPress theme. When we’re done, we will have a new button in the editor’s toolbar, which will trigger a modal window.

When we’re not teaching readers like you how to use new technologies, we’re developing GitKraken, a cross-platform Git GUI, and Axosoft, our Scrum project management software. Try both for free!