Adding Custom Buttons and Plugins to WordPress 3.5 and CKEditor

Adding Custom Buttons and Plugins to WordPress 3.5 and CKEditor

Unfortunately, there's not a lot of documentation out there on how to properly add custom buttons to WordPress' CKEditor main editor / format utility.  That's about to change.  Based on countless hours of searching the internet and posting on various forums, I've found the easy way to add custom buttons that perform their own functions and format certain pieces of text using custom css classes that I've defined in the main style sheet.

HTMLButtons Easy Plugin

This plugin allows you to easily create as many buttons as desired for both the full editor (the one you see when making a post on your WordPress blog) or the basic editor (the one visitors see when leaving comments).  The first step is to download this plugin.

I modified this version of HTMLButtons myself, which is why it's version 1.3. (versions 1.1 and up were also released by me).  Version 1.3 fixes a few bugs, keeps inline HTML formatting when modifying selected text, processes partial selections properly, and processes block selections properly.  The mouse pointer location is also reset correctly to the original selection in version 1.3.  When you click on your custom buttons to insert block elements, the text and HTML inline elements within the selection will be preserved.  The highlighted text is appended within element tags.  This is better than the initial implementation.  If nothing is selected, the elements are inserted with the pointer inbetween these elements.

For more information on the original version 1.0 HTMLButtons plugin or to find out about the original author, click here.

Once you've downloaded this plugin, unzip the files into a folder that you can easily find.  Now, we need to edit this plugin and configure our custom buttons.  Open plugin.js using a text editor such as PSPad or Notepad from the folder where you extracted the contents of htmlbuttons1.0.  Scroll down to the line that starts with:

CKEDITOR.config.htmlbuttons

You'll see three buttons defined here:

CKEDITOR.config.htmlbuttons =  [
    {
        name:'button1',
        icon:'icon1.png',
        html:'<a href="http://www.google.com">Search something</a>',
        title:'A link to Google'
    },
    {
        name:'button2',
        icon:'icon2.png',
        html:'<table style="min-width:200px"><tr><td>&nbsp;</td><td>&nbsp;</td></tr><tr><td>&nbsp;</td><td>&nbsp;</td></tr></table>',
        title:'A simple table'
    },
    {
        name:'button3',
        icon:'icon3.png',
        html:'<ol><li>Item 1 <ol><li>Sub item 1</li><li>Sub item 2</li></ol></li></ol>',
        title:'A nested list'
    }
];

The name of each button is how we will reference it when adding it to the full and basic editor.  Icon specifies which picture should be displayed for the button.  Button icons should be 15 pixels by 15 pixels.  You can create custom icons using an image editor.  HTML specifies what should be inserted to the actual source of your post when clicked on.  It will automatically insert text within this statement.  As an example, check out one of my own button declarations:

name:'button3',
icon:'custcode.png',
html:'<div class="customCode"><pre> </pre></div>',
title:'Custom Code'

The above button declaration will insert a div and pre element into the source of my post and place the pointer inbetween the pre tags.  Thus, any text that is typed once the button has been clicked will be wrapped within the div and pre elements.  You can also highlight text and click the button.  If you highlight text and then hit the button, the highlighted text will be automatically inserted within the div and pre opening tags and before the end tags.  You can add as many buttons as you like following the template or remove as many as you wish.

I'm done editing what I want my buttons to do.  What next?

Next, you'll need to upload your htmlbuttons plugin folder to the wp-content/plugins/ckeditor-for-wordpress/ckeditor/plugins/ directory.  Once this has been done, open the wp-content/plugins/ckeditor-for-wordpress/ckeditor.config.js using a text editor.  Under:

CKEDITOR.editorConfig = function(config) {

Add the following line:

// Added custom plugs
config.extraPlugins = 'htmlbuttons'; 

 The basic editor definition is here:

// WordPress basic toolbar
    config.toolbar_WordpressBasic = [
        { name: 'basicstyles', groups: [ 'basicstyles', 'cleanup' ], items: [ 'Bold', 'Italic', 'Strike', '-', 'RemoveFormat' ] },
        { name: 'paragraph', groups: [ 'list', 'indent', 'blocks', 'align', 'bidi' ], items: [ 'Blockquote', '-', 'JustifyLeft', 'JustifyCenter', 'JustifyRight'] },
        { name: 'links', items: [ 'Link', 'Unlink' ] },
        { name: 'insert', items: [ 'Image', 'SpecialChar' ] }
    ];

 To add your button to the basic styles group, just add the following items to the end of the basic styles definition like so (depends on how many buttons you've created of course):

{ name: 'basicstyles', groups: [ 'basicstyles', 'cleanup' ], items: [ 'Bold', 'Italic', 'Strike', '-', 'RemoveFormat', 'button1', 'button2', 'button3' ] },

Your buttons will be added to the basic editor which is seen when leaving comments.

The full editor definition is a little different.  Here's what it looks like by default:

// The equivalent of "WordpressFull" toolbar, defined in a way that makes adding buttons from plugins easier.
    config.toolbarGroups = [
        { name: 'document',    groups: [ 'mode', 'document', 'doctools' ] },
        { name: 'clipboard',   groups: [ 'clipboard', 'undo' ] },
        { name: 'editing',     groups: [ 'find', 'selection', 'spellchecker' ] },
        // { name: 'forms' },
        '/',
        { name: 'paragraph',   groups: [ 'list', 'indent', 'blocks', 'align' ] },
        { name: 'links' },
        { name: 'insert' },
        { name: 'wordpress' },
        '/',
        { name: 'basicstyles', groups: [ 'basicstyles', 'cleanup' ] },
        { name: 'styles' },
        { name: 'colors' },
        { name: 'tools' },
        { name: 'about' }
    ];

 Depending on where you want to add your custom buttons, you'll need to create a new group with its own name and items definition that will be added to the list.  I wanted my buttons before the bold, italics, and underline buttons, so I added my declaration here:

{ name: 'wordpress' },
'/',
{ name: 'custom', items: [ 'button1', 'button2', 'button3' ] },
{ name: 'basicstyles', groups: [ 'basicstyles', 'cleanup' ] },

 This will insert our custom buttons before the basicstyles controls in the full editor (the one you see when making a new post / blog)

You're done.  Here's what my full ckeditor.config.js file contains:

/*
Copyright (c) 2003-2010, CKSource – Frederico Knabben. All rights reserved.
For licensing, see LICENSE.html or http://ckeditor.com/license
*/

/**
 * Documentation:
 * http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html
 */

CKEDITOR.editorConfig = function(config) {

  // Added custom plugs
  config.extraPlugins = 'htmlbuttons';      

    // The minimum editor width, in pixels, when resizing it with the resize handle.
    config.resize_minWidth = 450;
   
    // Protect PHP code tags (<?…?>) so CKEditor will not break them when
    // switching from Source to WYSIWYG.
    config.protectedSource.push(/<\?[\s\S]*?\?>/g);

    // Define toolbars, you can remove or add buttons.
    // List of all buttons is here: http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.toolbar_Full

    // WordPress basic toolbar
    config.toolbar_WordpressBasic = [
        { name: 'basicstyles', groups: [ 'basicstyles', 'cleanup' ], items: [ 'Bold', 'Italic', 'Strike', '-', 'RemoveFormat', 'button1', 'button2', 'button3' ] },
        { name: 'paragraph', groups: [ 'list', 'indent', 'blocks', 'align', 'bidi' ], items: [ 'Blockquote', '-', 'JustifyLeft', 'JustifyCenter', 'JustifyRight'] },
        { name: 'links', items: [ 'Link', 'Unlink' ] },
        { name: 'insert', items: [ 'Image', 'SpecialChar' ] }
    ];

    // The equivalent of "WordpressFull" toolbar, defined in a way that makes adding buttons from plugins easier.
    config.toolbarGroups = [
        { name: 'document',    groups: [ 'mode', 'document', 'doctools' ] },
        { name: 'clipboard',   groups: [ 'clipboard', 'undo' ] },
        { name: 'editing',     groups: [ 'find', 'selection', 'spellchecker' ] },
        // { name: 'forms' },
        '/',
        { name: 'paragraph',   groups: [ 'list', 'indent', 'blocks', 'align' ] },
        { name: 'links' },
        { name: 'insert' },
        { name: 'wordpress' },
        '/',
    { name: 'custom', items: [ 'button1', 'button2', 'button3' ] },
        { name: 'basicstyles', groups: [ 'basicstyles', 'cleanup' ] },
        { name: 'styles' },
        { name: 'colors' },
        { name: 'tools' },
        { name: 'about' }
    ];

    // Remove buttons in "WordpressFull" toolbar
    config.WordpressFull_removeButtons = 'Save,NewPage,Preview,Print,Templates,CreateDiv,PageBreak,Subscript,Superscript,Styles';

    //IE: remove border of image when is as a link
    config.extraCss = "a img { border: 0px\\9; }";
                                                          
    // mediaembed plugin
    // config.extraPlugins += (config.extraPlugins ? ',mediaembed' : 'mediaembed' );
    // CKEDITOR.plugins.addExternal('mediaembed', ckeditorSettings.pluginPath + 'plugins/mediaembed/');
};

 

That's all you need to edit.  Save the file, upload it to the server, and overwrite the existing file.  You should now see your custom buttons, and they should work when you click on them based on how you defined their behavior.

What does your button do from your example?

My button allows me to create html code that is formatted using a class I defined in the wp-content/themes/[current theme you're using]/style.css stylesheet.  The class of customCode has the following definition:

div.customCode {padding:5px; background-color: #ecfef0; font-family: 'arial'; font-style: italic; color: black; font-size: 17px; margin-top: 1em; margin-bottom: 1em; overflow: auto;}

Thus, when the button is clicked, I have inserted custom code into the source of the post that will format the text exactly as I have defined.  This is a great shortcut to be able to make my blog posts look exactly how I want them to look.

My End Product:

Tags: , , , , , , , , , , , , , , , , , , , , , , ,

Leave a Reply

You must be logged in to post a comment.