# 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:

1. 2.0: 1-March-2011. First version ported from the FCKeditor version.
2. 2.1: 18-September-2011. Adjustments of resizing the dialog.
3. 2.2: 15-October-2011. IE8 bug that didn't allow to show the contents of the dialog since [7185].
4. 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.
5. 3.1.0 15-November-2011. Automatically detect CKEditor version to avoid problems with "browse server" button
   Reorganize structure and simplify some parts
6. 3.2.0 31-May-2012. Use a single sprite for the icons
7. 3.2.1 3-June-2012. Fix problem with the detection of CKEditor version
8. 3.3.0 9-July-2012. Fix problems with IE (first click while drawing and double click in the editor)
9. 3.3.1 10-July-2012. Fix problems with Chrome. Switched to use the uncompressed imgmap.js as some changes were required there.
10. 3.3.2 11-July-2012. Avoid drag&drop of the image.
11. 3.3.3 8-September-2012. If the main page was scrolled, drawing of polygons failed in all browsers != IE.
12. 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.
13. 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.
14. 3.4.2 Simplification of the dialog options.
    Create name attribute for the map if IE is in quirks mode.
15. 3.4.3 13-October-2012 Added an event "imagemaps.validate" to perform custom validation before creating the map.
16. 3.4.4 Swedish translation.
17. 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)
18. 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
19. 3.5.2 12-March-2013 Compatibility with devTools plugin.
20. 3.5.3 13-March-2013 Allow the "imagemaps.validate" event to modify the data.
21. 3.5.4 16-March-2013 Remove orphan maps if the image is deleted from the editor.

## 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';`

### 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.

## Disclaimers

CKEditor is © CKSource.com

The core imgmap code is © Adam Maschek