As of version 4.0, there are 18 built-in APIs in WordPress. They are all extremely important to different aspects of WordPress, and together they help WordPress to be the most flexible content management system in the world.

One of these APIs is the Quicktags API, which lets plugin and theme developers add new buttons to the Text mode (usually called the HTML mode) of the WordPress editor. In this tutorial, we're going to learn what the Quicktags API is, and how to use the API to create new buttons for the HTML editor.

What Is the Quicktags API?

Even though it's more than that, WordPress is commonly used as a "content management system" and WordPress has to let users manage the content easily and efficiently. That's why WordPress comes with TinyMCE, one of the best WYSIWYG ("What You See Is What You Get") editors of all time, and arguably the most appropriate content editor for WordPress. TinyMCE offers an uncomplicated content editing experience to users, which simultaneously displays the content almost as an exact preview of what they're going to publish.

But some users don't like to see that. In fact, some users would prefer to see the source code of the content so that they have total control over what they're going to publish. Or maybe the user would be on the "Visual editor" and want to check and verify the source code. That's where the "HTML editor" comes into play. The HTML mode of the WordPress editor displays the source code of the content, and nothing more.

There are buttons on top of the HTML editor, which we call "Quicktag buttons", and they allow us to edit the content without switching back to the Visual editor. Using the Quicktags API, we can create new buttons along with the existing ones.

Using the Quicktags API

Using the Quicktags API is very easy because while the core quicktags.js file has a lot more, we will (and should) use only one function: QTags.addButton().

If you want to pass the script as a separate file (which is the recommended usage), you should use the code snippet below:

<?php

function load_my_quicktags() {

    // Load the `my-quicktags.js` file with the `QTags.addButton()` functions.
    wp_enqueue_script( 'my-quicktags', 'http://the.url/to/my-quicktags.js', array( 'quicktags' ) );

}

add_action( 'admin_enqueue_scripts', 'load_my_quicktags' );

?>

But if you have no choice but to print the script inline, you can do it with the following code snippet:

<?php

function load_my_quicktags_inline() {

    if ( wp_script_is( 'quicktags' ) ) { ?>
    
        <script>
        
            // The `QTags.addButton()` functions go here.
        
        </script>
    
    <?php }

}

add_action( 'admin_print_footer_scripts', 'load_my_quicktags_inline' );

?>

Pretty easy, right? Note that we used the admin_print_footer_scripts action this time.

Parameters of QTags.addButton()

The QTags.addButton() function has eight parameters:

QTags.addButton( 
    id, 
    display, 
    arg1, 
    arg2, 
    access_key, 
    title, 
    priority, 
    instance
);

• id (string, required): A unique ID which will be the HTML ID value for the Quicktag button. (Keep in mind that the ID value for each button will be automatically prepended with the string 'qt_content_'.)
• display (string, required): Text to display on the button.
• arg1 (string or function, required): A starting tag to be inserted, or the name of a callback function.
• arg2 (string, optional): The ending tag to be inserted if necessary.
• access_key (string, optional): Access key for the button.
• title (string, optional): The HTML title value for the button.
• priority (integer, optional): The place that your button will go—1 to 9 for the first place, 11 to 19 for the second place, 21 to 29 for the third place, and so on.
• instance (string, optional): A specific Quicktags instance to show the button only there, if there is more than one Quicktags instance on the page. (If this is not set, the button will be added to all instances.)

Basic Usage: Creating Simple Buttons

The Quicktags API might seem scary and complicated at first (especially if your JavaScript knowledge is weak like me), but as you'll see right now, there's nothing to worry about writing tiny bits of code to create Quicktag buttons.

Let's start with something simple: Suppose you're going to add two shortcode buttons—one enclosing shortcode first, and one self-enclosing shortcode after that. Here's what you do:

QTags.addButton(
    'info-box', 
    'info box', 
    '[infobox]', 
    '[/infobox]'
);

See how easy this is? All you have to do is to set an ID, a button name, and the strings to print when the button is clicked. You can also not set the second argument (fourth parameter) and print a self-enclosing shortcode:

QTags.addButton(
    'signature', 
    'signature', 
    '[signature]'
);

That's all there is to know about the basic usage of Quicktag buttons!

Advanced Usage: Triggering Callback Functions

Of course, not all Quicktag buttons are created equally. You can create simple enclosing and self-enclosing Quicktag buttons with ease, but you might need to create a button that would need a little bit more work. That's where JavaScript functions come into play.

We're going to show simple examples of this, but it's up to your imagination to create complicated Quicktag buttons with JavaScript functions.

Now, let's do two quick examples. The first one's the classic alert button:

QTags.addButton(
    'alert', 
    'alert', 
    my_alert
);

function my_alert() {
    alert( 'Hello Quicktag!' );
}

As you can guess, it pops up a "Hello Quicktag!" message. Now let's do something with a prompt:

QTags.addButton( 
    'my_prompt', 
    'alert', 
    my_prompt
);

function my_prompt() {
    var my_class = prompt( 'Enter a class name:', '' );
    
    if ( my_class ) {
        QTags.insertContent('<div class="' + my_class +'"></div>');
    }
}

This one's a bit trickier: It asks you to type in a class name, and prints a div with the class you specified.

Conclusion

As I said earlier, the API looks a little bit intimidating. But as you can see, using it is pretty straightforward—even when using it to trigger callback functions. The HTML mode has some very dedicated users, and they would really appreciate it if you put in a button or two when you're developing a theme or a plugin.

What's your take on the Quicktags API? Would you consider using it, or do you have anything else to add to this tutorial? Tell us what you think by commenting below. And if you liked the article, don't forget to share it with your friends!