Discusses how to configure and implement custom CKEditor widgets in Drupal. Includes numerous examples of custom widgets and actual widgets that we use in CNN Travel site. Note that you could also download the PDF copy of this presentation by clicking the Save/Download button. The PDF copy has far better quality than the one rendered here online.

1. CKEditor Widgets with Drupal
Engr. Ranel O. Padon
Kite Systems | http://github.com/ranelpadon

2. About Me
• Software Engineer at Kite Systems (Hong Kong-based company)
– full-time Drupal developer for CNN Travel (our client)
• part-time Python lecturer in University of the Philippines
• involved in Java and Python projects before
• plays competitive futsal

3. Topics
• Why give importance on contents?
• Why use a WYSIWYG tool and CKEditor?
• Why use widgets?
• How to create widget from scratch?
– Grouped Texts widget
– HERE Maps widget
• CNN Travel in-house widgets
– Inline Ads
– Inline Maps
– Service Info widget
• My personal project: Leaflet Maps widget

4. Why Contents?
• one of the best ways to drive traffic to your site
is to create valuable and interesting contents
• to create high-quality contents the editors must
have effective and high-quality tools

5. Why WYSIWYG?
• WYSIWYG (WhatYou See Is WhatYou Get)
Editors could be used to create/edit contents
directly in your web site
• eliminates the need to use a word document
processor(MS Word, LibreOffice Writer)
• boosts editor’s productivity

6. Why WYSIWYG?
• Node view
(normal page view)

7. Why WYSIWYG?
• Node Edit link

8. CKEditor Toolbar
• Node Edit view
(CKEditor view)

9. Why CKEditor?
image captured from http://www.ckeditor.com

10. Why CKEditor?
image captured from http://www.ckeditor.com

11. Why CKEditor?
image captured from http://www.ckeditor.com

12. Why CKEditor?
image captured from http://www.ckeditor.com

13. Why CKEditor?
image captured from http://www.ckeditor.com

14. Why CKEditor?
• Has good support for common CMSes like
Drupal, WordPress, Django, etc.
• Default WYSIWYG Editor in Drupal 8!

15. Why CKEditor?
• Check-out xEditor 2.0 for in-place editing
of contents (Drupal module for live node
view editing):
https://www.drupal.org/project/xeditor

16. Why CKEditor?
• a redesigned version of FCKeditor
• created by Frederico Caldeira Knabben

17. Why Widgets?
• grouped CKEditor elements
• subclass of the Plugin class
• widget styling has a template
- could have a generic style for all widget
- could have specific style for specific via a
custom Dialog window
• widget is a drag-and-drop element, but as a group
• widgets could have multiple instances

18. Why Widgets?
• we use to inject spatial information in our
content using a customized Drupal’s Leaflet
module.
• we could display maps in Leaflet as a block
but it could be too limiting
• sometimes our editors write articles like
Top10 articles in Hong Kong and want to
insert the map alongside its content writeup

19. Widget 1: Grouped Texts

20. Widget 2: Code Snippets

21. Widget 3: Annotated Images

22. Widget 4: Math Formulas

23. CKEditor Widgets Live Demo
• Check-out the live demo of the four widgets:
http://ckeditor.com/demo#widgets

24. Custom Widget
• Structure/Required Files
– PLUGIN_NAME/plugin.js
– PLUGIN_NAMEs/css/contents.css
– PLUGIN_NAME/icons/PLUGIN_NAME.png

25. Custom Widget: Grouped texts
• Required Files
– grouped_texts/plugin.js
– grouped_texts/css/contents.css
– grouped_texts/icons/grouped_texts.png
ideas for this sample widget is obtained from the Simple Box widget from here:
https://github.com/ckeditor/ckeditor-docs/tree/master/guides/widget_sdk/tutorial_1

26. Custom Widget: Grouped texts

27. Custom Widget: Grouped texts

28. Custom Widget: Grouped texts
– grouped_texts/plugin.js

29. Custom Widget: Grouped texts

30. Custom Widget: Grouped texts

31. Custom Widget: Grouped texts

32. Custom Widget: Grouped texts
– grouped_texts/css/contents.css

33. Custom Widget: HERE Maps
Workhorse Widget Files
• Plugin Core: Defines the plugin and attaches the
plugin to the CKEditor toolbar.
• Dialog Script: Displays the map options when
creating and editing existing maps.
• Map Iframe Renderer: Parses the map options via
URL and renders the map accordingly.

34. Custom Widget: HERE Maps
• Widget Files
– here_maps/plugin.js
– here_maps/css/contents.css
– here_maps/icons/here_maps.png
– here_maps/dialogs/here_maps.js
– here_maps/scripts/here_maps_iframe.html

35. Custom Widget: HERE Maps
• Creating a new HERE Maps widget

36. Custom Widget: HERE Maps
• Inserting the new HERE Maps widget; loads the iframe element

37. Custom Widget: HERE Maps
• Editing the HERE Maps widget (by double-clicking the handle bars that
displays in upper-left corner of the widget when you hover the mouse)

38. Custom Widget: HERE Maps
– here_maps/plugin.js

39. Custom Widget: HERE Maps
– here_maps/plugin.js

40. Custom Widget: HERE Maps
– here_maps/dialog/here_maps.js

41. Custom Widget: HERE Maps
– here_maps/dialog/here_maps.js (setup method, for editing
existing widgets)

42. Custom Widget: HERE Maps
– here_maps/dialog/here_maps.js (setup and commit methods)

43. Custom Widget: HERE Maps
– here_maps/dialog/here_maps.js (commit method, acts as a Submit/
Save handler)

44. Custom Widget: HERE Maps
– here_maps/dialog/here_maps.js (commit method)

45. Custom Widget: HERE Maps
– here_maps/scripts/here_maps_iframe.html (executes when the commit
method is called)

46. Custom Widget: HERE Maps
– parse the URL
query parameters
and pass them as info
to build the map

47. Custom Widget: HERE Maps
– build the map
using the info
from iframe’s URL

48. Custom Widget: HERE Maps
– specify the HERE Maps credentials, could be passed as URL params
also or store them in Drupal.settings object

49. Custom Widget: HERE Maps
– instantiate a new map using the specified map options via URL
(Latitude and Longitude parameters)
– you could include via URL other map variables like zoom level, map
center, etc

50. Custom Widget: Drupal Hook
the custom widgets could be registered in Drupal using
hook_ckeditor_plugins:

51. Custom Widget: Drupal Hook

52. Custom Widget: Drupal Hook

53. Custom Widget: Drupal Hook
enable them in the activated CKEditor profile,
usually in admin/config/content/ckeditor/edit/Advanced

54. Custom Widget: Drupal Hook
they must be included in the Current Toolbar as well

55. Custom Widget: Drupal Hook
they will now appear in the CKEditor toolbar when adding/editing
articles/contents

56. CNN Travel Ads Widget
has similar mechanism to that of HERE Maps widget (uses iframe also)

57. CNN Travel Ads Widget
Dialog window’s options
for specifying ads

58. CNN Travel Map Widget
• maps could show one or more places
• maps could have various dimensions
• maps could have the specified alignment
• could show nearby TripAdvisor places
• popups should be styled similar to
TripAdvisor
• preserves the last zoom level state
– via mouse scroll zoom events

59. CNN Travel Map Widget
• Node Edit mode

60. CNN Travel Map Widget
• Node Edit mode
• shows the Dialog window’s Places tab options

61. CNN Travel Map Widget
• Node Edit mode
• shows the Options tab and the auto-
complete search functionality
• uses Twitter’s TypeAhead API and
fetches live data from TripAdvisor’s servers

62. CNN Travel Service Info
• CNN Travel Map widget plus other add-ons
• shows one Place only
• focuses on custom texts and TripAdvisor data
– user ratings/reviews
– booking info

63. CNN Travel Service Info
• Node Edit mode (Hong Kong’s Insider Guide article)
http://travel.cnn.com/destinations-insider-guide-hong-kong-954446
http://travel.cnn.com/destinations-insider-guide-hong-kong-954446

64. CNN Travel Service Info
• Node Edit mode

65. CNN Travel Service Info
http://travel.cnn.com/destinations-insider-guide-hong-kong-954446

66. CNN Travel Service Info
http://travel.cnn.com/destinations-insider-guide-hong-kong-954446
• the widget
showing the
TripAdvisor
reviews

67. CNN Travel Service Info
http://travel.cnn.com/destinations-insider-guide-hong-kong-954446
• the widget
showing the
HERE Maps
section

68. Challenges We Encountered
• iframes are notoriosly slow, for contents with
lot of map widgets, the page takes too long to
fully load
• we refactored our widget implementation
and converted the map iframes to ordinary
divs, and treated the main page as the main
iframe for all the widgets

69. Challenges We Encountered
• we further optimized the widget rendering by
rendering them only as needed or as the page
scrolls
• so if the widget is not currently visible in the
viewing area, the widget will be not rendered
yet

70. CKEditor leaflet Maps
Project Page: http://ckeditor.com/addon/leaflet

71. CKEditor leaflet Maps
Live Demo:
http://ranelpadon.github.io/ckeditor-leaflet/index.html

72. CKEditor leaflet Maps
Live Demo (Dialog window):
http://ranelpadon.github.io/ckeditor-leaflet/index.html

73. CKEditor leaflet Maps
Utilizes these libraries:
• CKEditor's Widget API
• Google's Places Library/Type-Ahead Search
• Google's Geocoding API
• Leaflet JS,
• Leaflet - Tile Providers
• Leaflet - MiniMap

74. CKEditor leaflet Maps
• has good code base (with ample inline code
comments) when you want to develop
custom widgets
• includes installation guide that could be useful
in installing CKEditor and/or plugins/widgets
in Drupal:
https://github.com/ranelpadon/ckeditor-leaflet/blob/
master/Installation%20Guide.txt

75. Recommendation
• take time to read the much improved and
comprehensive documentation (includes
useful links to related resources) and
familiarize yourself to the valuable APIs:
– http://sdk.ckeditor.com

76. Recommendation | CKEditor sdk

77. Special Thanks
• CNN Travel (http://travel.cnn.com) for
allowing me to share what we are working on.
• HERE (http://here.com) for sponsoring my talk.

78. What did you think about the presentation ?
Leave your feedback and
help us improve Drupalcamp on :
http://2014.drupalcebu.org/