Image Maps Plugin for CKEditor

Introduction

This is a dialog-based plugin to handle insertion and modification of image map areas in CKEditor.

Author:

Alfonso Martínez de Lizarrondo

Version history:

2.0: 1-March-2011. First version ported from the FCKeditor version.
2.1: 18-September-2011. Adjustments of resizing the dialog.
2.2: 15-October-2011. IE8 bug that didn't allow to show the contents of the dialog since [7185].
3.0.0 5-November-2011. Rewritten to fit correctly with the CKEditor dialogs without using the iframe as that's not properly supported by CKEditor (see versions 2.1 and 2.2)
The browser functionality requires a CKEditor version > 3.6.2, because there was a bug that I fixed for this plugin.
3.1.0 15-November-2011. Automatically detect CKEditor version to avoid problems with "browse server" button
Reorganize structure and simplify some parts
3.2.0 31-May-2012. Use a single sprite for the icons
3.2.1 3-June-2012. Fix problem with the detection of CKEditor version
3.3.0 9-July-2012. Fix problems with IE (first click while drawing and double click in the editor)
3.3.1 10-July-2012. Fix problems with Chrome. Switched to use the uncompressed imgmap.js as some changes were required there.
3.3.2 11-July-2012. Avoid drag&drop of the image.
3.3.3 8-September-2012. If the main page was scrolled, drawing of polygons failed in all browsers != IE.
3.4.0 12-September-2012. Added compatibility with CKEditor 4 beta.
IE8 didn't initialize the excanvas library correctly and so circles and polygons were not visible.
3.4.1 21-September-2012. Fixed compatibility problems with the old CKEditor 3.4.1, it's ugly but now the dialog works.
Tooltips for area actions were missing.
3.4.2 Simplification of the dialog options.
Create name attribute for the map if IE is in quirks mode.
3.4.3 13-October-2012 Added an event "imagemaps.validate" to perform custom validation before creating the map.
3.4.4 Swedish translation.
3.5.0 23-February-2013 Integration with CKEditor 4.1 data filtering.
Draw the shapes over the image in the editor (this is a native feature for IE)
3.5.1 3rd-March-2013 I was breaking the selectionChange event in v4 :-(
Handle maps where the name attribute has been removed
IE compatibility bug with the new shape drawing
3.5.2 12-March-2013 Compatibility with devTools plugin.
3.5.3 13-March-2013 Allow the "imagemaps.validate" event to modify the data.
3.5.4 16-March-2013 Remove orphan maps if the image is deleted from the editor.
3.5.5 19-April-2013 Show the image correctly if it was resized with attributes instead of inline styles.
Adjust correctly the 4.1 ACF (the "url" attribute doesn't exist, I'm stupid).
Detect correctly v4 to avoid huge dialogs and provide better layout
Adjusted the language files so the plugin can be compiled correctly with a local install of CKBuilder
Set 'insert' as the toolbargroup for the button (besides image button) instead of the default 'others'
3.5.6 1st-April-2013 Handle better the hover and cursor effects while editing a map in Chrome if the page has been scrolled
Resizing of the preview was disabled in CKEditor 4
3.5.10 24-August-2013 Improved compatibility with CKBuilder (merge icon into the main toolbar strip)
Restrict operations to the editor content (for inline and divarea modes, skip maps and images outside the editor)
Improved drawing of the areas with the image in Chrome
3.5.11 9-December-2013
Adjusted compatibility with IE11
Adjusted for compatibility with the image2 widget in CKEditor 4.3 (still not perfect, but it seems to mostly work)
Remove overlaid areas when removing a map on an image
Set dialog to use Strict mode
Corrected context menu state (it was always "on")
If the window wasn't tall enough to display the whole dialog, most of the times the areas were drawn incorrectly
Removed commented out code and unused methods (preview mode, Bezier curves) in the imgmap library (~24Kb)

Installation

1. Copying the files

Extract the contents of the zip in you plugins directory, so it ends up like this

ckeditor\
	...
	images\
	lang\
	plugins\
		...
		imagemaps\
			icon.png
			plugin.js
			dialog\
			docs\
			images\
			lang\
		...
	skins\
	themes\

2. Adding it to CKEditor

Now add the plugin in your config.js or custom js configuration file: config.extraPlugins='imagemaps'; If you are already using other additional plugins, then you must have a single extraPlugins statements with all the plugins separated by commas: config.extraPlugins='confighelper,imagemaps';

3. Add it to your toolbar

In your toolbar configuration, add a new 'ImageMaps' item in the place where you want the button to show up.

4. Configuration

When the user presses OK in the dialog, if the data is correct a custom "imagemaps.validate" event will be fired, allowing you to add custom validation according to your specific needs. If you cancel that event then the dialog won't close until the user changes the map to pass your validation.

Example of usage: force all links to start with "http://": // Let's add this to every editor on the page. You can instead add it only to a specific editor. CKEDITOR.on('instanceReady', function(e) { // the real listener e.editor.on( 'imagemaps.validate' , function(ev) { // the "imgmap" object is passed as the data property of the event var imgmap = ev.data; for (var i = 0; i < imgmap.areas.length; i++) { if (imgmap.areas[i].ahref.substring(0, 7) != "http://") { alert("All links must start with 'http://'"); // Cancel the event to mark that the validation has failed ev.cancel(); } } }); });

Since version 3.4.2 two options have been set as hidden by default to avoid confusion for the users: map name and alt attribute of each area.
The options are still there ready to be used, and you can enable them by using the typical code that it's used to hide options, but reversed: CKEDITOR.on( 'dialogDefinition', function( ev ) { var dialogName = ev.data.name, dialogDefinition = ev.data.definition; if (dialogName != 'ImageMaps') return; var tab = dialogDefinition.getContents( 'info' ); tab.get( 'ContainerMapName' ).hidden = false; tab.get( 'alt' ).hidden = false; });

5. Use it

Clear your cache and reload your editor. Now when you select an image the new button will be enabled so you can map the active regions. If you select an image with an existing map the button will be highlighted.

6. Translations

To add a new translation open plugin.js and search for "translations", it's at line 6 and add your language (the example is based on adding Polish ('pl') // translations lang : ['en', 'el', 'es'], to// translations lang : ['en', 'el', 'es', 'pl'],

Then in the lang folder copy the en.js to pl.js, edit that file and in the first line set your language: CKEDITOR.addPluginLang( 'imagemaps', 'pl', and finally, translate all the text between quotes :-)

If you send it back to me I'll include it in the next versions.