# GoogleMaps Plugin for CKEditor

## Introduction

This is a dialog-based plugin to handle insertion and modification of Google Maps in CKEditor

### Author:

Alfonso Martínez de Lizarrondo

### Sponsored by:

Ani López, SEO Consultant

Uritec

InControl Solutions

Moava

### Version history:

1. 1.0: 25/08/2007. First version for FCKeditor
2. 1.x: Several improvements and features.
3. 2.0: 30/11/2008. Lots of changes. Changed to closed source
4. 2.x: Mainly corrections and bug fixing
5. 3.0: xx/08/2010. Rewritten for CKEditor 3.4 and Google Maps API v3:
   - It doesn't require a maps API key
   - Improved performance of the maps
   - The dialog is located in the main document, so config.GoogleMaps_DialogCss is no longer needed
6. 3.1: 29/11/2011.
   - Tested with CKEditor 3.6.2 and Google Maps v3.7.
   - Fixing previous bugs
   - Enabled creating and deleting lines and areas.
7. 3.2: 13/05/2012.
   - Tested with CKEditor 3.6.3 and Google Maps v3.8.11.
   - Fixing reported problems
   - Context menu and double click in the editor are handled exclusively
   - It's possible to delete single points in Lines and Areas.
   - Enabled Traffic and Weather layers.
   - End script can be configured with config.googleMaps_endScriptPath.
   - Image buttons merged in a single sprite.
   - Reorder translations so it uses English if a better one isn't available.
   - New translations: ar, cs, fi, fr, sk, tr.
8. 3.2.xx: xXx
   - Option to use custom icons in the markers.
   - Bug fixing several problems
   - It's possible to edit Lines and Areas
9. 3.3: 7-August-2012.
   - Option to set the custom icons from the dialog instead of only from the config file
   - Use shadows for the markers (for default and custom icons).
   - Several new configuration options
   - Button in the editor for markers to insert a "Destination" link.
   - Remember which info windows on markers should be open.
   - New texts since 3.2:
     transit : 'Transit',
     directions : 'Add Directions link',
     directionsTitle : 'Directions',
10. 3.3.1: 8-August-2012.
    - Lines and areas were drawn incorrectly in IE9
    - Bug fix of using custom icons added in the dialog. Beware that anything show on a static map must be placed in a public server (localhost won't work)
11. 3.3.2: 9-August-2012.
    - Force redraw of the last segment of areas in static maps
    - Better resize in IE of the marker and icon dialogs
12. 3.3.3: 9-August-2012.
    - New icons didn't work correctly if there was no one defined in the config.
13. 3.3.4: 1-November-2012.
    - Compatibility with CKEditor 4.
    - Avoid problems if parts of the Google Maps or other Google libraries are already loaded.
14. 3.3.5: 26-November-2012.
    - Avoid error if two maps are present in the same page.
15. 3.3.6: 6-December-2012.
    - Avoid problems while inserting Markers and Text notes if there are Lines or Areas in the map.
    - Try to avoid layout problems due to the excesive padding in the dialogs of Moono (default skin for v4).
    - Little error while creating a Text note.
16. 3.3.7: 6-December-2012.
    - Corrected compatibility of languages with CKBuilder.
17. 3.3.8: 13-December-2012.
    - Validate that the 'zoom' value is always numeric and not a string.
    - Kml files were not working properly .
18. 3.3.9: 16-December-2012.
    - Validate better the path to Kml files.
19. 3.4.0: 10-March-2013.
    - Compatibility with data filtering of upcoming CKEditor 4.1.
    - Compatibility with scripts that continously call editor.getData() (like the "Wordcount" plugin) instead of detecting changes.
20. 3.4.1: 12-March-2013.
    - Compatibility with devTools plugin.
21. 3.4.2 18-May-2013
    - Compatibility with Bootstrap in the map dialog.
    - Set <script> as the requirement for the ACF in CKEditor 4.1.
22. 3.4.3 13-June-2013
    - Handle correctly custom icons placed in folders with dots.
23. 3.4.4 26-June-2013
    - Support loading of maps in hidden divs. Call "initGmapsLoader()" when a hidden div is show to refresh the size of the maps. Also such maps can be configured to not load the Google libraries on page load.
24. 3.4.5 24-August-2013
    - Improved compatibility with CKBuilder (merge icon into the main toolbar strip).
    - Enabled "strict mode" and fixed issues.
    - Update "Text notes" code to draw and update properly in the dialog.
25. 3.4.6 9-September-2013
    - Detect correctly the map id if the output has the line feeds removed.
    - Add the optional div wrapper class to the ACF.
26. 3.5.0
    - Included support to specify an API Key. For the moment it seems that the maps work correctly without a key, but in the future Google might change its mind, so it's better to include support right now. You can set it using ".googleMaps_ApiKey"
    - Added new configuration option ".googleMaps_weatherUsaUnits" to set the weather in Fahrenheit and Wind speed in Miles/hour.
    - Set empty alt attribute on the image to avoid problems with the ACF.
27. 3.5.1
    - Fixed bug in the final page when areas are used due to wrong variable assignment.
28. 3.5.2 13-October-2013
    - Use of streetview data
    - Enabled drawing of circles. In the static images circles won't be shown
    - If the map has been set to 45º imagery or it has been rotated, use that info (this won't work also with the static image)
    - Make the maps work automatically if the contents are inserted into a fully loaded page (for example loaded by ajax or a preview page of the editor).
    - Cache the geolocation data on creation of the first map to speed up further requests
    - Hidden the options to specify the zoom control and map types
    - Corrected the ability to display Traffic or Transit
    - Unified the options to specify the road types and added Bicycle
29. 3.5.3 21-November-2013
    - If a onLoadedGMaps function is defined, call it after the maps have been loaded, a "loadedGMaps" includes the references to the created maps (use Firebug or similar to inspect the objects)
    - Compatibility with IE11
    - Compatibility with the new "image2" widget of CKEditor 4.3
    - Try to limit the URL length of static maps
30. 3.5.4 20-January-2014
    - Removed console.log call left in the code
    - Better compatibility with recent changes in CKEditor
31. 3.5.5 2-February-2014
    - Added Autocomplete for the Search location field
32. 3.5.6 13-February-2014
    - Fixed compatibility with CKEditor 4.3.2
33. 3.5.7 2-June-2015
    - Testing responsive mode
34. 3.5.8 19-July-2015
    - Responsive mode take 2: enabled automatically, restricting the size of the map.
    - Use the "Click to load" option automatically when the browser is mobile to improve the usability as well as avoid bandwidth usage
    - If the div map has set "text-align: center" to center the map, then convert it to margin:0 auto
35. 3.6.0 3-July-2016
    - Review the usage of the Google Maps API key, remove sensor parameter.

### Known bugs:

Google bar isn't available.

## 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\
    		...
    		googlemaps\
    			...
    			plugin.js
    			readme.html
    			dialogs\
    			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='googlemaps';` 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,googlemaps';`

### 3. Adding it to the toolbarset

Add the button 'GoogleMaps' (case sensitive) to your toolbarset: `config.toolbar_Full = [ ['Source','-','Save','NewPage','Preview','-','Templates'], ['Cut','Copy','Paste','PasteText','PasteFromWord','-','Print', 'SpellChecker', 'Scayt'], ['Undo','Redo','-','Find','Replace','-','SelectAll','RemoveFormat'], ['Form', 'Checkbox', 'Radio', 'TextField', 'Textarea', 'Select', 'Button', 'ImageButton', 'HiddenField'], '/', ['Bold','Italic','Underline','Strike','-','Subscript','Superscript'], ['NumberedList','BulletedList','-','Outdent','Indent','Blockquote'], ['JustifyLeft','JustifyCenter','JustifyRight','JustifyBlock'], ['Link','Unlink','Anchor'], ['Image','Flash','Table','HorizontalRule','Smiley','SpecialChar','PageBreak'], '/', ['Styles','Format','Font','FontSize'], ['TextColor','BGColor'], ['Maximize', 'ShowBlocks','-','About'], ['GoogleMaps'] ];`

### 4. Configure the plugin

Since 22nd June 2016 Google requires the usage of an API key, you must fill the 'googleMaps_ApiKey' entry

- config.googleMaps_Width: The width of the map area. Default: 500.
- config.googleMaps_Height: The height of the map area. Default: 370.
- config.googleMaps_CenterLat: The latitude of the center. Default: 37.4419.
- config.googleMaps_CenterLon: The longitude of the center. Default: -122.1419.
- config.googleMaps_Zoom: The default zoom level. Default: 11.
- config.googleMaps_WrapperClass: The Google Maps automatically fills the width and height of the generated div, so if you want to add a little spacing and a border, you need to use a div around it. If this entry contains a non-empty value then such a div will be generated with this class. Default: ''.
  Important: in the preview inside the editor, the class might be applied to an image, not a div!
- config.googleMaps_MarkerText: Initial text for a marker. Default: lang.googlemaps.defaultMarkerText (changes with the translations)
- config.filebrowserKmlBrowseUrl : URL of the file browser for KML files. It defaults to filebrowserBrowseUrl. If it's an empty string the "Browse server" button won't be shown
- config.filebrowserIconBrowseUrl : URL of the file browser for icon files. It defaults to filebrowserImageBrowseUrl || filebrowserBrowseUrl. If it's an empty string the "Browse server" button won't be shown
- config.googleMaps_endScriptPath : URL of end script. It defaults to "scripts/cke_gmaps_end.js" at the plugin folder. If it's an empty string the script won't be inserted (you must do it elsewhere in the page or merge it together with the rest of your scripts).
- config.googleMaps_Icons : An object definining custom icons. For the moment only the image and shadow are used, an example:

      config.googleMaps_Icons = {
      	start: {
      		marker: {
      			image: 'http://martinezdelizarrondo.com/icons/start.png'
      		},
      		shadow: {
      			image: 'http://martinezdelizarrondo.com/icons/shadow.png'
      		}
      	}
      };

  In the future more options (like defining sizes, etc...) might be added. Or maybe not? is it enough to use this simple data?.
  Remember that if you want to show the custom icon in the static map the image must use a public URL (including the domain).
  If you want to find lots of useful and greatly designed icons, look at the Map Icons Collection project, the price is right (credits + optional donation) and you can get easily all your icons following the same theme instead of mixing different styles.
- config.googleMaps_shadowMarker : Default shadow image for icons added from the dialog. In the icons folder there's a shadow for the Map Icons Collection icons if you want to use a different set, remember to place the "anchor point" of the icon and the shadow at the bottom center. If this parameter is a function, it's called with the url of the selected image, otherwise it's treated as a string. Default: no shadow.
- config.googleMaps_newMarkerColor : Color for new icons. It can be also the name of a custom icon. This setting can be either a normal string, or a function that returns a string. If not set it rotates between the default colors.
- config.googleMaps_newOverlayColor : Color for new polylines and polygons. This setting can be either a normal string, or a function that returns a string, in this case a parameter with the type of overlay being created is passed. If not set it rotates between the default colors.
- config.googleMaps_overlayColors : Array with the default values for the overlay colors. Default ["#880000", "#008800", "#000088","#888800", "#880088", "#008888", "000000", "888888"]
- config.googleMaps_markerColors : Array with the list of default markers to use. Default ['green', 'purple', 'yellow', 'blue', 'orange', 'red'] . In this setting you can't add new colors, the only goal of this setting is to remove the default markers that you don't want or reorder the set. Use googleMaps_Icons to add new ones, and googleMaps_markerColor to control how new markers are created.
- config.googleMaps_toolbar : Toolbar configuration to use for the embedded editor in markers. Besides the normal buttons, you can use this special button to insert the Directions link "GMapsInsertDirections". Default: [["Bold", "Italic", "Link", "Image"], ["Undo", "Redo"], ["GMapsInsertDirections"]]
- config.googleMaps_ApiKey : This is a required entry. Follow these steps to get your key. (String).
- config.googleMaps_weatherUsaUnits : Switches the default temperature and speed units in the weather layer to use the USA system (Fahrenheit and Miles/hour) instead of metric. (boolean: true/false)

### 5. Use it

Now empty the cache of your browser and reload the editor, the new button should be ready to use.

Here's a video showing the basic features and another for the elements tab

### 6. Translations

To add a new translation open plugin.js and search for "translations", it's at line 1113 and add your language (the example is based on adding Polish ('pl')

`// translations lang : ['el', 'en', 'es'],` to`// translations lang : ['el', 'en', '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( 'googlemaps', 'pl',`

and finally, translate all the text between quotes :-)

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

### Other notes

The KML files aren't used in the static maps. And in order for them to work you should use them in a public server (localhost won't work with .kmz)
You might need to adjust the server to use the correct MIME types (application/vnd.google-earth.kml+xml for .kml and application/vnd.google-earth.kmz for .kmz).

As a summary of features that aren't available in the static preview:

- KML files
- Circles
- Text overlays
- Also, if there's too much data, the image won't be shown at all (too many lines, areas, icons... so that the URL to the image is too long)
- The maximum size for the image is 640x640, if you use a bigger one, it will be scaled

If you need some special feature for this plugin, or if you need any other kind of plugin for CKEditor then contact me and we can discuss it

## Disclaimers

CKEditor is © CKSource.com

Google, Google Maps and the Google Maps API are all properties of Google.