Installation Guide.txt

I. OVERVIEW

This Leaflet Maps plugin requires CKEditor 4.3 or later versions, and it leverages the power and flexibility
of Widget API. Hence, the 'widget' plugin is also a hard dependency (which also depends on Line Utilities
and Clipboard plugins). The Clipboard plugin is already loaded by default in all presets/pre-built packages of CKEditor
(Basic, Standard, and Full). Hence, we only need to download the Widget plugin (http://ckeditor.com/addon/widget),
the Line Utilities plugin (http://ckeditor.com/addon/lineutils), and this Leaflet Maps plugin (http://ckeditor.com/addon/leaflet).

For Linux users, after downloading, make sure that the zipped folders or the target CKEditor folders
    have right read/write/execute permissions, otherwise you might encounter loading issues
    like the "File x could not be found" notice. You might need to run "sudo chmod 777 -R leaflet",
    "sudo chmod 777 -R lineutils", and "sudo chmod 777 -R widget" before or after copying them
    in the appropriate CKEditor folders.

GOOGLE POLICY CHANGES:
Leaflet Maps plugin uses the "Autocomplete" and "GeoCoding" components of "Google Places API".
However as of June 22, 2016, Google will now require access key, especially for new website domains.
See the Goggle's official announcement:
    http://googlegeodevelopers.blogspot.com.au/2016/06/building-for-scale-updates-to-google.html

Create your own Google Maps JS API key w/ this guide:
    https://developers.google.com/maps/documentation/javascript/get-api-key

Make sure to ENABLE the "Google Maps JavaScript API" in your "Google API Console" account/dashboard to activate your key.
Note that the plugin uses my personal key by default, so Google API's standard usage quota will apply,
especially if many users will simultaneously use my plugin.
Hence, it's strongly recommended that the user create his own Google API key asap (see link above),
and set his personal key via CKEditor's config file (config.js) in this manner:
    config.leaflet_maps_google_api_key = '<YOUR GOOGLE API KEY HERE>';

See further instructions on it below.

DEMO PAGE:
Moreover, the plugin now bundles a stand-alone demo page (demo/index.html)
which showcases the various map tiles, map options, and languages/translations.
Translations could be switched dynamically in the demo page using the language switcher's select list.
The Leaflet Maps plugin folder is all you need to render the bundled demo page since all its dependencies
(including widget's dependencies and languages) will be pulled from the CDN-hosted files.
Note that you need to put the plugin folder in a web server context (e.g. localhost or virtual host setup)
to render the demo page properly; opening the demo/index.html file directly in a browser as a regular file will not work.


II. STANDARD INSTALLATION (Usual Setup)

1) After unzipping the folder, paste the three folders ("lineutils", "leaflet", and "widget")
    to "ckeditor/plugins" folder. After that, you should have the following folder structures:
        "ckeditor/plugins/leaflet"
        "ckeditor/plugins/lineutils"
        "ckeditor/plugins/widget"

2) Edit the "ckeditor/config.js" file, and add the following:
    if there's no existing line yet:
        config.extraPlugins = "lineutils,widget,leaflet";
        config.leaflet_maps_google_api_key = 'AIzaSyA9ySM6msnGm0qQB1L1cLTMBdKEUKPySmQ';

    otherwise, append it to the existing list, no extra spaces are allowed:
        config.extraPlugins = "existing_plugin,another_existing_plugin,lineutils,widget,leaflet";
        config.leaflet_maps_google_api_key = 'AIzaSyA9ySM6msnGm0qQB1L1cLTMBdKEUKPySmQ';

3.) Just to make sure, clear the web browser's cache after modifying your configuration.
    Clearing the browser's cache is also very important
    since the CKEditor's JS and CSS assets/components are cached also in the browser.


III. DRUPAL INSTALLATION

In Drupal, the typical way to embed the CKEditor WSYIWYG is
through the CKEditor module (https://drupal.org/project/ckeditor),
and then loading the corresponding CKEditor JS library (http://ckeditor.com/).

Drupal's CKEditor module is typically installed to have this internal path:
    sites/all/modules/ckeditor or sites/all/modules/contrib/ckeditor.

Moreover, the CKeditor JS Library is typically installed to have this internal path:
    "sites/all/modules/ckeditor/ckeditor/ckeditor.js" or
    "sites/all/modules/contrib/ckeditor/ckeditor/ckeditor.js" or
    "sites/all/libraries/ckeditor/ckeditor.js."

With Drupal's latest CKEditor (https://www.drupal.org/project/ckeditor, 7.x-1.16),
the Widget and Lineutils plugins are already bundled and enabled by default which is indicated
as the "Full" CKEditor.js build in you check in the the CKEditor Global Profile admin page
    "admin/config/content/ckeditor/editg"
        Path to CKEditor: //cdn.ckeditor.com/4.4.3/full-all

so the Widget and Lineutils plugins should not be downloaded anymore; actually, it will cause conflicts and console error like this if you do:
    Uncaught TypeError: CKEDITOR.tools.getIndex is not a function

Hence, it is highly recommended that you use the latest Drupal CKEditor module
since it would be the easiest to setup, especially in the context of Leaflet Maps plugin.

These are the possible plugin setups, the idea is to copy the plugin folder, enable it,
and make it visible in the toolbar:


A. DRUPAL INSTALLATION OPTION 1 (EASIER SETUP)

    1.) Download and unzip the plugin here (depending on your setup):
            "sites/all/modules/ckeditor/plugins" or
            "sites/all/modules/contrib/ckeditor/plugins".

        After that, you should have this folder structure:
            "ckeditor/plugins/leaflet"

    2.) We should now activate the new plugin and add them to the toolbar.
        This is done by configuring the CKEditor Profile Settings,
        in which by default is located in:
            "admin/config/content/ckeditor/edit/Advanced"

        A. Activate the Plugin
            In EDITOR APPEARANCE >>> Plugins section:
            Enable the corresponding checkboxes for the Leaflet Map.
            This is the text displayed adjacent to its checkbox:
                "Plugin file: leaflet"

        B. Add them to the Toolbar
            We should then make the activated plugin visible in the toolbar,
            skipping this step will make the Leaflet Maps plugin inaccessible in the toolbar.

            In EDITOR APPEARANCE >>> Toolbar section:
            Drag the Leaflet Maps icon (black-colored) from the 'All Buttons' section
            to the 'Used Buttons' section.

        C. Specify the Google API key (used mainly for autocomplete/geocoding functionalities):
            As indicated in the OVERVIEW section above, Google API key is now required.
            In ADVANCED OPTIONS >>> Custom JavaScript Configuration:
            Set your personal Google API key (I've provided my personal key as sample):
                config.leaflet_maps_google_api_key = 'AIzaSyA9ySM6msnGm0qQB1L1cLTMBdKEUKPySmQ';

    3.) Then, click the Save button. Clear the Drupal's overall cache AND
        clear the browser's cache. Clearing the browser's cache is also
        very important since the CKEditor's JS and CSS assets/components
        are cached also in the browser.

    As indicated above, using the "sites/all/modules/ckeditor/plugins" or
    "sites/all/modules/contrib/ckeditor/plugins"
    will work with no additional custom hooks programming since by default
    CKEditor utilize that folder in the CKEditor Global Profile Settings:
    "admin/config/content/ckeditor/editg".

    If you go that Global Profile Settings page, this will be indicated
    (unless you override the default configuration):
        Path to the CKEditor plugins directory: "%m/plugins"

        In which "%m" refers to the base URL path where the CKEditor module is stored,
        and defaults to "sites/all/modules/ckeditor" or "sites/all/modules/contrib/ckeditor".


B. DRUPAL INSTALLATION OPTION 2

    With the advent of Libraries API (https://drupal.org/project/libraries),
    Drupal offers more flexibility in the handling of external/third-party libraries,
    which means a clean mechanism that provides a separation of control between
    the CKEditor module and CKEditor library, and implies that we could
    safely upgrade the library and module independent to each other.
    Having a Libraries folder (sites/all/libraries) is also a very common setup in Drupal.

    This setup assumes that you've already installed and enabled the Libraries API module
    and configured the CKEditor library (sites/all/libraries/ckeditor).
    Make sure also that the "Path to CKEditor" settings indicated in
    the CKEditor's Global Profile (admin/config/content/ckeditor/editg) is
    indicated as "%l/ckeditor", in which "%l" refers to the "sites/all/libraries".

    1.) Download and unzip the plugin here:
            "sites/all/libraries/ckeditor/plugins"

        After that, you should have this folder structure:
            "ckeditor/plugins/leaflet"

    2.) We should now activate the new plugin and add them to the toolbar.
        This is done by implementing first the hook_ckeditor_plugin() in a custom module:

        function MYMODULE_ckeditor_plugin() {
          return array(
            'leaflet_maps' => array(
              'name' => 'leaflet',
              'desc' => t('Plugin for inserting Leaflet Maps.'),
              'path' => libraries_get_path('ckeditor') . '/plugins/leaflet/',
              'buttons' => array(
                'leaflet' => array(
                  'label' => 'Leaflet Maps',
                  'icon' => 'icons/leaflet.png',
                ),
              ),
            ),
          );
        }

        For convenience, I've created a Drupal utility module specifically for this purpose,
        check-out the module and instructions here:
        https://github.com/ranelpadon/drupal-leaflet-maps/tree/master

        Now, we configure the CKEditor Profile Settings,
        in which by default is located in:
            "admin/config/content/ckeditor/edit/Advanced"

        A. Activate the Plugin
            In EDITOR APPEARANCE >>> Plugins section:
            Enable the corresponding checkbox for the Leaflet Maps plugin.
            This is the description displayed adjacent to its checkbox:
                "Plugin for inserting Leaflet Maps."

        B. Add them to the Toolbar
            We should then make the activated plugin visible in the toolbar,
            skipping this step will make the Leaflet Maps plugin inaccessible in the toolbar.

            In EDITOR APPEARANCE >>> Toolbar section:
            Drag the Leaflet Maps icon (black-colored) from the 'All Buttons' section
            to the 'Used Buttons' section.

        C. Specify the Google API key (used mainly for autocomplete/geocoding functionalities):
            As indicated in the OVERVIEW section above, Google API key is now required.
            In ADVANCED OPTIONS >>> Custom JavaScript Configuration:
            Set your personal Google API key (I've provided my personal key as sample):
                config.leaflet_maps_google_api_key = 'AIzaSyA9ySM6msnGm0qQB1L1cLTMBdKEUKPySmQ';

    3.) Then, click the Save button. Clear the Drupal's overall cache AND
        clear the browser's cache. Clearing the browser's cache is also
        very important since the CKEditor's JS and CSS assets/components
        are cached also in the browser.

Note that if you configure the Leaflet Maps, Line Utilities, and Widget plugins
using the handy CKEditor auto-builder (http://ckeditor.com/builder) and
bundled it with the core "ckeditor.js" file, it will not work in Drupal,
since as far as I know, the Drupal's CKEditor module
(or specifically the hook_ckeditor_plugin()) has no support for auto-build versions.

But, outside of Drupal, the Leaflet Maps will work even when
pre-configured/auto-bundled using the CKEditor builder.


IV. CAVEATS AND SURPRISES: STYLING AND MARKUP FILTERING ISSUES

For some systems like Drupal, IFRAME tag is blacklisted mainly for security purposes
when filtering contents. Currently, CKEditor Leaflet Maps uses IFRAME for rendering maps,
hence you must allow IFRAME tag in order for it to work as intended. In Drupal,
you should add the IFRAME tag as one of the whitelisted tags in the
'Allowed HTML tags' section in 'Limit allowed HTML tags' filter/tab in
"admin/config/content/formats/filtered_html" page.

Furthermore, this widget utilizes CSS classes to have a more maintainable styling
instead of bombarding the widget with inline styles resulting to a cluttered markup.
In Drupal, when you save the page after editing it with CKEditor, inline styles will be
discarded by Drupal by default, again for security purposes. Thus, for cases like this,
you need to load the contents of the widget's CSS file 'leaflet/css/contents.css'
to pages that will render the Leaflet Maps. This is very important if you want to make
the position/alignment or responsive behavior work as intended. You could add the style file
to your site's theme or global/core CSS file. In Drupal, you could easily add the styles
by using the CSS Injector module (https://www.drupal.org/project/css_injector)
or by using the usual drupal_add_css() construct in your custom module.