Adjusting a CKEditor plugin to be compatible with v3 and v4

Recently CKSource announced the first beta of the new CKEditor 4, and along the improvements, it also brings some changes of the API. You can read about those changes in the included API-CHANGES.md file (open it with any text editor, I don't know if there's an easier way to read it correctly)

I'm gonna record here the changes that I have to go through to update my plugins when I touch them (although I'm not gonna try to do full testing until it goes out of beta).

Translations

The first breaking change is that CKEDITOR.plugins.setLang has changed, so now when you pass the object with the translations it must not include the "parent" object, as the doc says:

So, in v3 we had:

    CKEDITOR.plugins.setLang( 'myplugin', 'en',
    {
        myplugin :
        {
            title : 'My Plugin'
        }
    });

In v4 it should be changed to:

    CKEDITOR.plugins.setLang( 'myplugin', 'en',
    {
        title : 'My Plugin'
    });

That's good if you want to release a plugin only for v4 or you plan to ignore it, but if you want to be ready to upgrade and try to make your code compatible with both v3 and v4 you now have a problem because the name of the function hasn't changed but the expected parameters have done so.

So my solution is to create a new helper function and call this one instead of CKEDITOR.plugins.setLang:

CKEDITOR.addPluginLang = function( plugin, lang, obj )
{
    // v3 using feature detection
    if (CKEDITOR.skins)
    {
        var newObj = {};
        newObj[ plugin ] = obj;
        obj = newObj;
    }
    CKEDITOR.plugins.setLang( plugin, lang, obj );
}

This way, we use the new format for the obj parameter, but if the function detects that it's running in v3 it adds the plugin name as the root of all the strings

CKEDITOR.addPluginLang( 'myplugin', 'en',
{
        title : 'My Plugin'
});

Spacer image

Another change is that they decided that leaving the images/spacer.gif file there was polluting the global scope, so now you just have to copy that image in every plugin to be sure that it's included in the install and then adjust the paths in your code to use this copy of the image. It's not a big deal, but certainly to me it doesn't seem a big problem to leave that simple image in a common place so it can be easily reused.

Adding CSS

The doc explain this about this change:

The "additional CSS" feature provided by `CKEDITOR.editor::addCss` is now moved
to a global `CKEDITOR.addCss`, with specified style rules applies **document wide**.

Thus the proper way for a plugin to style it's editable content is to call `CKEDITOR.addCss`
inside of the plugin's `onLoad` function, rather than it's `init` function in v3.

So in order to make your code work in both versions you have to use something like this:

...
    getPlaceholderCss : function()
    {
        return 'img.cke_video' +
                '{' +
                    'background-image: url(' + CKEDITOR.getUrl( this.path + 'images/placeholder.png' ) + ');' +
                    'background-position: center center;' +
                    'background-repeat: no-repeat;' +
                    'background-color:gray;'+
                    'border: 1px solid #a9a9a9;' +
                    'width: 80px;' +
                    'height: 80px;' +
                '}';
    },

    onLoad : function()
    {
        // v4
        if (CKEDITOR.addCss)
            CKEDITOR.addCss( this.getPlaceholderCss() );
    },

    init : function( editor )
    {
....
        // v3
        if (editor.addCss)
            editor.addCss( this.getPlaceholderCss() );
...

 

 

So this is all for the moment. I'll keep editing this post in the future as I upgrade more code.

 

 

Image Mapping plugin for CKEditor

Long time ago I cooperated with Adam Maschek to finish and polish the plugin of his imgmap library for FCKeditor.

Time passed by and people only bothered to request help with private mails instead of saying "Thanks" and even a little donation if the plugin was helpful.

So things go on that way and then I ported it to work for CKEditor when I needed it, but I decided to not publish it again as open source, supporting those request again was something that I didn't want to do.

Sometimes people contacted me asking for the plugin and those that behaved properly and also were willing to pay a little got the plugin. In order to make this step easier for anyone else, I'm publishing now a demo page to test the plugin, and a paypal button.

As you can see in the demo, the dialog is similar to the FCKeditor plugin, but I didn't want to fully match the previous one, so I've added only the features that made sense to me.

Price and availability

You can buy a license of the plugin at its new page.

EasyUpload for CKEditor

Most of the people think that the most commonly used dialogs in CKEditor are too complex for the average user. They show lots of options, and all the info at the same time.

This has always lead to people asking how to change them or how to achieve some feature to simplify that process: I have an image here and I want it there, don't ask me lots of questions and force me to get a degree on HTML in order to understand what's the meaning of all those fields.

So a long time ago I created a simplified version for FCKeditor and now it's the time to show an updated version for CKEditor.

Bear in mind that right now the demo is still half done, I want to show how to use it in different ways so you can get the code to configure it the way that you like just by looking at the demo; and of course, while I polish that part I'll find some adjustments for the plugin.

So you can start testing it in the demo page for Easy Upload for CKEditor. If you have some comments about what you think it's missing you can add them here and I'll try to address them.

What's different from the usual dialogs?

You can check the demo by yourself, but some highlights are:

• If there's no image selected, the user is shown a simple page allowing him to choose the source of the image.
• The extension of the image is validated before uploading it to the server
• While uploading a file from his computer an animation is shown to signal the user that he must wait
• When the image is ready, a simplified dialog is shown

Edit 27th November 2013

I've removed the option to get this plugin and instead I suggest you to use the SimpleUploads and use the CKEditor API to remove elements from the default dialogs.

I'll try to provide a sample page to show how to do that, with the advantage that now instead of a copy of the link or image dialogs you will be using the built-in dialogs and it will be easier to do version upgrades whenever CKEditor changes.

 

Drag and Drop uploads in CKEditor

Recently I was asked about a video that I added to YouTube some time ago: making drag&drop uploads work in CKEditor.
That video was a little test and I used a non-public modification of the image paste plugin that allows to automatically upload images that are pasted in Firefox. The video shows how to use drag and drop from the file system into a CKEditor instance and get that image or file uploaded to the server and inserted into the editor without any extra steps, if you know how to drag a file, adding it to CKEditor can't be any simpler.
The base of that code is XHR2 and FormData to send a File object to the server as well as the dataTransfer interface in the drop event and finally some API to find the correct drop location.
What does all those buzzwords mean?
Just that there are no browser plugins involved, if you use a browser that supports those new APIs then this feature will work: for Firefox, Chrome and Safari you can use the current stable versions, if you use IE then you need the IE 10 preview, and unfortunately Opera supports most of those features in Opera 12, but not the API to get the insertion point, so at the moment it's the only engine that it's left out.

Getting the plugin

The plugin is available in the version 4 page.

Demo

If you want to check how it works, you can use this demo page.

History

2.0 First release including drag&drop
2.1 June 17th, 2012. Added support for pasting in Chrome, correctly process files copied and pasted in Firefox  from the desktop if they aren't png. Support dropping multiple files.

version 3 is explained here

Steps to shutdown windows

Using the current Windows 7 (previous versions is quite similar and everyone has learnt how to do it):

1. Go to the Start or Windows button in the lower left corner.
2. Click it
3. Click the Shutdown button.
4. Done!

Using the Windows 8 Release Preview

1. Uh, there's nothing at the lower left corner?
2. Anyway, move the mouse there, maybe there's a glitch in the graphics as everyone is used to know that there are strange bugs in Windows sometimes
3. Clicking there doesn't do anything.
4. Move to the really lower bottom corner
5. A "Start" popup appers
6. After hunting it a little you're finally able to click it
7. Congratulations, you're now back to the "Windows Metro" screen.
8. At least now you have an icon about your account on the top right
9. Click it.
10. In that dropdown select "Sign out"
11. We're back to the start screen. Now we have the plug&screen icon. Click it.
12. So now we can login again...
13. But theres a Power icon at the bottom right
14. Yeah, click it
15. Now select "Shut down"
16. Finally you got it!!!

Ok, there are some faster ways:

1. Move your mouse to the bottom right corner
2. Yes, I know that there's no hint that you should move your mouse there, but there isn't also any hint now about the bottom left corner.
3. Some white icons appear above. Go to the last one, the one that looks like a gear.
4. Now you see that it's titled Settings. Not promising, but please, click it.
5. Now a pane shows up, there are two rows of icons below, and one of them is Power
6. Click it
7. Select Shut down
8. You're done.

Using this method we have been able to halve the steps required to shutdown windows. Now you just have to print this short list and paste it at the right side of the monitor of anyone that has to use Windows 8.

That way Microsoft is saving some little pixels on the screen and you just have a little post it on your screen.

 

Creating a button to insert some HTML in CKEditor

Sometimes it can be useful to have a toolbar button in CKEditor to insert a predefined block of HTML. The fact is that creating such option is quite easy, but for those that don't know much about javascript it might look more complex than it really is.
So this plugin allows to define as many new toolbar buttons as desired just by specifiying their properties in a config object.
After adding the "htmlbuttons" plugin you can add to your configuration a new entry "htmlbuttons" (yes, the same name I didn't want to think today). That entry must be an array of javascript objects, and each object has four properties; here's one example:

{
 name:'button1',
 icon:'icon1.png',
 html:'<a href="http://www.google.com">Search something</a>',
 title:'A link to Google'
},

First, the name for the command and button that you can use in the toolbar. Then the icon to use (place them in the plugin folder), next is the block of HTML that you want to insert, and finally a title to show up while hovering the button.
So now you can add those new buttons to your toolbar and when you reload the editor you can use those buttons to insert the HTML.
This sample shows the plugin in action with the default sample buttons (icons picked randomly from the Tango! project, if someone has some suggestions about better code samples and icons they're welcome).
The buttons (the three smileys) are from left to right:

1. Insert a link pointing to Google
2. Insert a 2x2 table
3. Insert a nested list

This is an editor. Test the buttons!

Download:
Edit 2016: go to CKEditor plugins repository:
HTML Buttons plugin

White list of elements and attributes for CKEditor

Sometimes you want to use CKEditor in a page where you can't fully trust the users, so they will have a restricted version with just some basic features: headings, bold, maybe links and images...

Of course it's easy to adjust the toolbar to show only those options, and with a good filter at the server you can be quite safe to accept the situation, but it would be even better if anything that will be stripped out at the server couldn't be added to the editor for example by pasting.

The fact is that using the dataProcessor of CKEditor it isn't too hard to setup something basic to perform the task: listen for each element and reject the ones that aren't whitelisted.

I've created a little plugin that does that job. It comes preconfigured with just some basic elements and attributes, but it's possible to modify that as it's just a simple javascript object that you can define in the CKEditor configuration.

Download: Whitelist plugin for CKEditor 1.1

Please, remember that you must use a filter at the server to perform at the very least the same filtering (or better) because this is not a real security option.

For PHP you can use HTML Purifier, in the case of Asp.Net previously the solution was the Microsoft AntiXss library but in January they released a broken version and haven't fixed it despite the complains. (Does anyone know an alternative solution)

 

This sample uses the default whitelist so it won't allow most HTML elements, and only basic attributes on links or images.

This a whitelisted editor

Edit: 20/01/13

Updated to version 1.1 to fix the attributes bug mentioned by Chris Hough