Installation Guide.txt 9.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203
  1. I. OVERVIEW
  2. This Leaflet Maps plugin requires CKEditor 4.3 or later versions, and it leverages the power and flexibility
  3. of Widget API. Hence, the 'widget' plugin is also a hard dependency (which also depends on Line Utilities
  4. and Clipboard plugins). The Clipboard plugin is already loaded by default in all presets/pre-built packages of CKEditor
  5. (Basic, Standard, and Full). Hence, we only need to download the Widget plugin (http://ckeditor.com/addon/widget),
  6. the Line Utilities plugin (http://ckeditor.com/addon/lineutils), and this Leaflet Maps plugin (http://ckeditor.com/addon/leaflet).
  7. For Linux users, after downloading, make sure that the zipped folders or the target CKEditor folders
  8. have right read/write/execute permissions, otherwise you might encounter loading issues
  9. like the "File x could not be found" notice. You might need to run "sudo chmod 777 -R leaflet",
  10. "sudo chmod 777 -R lineutils", and "sudo chmod 777 -R widget" before or after copying them
  11. in the appropriate CKEditor folders.
  12. II. STANDARD INSTALLATION (Usual Setup)
  13. 1) After unzipping the folder, paste the three folders ("lineutils", "leaflet", and "widget")
  14. to "ckeditor/plugins" folder. After that, you should have the following folder structures:
  15. "ckeditor/plugins/leaflet"
  16. "ckeditor/plugins/lineutils"
  17. "ckeditor/plugins/widget"
  18. 2) Edit the "ckeditor/config.js" file, and add the following:
  19. if there's no existing line yet:
  20. config.extraPlugins = "lineutils,widget,leaflet";
  21. otherwise, append it to the existing list, no extra spaces are allowed:
  22. config.extraPlugins = "existing_plugin,another_existing_plugin,lineutils,widget,leaflet";
  23. 3.) Just to make sure, clear the web browser's cache after modifying your configuration.
  24. Clearing the browser's cache is also very important
  25. since the CKEditor's JS and CSS assets/components are cached also in the browser.
  26. III. DRUPAL INSTALLATION
  27. In Drupal, the typical way to embed the CKEditor WSYIWYG is
  28. through the CKEditor module (https://drupal.org/project/ckeditor),
  29. and then loading the corresponding CKEditor JS library (http://ckeditor.com/).
  30. Drupal's CKEditor module (tested on version ) is typically installed to have this internal path:
  31. sites/all/modules/ckeditor or sites/all/modules/contrib/ckeditor.
  32. Note that this guide is tested on CKEditor "7.x-1.13", latest version is "7.x-1.14".
  33. I'll test this guide also in the latest version later.
  34. Moreover, the CKeditor JS Library is typically installed to have this internal path:
  35. "sites/all/modules/ckeditor/ckeditor/ckeditor.js" or
  36. "sites/all/modules/contrib/ckeditor/ckeditor/ckeditor.js" or
  37. "sites/all/libraries/ckeditor/ckeditor.js."
  38. However, installing additional plugins in CKEditor in Drupal is not that straightforward
  39. as we could see from the issue queues:
  40. https://drupal.org/node/2215409#comment-8568207
  41. https://drupal.org/node/1930130#comment-7297628
  42. https://drupal.org/node/1324554
  43. https://drupal.org/node/2215497
  44. Nevertheless, after experimenting with the various ways to enable the additional plugins
  45. (Line Utilities, Widget, and Leaflet), this is the simplest solution
  46. (the idea is to copy the plugin folders, enable them, and make them visible in the toolbar):
  47. A. DRUPAL INSTALLATION OPTION 1
  48. 1.) Download and unzip the plugins here (depending on your setup):
  49. "sites/all/modules/ckeditor/plugins" or
  50. "sites/all/modules/contrib/ckeditor/plugins".
  51. After that, you should have the following folder structures:
  52. "ckeditor/plugins/leaflet"
  53. "ckeditor/plugins/lineutils"
  54. "ckeditor/plugins/widget"
  55. 2.) We should now activate the new plugins and add them to the toolbar.
  56. This is done by configuring the CKEditor Profile Settings,
  57. in which by default is located in:
  58. "admin/config/content/ckeditor/edit/Advanced"
  59. A. Activate the Plugins
  60. In EDITOR APPEARANCE >>> Plugins section:
  61. Enable the corresponding checkboxes for the Leaflet Maps, Line Utilities,
  62. and Widget plugins. These are the texts displayed adjacent to their checkboxes:
  63. "Plugin file: leaflet"
  64. "Plugin file: lineutils"
  65. "Plugin file: widget"
  66. B. Add them to the Toolbar
  67. We should then make the activated plugins visible in the toolbar,
  68. skipping this step will make the Leaflet Maps plugin inaccessible in the toolbar.
  69. In EDITOR APPEARANCE >>> Toolbar section:
  70. Drag the Leaflet Maps icon (black-colored) from the 'All Buttons' section
  71. to the 'Used Buttons' section.
  72. We need to configure the Leaflet Maps icon only since the Line Utilities and Widget plugins
  73. have no toolbar icons and they will just load in the background.
  74. 3.) Then, click the Save button. Clear the Drupal's overall cache AND
  75. clear the browser's cache. Clearing the browser's cache is also
  76. very important since the CKEditor's JS and CSS assets/components
  77. are cached also in the browser.
  78. As indicated above, using the "sites/all/modules/ckeditor/plugins" or
  79. "sites/all/modules/contrib/ckeditor/plugins"
  80. will work with no additional custom hooks programming since by default
  81. CKEditor utilize that folder in the CKEditor Global Profile Settings:
  82. "admin/config/content/ckeditor/editg".
  83. If you go that Global Profile Settings page, this will be indicated
  84. (unless you override the default configuration):
  85. Path to the CKEditor plugins directory: "%m/plugins"
  86. In which "%m" refers to the base URL path where the CKEditor module is stored,
  87. and defaults to "sites/all/modules/ckeditor" or "sites/all/modules/contrib/ckeditor".
  88. B. DRUPAL INSTALLATION OPTION 2
  89. With the advent of Libraries API (https://drupal.org/project/libraries),
  90. Drupal offers more flexibility in the handling of external/third-party libraries,
  91. which means a clean mechanism that provides a separation of control between
  92. the CKEditor module and CKEditor library, and implies that we could
  93. safely upgrade the library and module independent to each other.
  94. Having a Libraries folder (sites/all/libraries) is also a very common setup in Drupal.
  95. This setup assumes that you've already installed and enabled the Libraries API module
  96. and configured the CKEditor library (sites/all/libraries/ckeditor).
  97. Make sure also that the "Path to CKEditor" settings indicated in
  98. the CKEditor's Global Profile (admin/config/content/ckeditor/editg) is
  99. indicated as "%l/ckeditor", in which "%l" refers to the "sites/all/libraries".
  100. 1.) Download and unzip the plugins here:
  101. "sites/all/libraries/ckeditor/plugins"
  102. After that, you should have the following folder structures:
  103. "ckeditor/plugins/leaflet"
  104. "ckeditor/plugins/lineutils"
  105. "ckeditor/plugins/widget"
  106. 2.) We should now activate the new plugins and add them to the toolbar.
  107. This is done by implementing first the hook_ckeditor_plugin() in a custom module:
  108. function MYMODULE_ckeditor_plugin() {
  109. return array(
  110. 'leaflet' => array(
  111. 'name' => 'Leaflet Maps',
  112. 'desc' => t('Plugin for inserting Leaflet Maps.'),
  113. 'path' => libraries_get_path('ckeditor') . '/plugins/leaflet/',
  114. 'buttons' => array(
  115. 'leaflet' => array(
  116. 'label' => 'Leaflet Maps',
  117. 'icon' => 'icons/leaflet.png',
  118. ),
  119. ),
  120. ),
  121. );
  122. }
  123. For convenience, I've created a Drupal utility module specifically for this purpose,
  124. check-out the module and instructions here:
  125. https://github.com/ranelpadon/drupal-leaflet-maps/tree/master
  126. Fortunately, we need only to register the Leaflet Maps plugin,
  127. the Line Utilities and Widget plugins are automatically registered.
  128. The Leaflet Maps Drupal module above is enough for our purpose.
  129. Now, we configure the CKEditor Profile Settings,
  130. in which by default is located in:
  131. "admin/config/content/ckeditor/edit/Advanced"
  132. A. Activate the Plugin
  133. In EDITOR APPEARANCE >>> Plugins section:
  134. Enable the corresponding checkbox for the Leaflet Maps plugin.
  135. This is the description displayed adjacent to its checkbox:
  136. "Plugin for inserting Leaflet Maps."
  137. B. Add them to the Toolbar
  138. We should then make the activated plugin visible in the toolbar,
  139. skipping this step will make the Leaflet Maps plugin inaccessible in the toolbar.
  140. In EDITOR APPEARANCE >>> Toolbar section:
  141. Drag the Leaflet Maps icon (black-colored) from the 'All Buttons' section
  142. to the 'Used Buttons' section.
  143. We need to configure the Leaflet Maps icon only since
  144. the Line Utilities and Widget plugins have no toolbar icons and
  145. they will just load in the background.
  146. 3.) Then, click the Save button. Clear the Drupal's overall cache AND
  147. clear the browser's cache. Clearing the browser's cache is also
  148. very important since the CKEditor's JS and CSS assets/components
  149. are cached also in the browser.
  150. Note that if you configure the Leaflet Maps, Line Utilities, and Widget plugins
  151. using the handy CKEditor auto-builder (http://ckeditor.com/builder) and
  152. bundled it with the core "ckeditor.js" file, it will not work in Drupal,
  153. since as far as I know, the Drupal's CKEditor module
  154. (or specifically the hook_ckeditor_plugin()) has no support for it yet.
  155. But, outside of Drupal, the Leaflet Maps will work even when
  156. pre-configured/auto-bundled using the CKEditor builder.