Quicktags

Description #Description

The Quicktags API allows you to include additional buttons in the Text (HTML) mode of the WordPress Classic editor.

Top ↑

History #History

This API was introduced in WordPress 3.3.

Top ↑

Usage #Usage

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

Top ↑

Parameters #Parameters

• id (string) (required): The html id for the button. Default: None
• display (string) (required): The html value for the button. Default: None
• arg1 (string) (required): Either a starting tag to be inserted like “<span>” or a callback that is executed when the button is clicked. Default: None
• arg2 (string) (optional): Ending tag like “</span>”. Leave empty if tag doesn’t need to be closed (i.e. “<hr />”). Default: None
• access_key (string) (optional): Shortcut access key for the button. Default: None
• title (string) (optional): The html title value for the button. Default: None
• priority (int) (optional): A number representing the desired position of the button in the toolbar. 1 – 9 = first, 11 – 19 = second, 21 – 29 = third, etc. Default: None
• instance (string) (optional): Limit the button to a specific instance of Quicktags, add to all instances if not present. Default: None

Top ↑

Return Values #Return Values

(mixed) Null or the button object that is needed for back-compat.

Top ↑

Examples #Examples

// add more buttons to the html editor
function wporg_add_quicktags() {
    if ( wp_script_is( 'quicktags' ) ) {
	?>
    <script type="text/javascript">
    QTags.addButton( 'wporg_paragraph', 'p', '<p>', '</p>', 'p', 'Paragraph tag', 1 );
    QTags.addButton( 'wporg_hr', 'hr', '<hr />', '', 'h', 'Horizontal rule line', 201 );
    QTags.addButton( 'wporg_pre', 'pre', '<pre lang="php">', '</pre>', 'q', 'Preformatted text tag', 111 );
    </script>
	<?php
    }
}
add_action( 'admin_print_footer_scripts', 'wporg_add_quicktags' );

(Note: to avoid a Reference Error we check to see whether or not the ‘quicktags’ script is in use.)

The above would add HTML buttons to the default Quicktags in the Text editor. For example, the “p” button HTML would be:

<input type="button" id="qt_content_wporg_paragraph" accesskey="p" class="wporg_button" title="Paragraph tag" value="p">

(The ID value for each button is automatically prepended with the string qt_content_.)

Here is a dump of the docblock from quicktags.js, it’s pretty useful on it’s own.

/**
 * Main API function for adding a button to Quicktags
 *
 * Adds qt.Button or qt.TagButton depending on the args. The first three args are always required.
 * To be able to add button(s) to Quicktags, your script should be enqueued as dependent
 * on "quicktags" and outputted in the footer. If you are echoing JS directly from PHP,
 * use add_action( 'admin_print_footer_scripts', 'output_my_js', 100 ) or add_action( 'wp_footer', 'output_my_js', 100 )
 *
 * Minimum required to add a button that calls an external function:
 *     QTags.addButton( 'my_id', 'my button', my_callback );
 *     function my_callback() { alert('yeah!'); }
 *
 * Minimum required to add a button that inserts a tag:
 *     QTags.addButton( 'my_id', 'my button', '<span>', '</span>' );
 *     QTags.addButton( 'my_id2', 'my button', '<br />' );
 */

Top ↑

Default Quicktags #Default Quicktags

Here are the values of the default Quicktags added by WordPress to the Text editor (table sorted by access key value). Access key and ID must be unique. When adding your own buttons, do not use these values:

Some tag values above use variables, such as URL and _datetime, passed from functions.

Top ↑

Source File #Source File

qt.addButton() source is located in js/_enqueues/lib/quicktags.js, during build it’s output in wp-incudes/js/quicktags.js and wp-includes/js/quicktags.min.js.