Custom Buttons API


Beginning with WP Edit Version 4.0 (and WP Edit Pro Version 5.0); the WP Edit (Pro) Custom Buttons API will be introduced, allowing other WordPress plugin/theme developers to add their buttons into the WP Edit (Pro) button configuration system.

Using the Custom Buttons API will allow a user of WP Edit (Pro) to place the custom plugin or theme button in any editor row (and location) as desired.

The following article is intended for plugin/theme developers. Please do not attempt to edit code unless experienced.

Create Buttons Normally

The buttons will still need to be created normally; just like any other editor buttons. This will involve both adding the button to the editor; and initializing the code for the button.

Creating the buttons normally will also ensure they are visible in the content editor, until the WP Edit (Pro) user has a chance to visit the WP Edit (Pro) admin settings page and set the button arrangement; or if WP Edit (Pro) is deactivated.

Adding Buttons to Editor

The first step is adding the button to the editor. There are many articles on how to add a custom button to the tinymce editor; so I’ll just cover the basics.

Typically, adding a button to the editor will look like:

add_filter( 'mce_buttons_2', 'myplugin_register_buttons' );
function myplugin_register_buttons( $buttons ) {

    array_push( $buttons, 'my_plugin_button' );
return $buttons;
}

Here, my_plugin_button is the name of the button being added in the editor button javscript file.

Adding Initialization Code

The next step is adding the plugin to the external plugins filter. This tells WordPress where the javascript file is located that handles the button. Again, there are many articles so I’ll just cover the basics.

add_filter( 'mce_external_plugins', 'myplugin_register_tinymce_javascript' );
function myplugin_register_tinymce_javascript( $plugin_array ) {
	
   $plugin_array['my_plugin_js'] = plugins_url( '/js/tinymce-plugin.js',__FILE__ );
   return $plugin_array;
}

Here, my_plugin_js is the name of the plugin being added in the editor button javascript file.
The plugins_url( '/js/tinymce-plugin.js',__FILE__ ); is the location of the editor button javascript file.

Quick View of Javascript Button Code

Just for reference, let’s see where these values come from in the javascript code used for the editor button:

(function() {
    tinymce.PluginManager.add('my_plugin_js', function( editor, url ) {
		
        editor.addButton('my_plugin_button', {
			
            text: 'My Plugin',
            onclick: function() {

                editor.insertContent('WP Edit (Pro) is awesome!');
            }
        });
    });
})();

The my_plugin_js is the unique name of the button plugin being passed to the editor Plugin Manager. The same value is used in the mce_external_plugins filter being passed to WordPress. Finally, the button_id value in the custom buttons API must also match this value.

The my_plugin_button is the unique name of the actual button, and is the same value used in the mce_buttons_2 filter being passed to WordPress.

Custom Buttons API

WP Edit (Pro) provides a custom buttons API to allow plugin/theme developers to add their editor buttons into the WP Edit (Pro) button configuration system. This will allow end users to place the button in any desired location in the editor toolbars.

Developers can access this system by using the wp_edit_custom_buttons filter. The filter provides one argument; which is an array of arrays, each containing seven key/value pairs. New buttons can be added by appending a new array (or arrays) to the filter.

These values only affect how the button appears on the WP Edit (Pro) admin settings page; and do not interfere with how the button is displayed in the content editor.


Key Type Value
tooltip_title (string) (required) The title of the button; shown on fancy tooltip.
If fancy tooltips are disabled; this title will be displayed using the “title” attribute.
tooltip_content (string) (required) The content of the button; shown on the fancy tooltip.
Content accepts html tags. Wrap sentences with paragraph tags.
Use this to display a brief message regarding the functionality of the button.
button_id (string) (required) This value MUST match the name of the “mce_external_plugins” filter key used to add the javascript file for the editor button.
It is the same value used in the javascript file to create the button being used (TinyMCE.PluginManager.add(‘THIS VALUE’, …)).
dashicon (string) (optional) WP Edit includes the WordPress “dashicons” stylesheet.
This value should only be set if the button icon will be loaded from the dashicons stylesheet.
An example value might be “dashicons dashicons-editor-ul” or “dashicons dashicons-editor-ol”.
If this value is set; the “button_text” value must be blank.
custom_icon (string) (optional) This value can be used for a custom button image.
An example might be:
plugins_url() . '/my_plugin/my_editor_button/images/my_image.png'
Recommended image size is 20px by 20px.
If this value is set; the “button_text” value must be blank.
button_text (string) (optional) The text to be shown on the button.
This should only be used if the button is labled with text (no icon).
If an image is used instead (in the “dashicon” or “custom_icon” value; leave this field blank.
editor_row (string) (optional) The editor toolbar row where the button should be appended (until moved and saved by user).
Possible values are:
A) ‘toolbar1’ (string)
B) ‘toolbar2’ (string)

Text Button Example

Adding a text button simply involves passing the text of the button as the “button_text” value. Be sure to leave the “dashicon” and “custom_icon” values blank; if a text value is set.

add_filter( 'wp_edit_custom_buttons', 'wp_edit_button_filter' );
function wp_edit_button_filter( $args ) {
	
    $args[] = array( 
	
	'tooltip_title' => 'Test Plugin',
	'tooltip_content' => '<p>Test Plugin content.</p>',
	'button_id' => 'test_plugin',
	'dashicon' => '',
	'custom_icon' => '',
	'button_text' => 'Test Plugin',
	'editor_row' => 'toolbar2'
    );

    // Important; return original filter $args
    return $args;
}

Basically, we are appending a new array to the incoming array being filtered. This example will add a new button titled “Test Plugin”, and add it to the WP Edit (Pro) buttons container (second row).

Custom Buttons API

Dashicon Button Example

A WordPress Dashicon may also be used for the WP Edit (Pro) button image. Visit the WordPress Dashicons Webpage; and select which icon will be used. Next, click the “Copy HTML” link. This will display a javascript alert; containing the dashicon code.

The code for a dashicon (after clicking “Copy HTML”) will contain some extra html markup (a span container). All that is needed are the class names inside the span tag. For example, <span class="dashicons dashicons-admin-tools"></span> becomes just dashicons dashicons-admin-tools.
add_filter( 'wp_edit_custom_buttons', 'wp_edit_button_filter' );
function wp_edit_button_filter( $args ) {
	
    $args[] = array( 
	
	'tooltip_title' => 'Test Plugin',
	'tooltip_content' => '<p>Test Plugin content.</p>',
	'button_id' => 'test_plugin',
	'dashicon' => 'dashicons dashicons-admin-tools',
	'custom_icon' => '',
	'button_text' => '',
	'editor_row' => 'toolbar2'
    );

    // Important; return original filter $args
    return $args;
}

Basically, we are appending a new array to the incoming array being filtered. This example will add a new button with the dashicon image, and add it to the WP Edit (Pro) buttons container (second row).

Custom Buttons API

Custom Icon Button Example

Finally, a custom icon can be used for the WP Edit (Pro) button image. When using a custom button; the location of the image will need to be passed in the “custom_icon” value.

Recommended image size for the WP Edit (Pro) button image is 20px by 20px.
add_filter( 'wp_edit_custom_buttons', 'wp_edit_button_filter' );
function wp_edit_button_filter( $args ) {
	
    $args[] = array( 
	
	'tooltip_title' => 'Test Plugin',
	'tooltip_content' => '<p>Test Plugin content.</p>',
	'button_id' => 'test_plugin',
	'dashicon' => '',
	'custom_icon' => plugins_url() . '/my_plugin/my_editor_button/images/my_image.png',
	'button_text' => '',
	'editor_row' => 'toolbar2'
    );

    // Important; return original filter $args
    return $args;
}

Basically, we are appending a new array to the incoming array being filtered. This example will add a new button with the custom image, and add it to the WP Edit (Pro) buttons container (second row).

Custom Buttons API

Multiple Buttons Example

Adding multiple buttons to the Custom Buttons API is easy. Just create additional arrays to accommodate each additional editor button.

add_filter( 'wp_edit_custom_buttons', 'wp_edit_button_filter' );
function wp_edit_button_filter( $args ) {
	
    $args[] = array( 
	
	'tooltip_title' => 'Test Plugin',
	'tooltip_content' => '<p>Test Plugin content.</p>',
	'button_id' => 'test_plugin',
	'dashicon' => 'dashicons dashicons-admin-tools',
	'custom_icon' => '',
	'button_text' => '',
	'editor_row' => 'toolbar2'
    );
	
    $args[] = array( 
	
	'tooltip_title' => 'Test Plugin 2',
	'tooltip_content' => '<p>Test Plugin content 2.</p>',
	'button_id' => 'test_plugin_2',
	'dashicon' => '',
	'custom_icon' => plugins_url() . '/my_plugin/my_editor_button/images/my_image.png',
	'button_text' => '',
	'editor_row' => 'toolbar2'
    );

    // Important; return original filter $args
    return $args;
}

The result is two buttons being added to the WP Edit (Pro) buttons container (second row).

Custom Buttons API

Full Code Example

The full code example below can be used as reference.

add_filter( 'mce_buttons_2', 'myplugin_register_buttons' );
function myplugin_register_buttons( $buttons ) {

    array_push( $buttons, 'my_plugin_button' );
    return $buttons;
}

add_filter( 'mce_external_plugins', 'myplugin_register_tinymce_javascript' );
function myplugin_register_tinymce_javascript( $plugin_array ) {
	
   $plugin_array['my_plugin_js'] = plugins_url( '/js/tinymce-plugin.js',__FILE__ );
   return $plugin_array;
}

add_filter( 'wp_edit_custom_buttons', 'wp_edit_button_filter' );
function wp_edit_button_filter( $args ) {
	
    $args[] = array( 
	
	'tooltip_title' => 'Test Plugin',
	'tooltip_content' => '<p>Test Plugin content.</p>',
	'button_id' => 'my_plugin_js',
	'dashicon' => '',
	'custom_icon' => plugins_url() . '/my_plugin/my_editor_button/images/my_image.png',
	'button_text' => '',
	'editor_row' => 'toolbar2'
    );

    // Important; return original filter $args
    return $args;
}

User Experience

Let’s outline what the end-user of WP Edit (Pro) will see when the filtered buttons are applied.

Phase One

If the end-user has not yet visited the WP Edit (Pro) admin settings page to save the new buttons (or if WP Edit (Pro) is deactivated); the editor buttons will be appended to whichever editor row was used when “Creating the Buttons Normally” (detailed above).

Custom Buttons API

Phase Two

Once the end-user visits the WP Edit (Pro) admin settings page; a notice will be displayed alerting the user new buttons have been added to the container.

Custom Buttons API

Phase Three

After the user places the buttons in a new location and saves; the process is complete. The buttons will now appear in the same location in the editor.

WP Edit (Pro) Buttons Editor
Custom Buttons API

Post/Page Content Editor
Custom Buttons API

Conclusion

As illustrated above; it’s really simple to add buttons to the WP Edit (Pro) button Custom Buttons API. A single function will allow other plugin/theme plugins to add their buttons to a system which allows the end-user to place the buttons in any custom arrangement.

Notes

  • It is important to both add the button manually; and via the WP Edit (Pro) Custom Buttons API. This will ensure the button is shown in the editor even if WP Edit (Pro) is deactivated. Once the end user saves the WP Edit (Pro) buttons; the new button locations will appear in the editor.
  • When using the wp_edit_custom_buttons filter; it is VERY important to return the $args array, or else it will prevent other plugin/theme buttons from rendering.
  • If adding multiple buttons; the button_id must be unique for each button. In fact; it is a good idea to namespace the button with a unique prefix; which will prevent clashes with other plugin/theme buttons.
  • Both the Free version and the Paid version of WP Edit use the same wp_edit_custom_buttons filter. There is no need to code buttons for both plugins separately. The custom buttons will be recognized by either WP Edit version.

Help

If you would like some assistance with setting the WP Edit (Pro) Custom Buttons API filter properly; please feel free to open a support ticket on the WP Edit Pro Support Website.


Josh Lobe has written 54 articles

Josh Lobe is the sole developer of WP Edit and WP Edit Pro. A father of two; a husband to a beautiful wife; and a small home in the suburbs… he primarily enjoys coding in WordPress and designing websites.

One thought on “Custom Buttons API

Leave a Reply

Your email address will not be published. Required fields are marked *

ENTER CAPTCHA MATH *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>