If you’re interested in adding a TinyMCE button to WordPress, then this series of articles aims to do just that. In the first post of the series, I walked through some of the basic things that need to be done in order to get started with adding a custom button.

My very own copy TinyMCE Editor. Show spectacular.

My very own copy TinyMCE Editor. So spectacular.

I laid out the file organization, the basic plugin structure, some of the foundational JavaScript, and started working on the hooks that are necessary for adding a custom button.

As it stands right now, the functions responsible for adding a new button aren’t actually defined within the context of a class much less hooked into the plugin itself. So in this post, we’ll take a look at exactly how to do exactly that.

Adding a TinyMCE Button to WordPress

Remember that adding a TinyMCE Button to WordPress is basically writing a custom TinyMCE plugin and then registering the JavaScript with the appropriate hooks in WordPress.

When you’re working to do that, there’s a lot of boilerplate-style work that goes into the JavaScript. As such, I’ll be taking a look at that in its own post. As long as you have the code from the first post in place, then you should be good to go for now.

1. The Plugin Bootstrap File

If you’ve seen any of the code that’s in the WordPress Plugin Boilerplate or you’ve seen any of the code that I’ve written for a number of the more recent plugins that I’ve released, then you’re likely familiar with what I call a “plugin bootstrap file.”

In short, this is a file that’s responsible for starting the plugin. That’s it – it defines the header for WordPress to see and then it instantiates the core plugin.

In this case, it looks something like this:

Notice in this file – specifically in the run_acme_button function, we’re instantiating and initializing a class that we’ve yet to actually define. Secondly, note that we’re calling require_once to load the class-acme-button-loader.php file in the includes directory. We haven’t actually created that file, but we’ll be doing so momentarily.

Before doing that, let’s define the core plugin file.

2. The Acme_Button Class

The Acme_Button class represents the core plugin in that it maintains references to the current version of the plugin (that we can use throughout the rest of the code) and a reference to a loader that’s responsible for de-coupling the business logic of the hook definitions from the class itself.

The initial class is pretty simple:

There’s still some work to be done with it, but this is the basic functionality that you need – the version property, a getter method, and a constructor that defines the plugin’s version. If you’ve got the code defined up to this point in your plugin, then you should be good to go in terms of instantiating it in WordPress.

3. Adding The Loader

As mentioned previously, the loader is a class that’s responsible for de-coupling the business logic of hook definitions into its own class.

Discussing a loader is content for another post, but the gist of it is that it:

  • makes sure that a single class isn’t doing more work that it should
  • keeps the level of cohesion of the classes high
  • and makes it easier to test your work if you’re planning to write unit tests

With that said, the loader for this particular plugin looks like this:

Notice that the constructor accepts a reference to the core plugin file. This makes it possible for us to read whatever properties we choose to expose – like the version – and then also has methods that actually communicate with the WordPress API.

This allows us to register a hook in the core plugin file and call a corresponding function in the loader that actually does the work.

We’ll see how these functions (that we saw in the previous post) all fit together momentarily.

4. Adding the TinyMCE Hooks To The Loader

At this point, the we need to do is actually take the code from the previous post and make sure that it’s properly hooked up between the core plugin file and the loader.

To do this, we define the filter in the core plugin class’ initialize method:

And then we make sure the definitions for the function are the loader:

Easy enough, right?

5. Tying It All Together

Finally, we need to hop back into the core plugin fall and then make sure it maintains a reference to the loader so that we can actually register all of these hooks.

So first, we’ll add the property and setup a call to it in the constructor:

And that should tie everything together.

  1. The bootstrap file defines the plugin header, loads the dependencies, and then instantiates the core plugin.
  2. The core plugin defines the version and reference to the loader as well as initializes the hooks that are needed to load the core plugin file.
  3. The loader is called via the core plugin file and provides the actual functionality for what code should be fired for a specific event in WordPress.

That’s it.

Back To The Editor

Now that we’ve actually got a functional plugin that’s properly registering hooks, JavaScript files, and so on with WordPress, we can start implementing the button such that it has its own icon, that it responds whenever we click on it, and that it adds whatever is needed to the editor within the WordPress post editor.

In the next post, we’ll turn our attention to how to do all of the above.

Category:
Notes
Tags:
,

Join the conversation! 12 Comments

  1. Timing is everything, great post and just in time I learning it.

    Do you have a good tutorial or a resource for adding a button with a dialog where the dialog screen is generated by PHP as the required parameters values need to taken from WordPress

    Thanks, David

    • Hey David,

      Not sure – I’ve done a couple of tutorials about using the media modal, for example, within WordPress but if you’re talking about a dialog being generated with PHP, I’d need to know more of what you’re actually trying to build.

      If you’re looking to build a dialog, then it’d be a combination of HTML and PHP and likely some CSS and then triggered via Ajax and JavaScript.

      But without knowing more, it’s hard to say.

      • Hi,

        I’m trying to create a button in TinyMCE for a shortcode that will open a dialog with the parameters for the shortocde. In most cases I do it using JS and everything is working great however is this button I need that one of the parameters values will be something from the WordPress environment for example name of all the pages.

        I know that the solution to do it is to create a PHP modal but I can’t find any resource that showing the process.

  2. Hi Tom,

    I’m following most of your tutorials here and on Tuts+. Can’t wait for more of this, they’re great, especially the one about meta boxes :)

    I assume that in later parts you’ll show how to add fields like text, textarea or simple select etc. in the modal that will popup. Just wanted to know if you’ll dig into more advanced stuff like e.g. select list from php array or maybe multicheck?

    And my second question: do you have plans to create tutorials on more advanced meta boxes e.g. gallery or something similar?

    Cheers

    • I assume that in later parts you’ll show how to add fields like text, textarea or simple select etc. in the modal that will popup. Just wanted to know if you’ll dig into more advanced stuff like e.g. select list from php array or maybe multicheck?

      Right now, I’m just looking at creating a simple button and inserting some data into the post editor, although I could expand it a bit – I’ve had some others ask about similar things so I’ll see.

      And my second question: do you have plans to create tutorials on more advanced meta boxes e.g. gallery or something similar?

      Right now, I don’t. A lot of the things that people want to build with meta boxes are historically done with things like the media uploader, Jetpack, etc. That doesn’t mean that we shouldn’t look at alternative ways of doing things, but I just haven’t really given it much thought :).

  3. Useful but not complete (as you have already mentioned). I’ll wait for more. By the way, why don’t you use Boilerplate (which you have developed, if I am not wrong)? You are using structure very similar to BoilerPlate and it would have been really good to have a proper tutorial for beginners to get started with Boilerplate.

    Appreciate if you write a complete plugin development tutorial for Boilerplate.

    • By the way, why don’t you use Boilerplate (which you have developed, if I am not wrong)?

      I’m using a similar structure to the Boilerplate plate, but it’s not 1:1. I’ve got my bootstrap class, a loader class, and then the additional files (like the JavaScript).

      You are using structure very similar to BoilerPlate and it would have been really good to have a proper tutorial for beginners to get started with Boilerplate.

      I’m actually no longer in charge of the Boilerplate, but if you follow along with the current GitHub repository then you should be able to find more information.

      • Thanks for the reply. Once I get acquainted with WordPress Plugin development, perhaps I’ll write a tutorial for Boilerplate one day since there is no proper tutorial for the latest version.

        By the way, how do you test/compile the plugins? Through local wordpress install or dummy wordpress website?

        • By the way, how do you test/compile the plugins? Through local wordpress install or dummy wordpress website?

          I usually have three environments setup:

          . Development is where I build and test the plugins locally

          . Staging is where I deploy them for the client to test

          . Production is where the plugin runs on the actual live site

          All work is done in Development, checked into source control, then deployed to Staging. Once the client signs off, I’ll then deploy the Production (where no development or touching of the code is done).

  4. Hi Tom,

    Thank you for the awesome post. Wanted to ask you where is the assets/class-acme-editor-button.php loaded?

    Also is there a repo for the whole ACME plugin?

    Best regards,

    Ionut

    • Wanted to ask you where is the assets/class-acme-editor-button.php loaded?

      Right here.

      Also is there a repo for the whole ACME plugin?

      No — but all of the source code for it is in the gists of this post so hopefully that helps :).

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.