An Introduction To The CKEditor And Text Formats In Backdrop CMS
My team runs a service for the University of Colorado that allows departments and faculty to create websites telling students how awesome it is to go to CU and live in Boulder, CO. The service now powers around 1000 sites and has become a critical piece of what our department offers to the university.
The service was built using Drupal 7 (D7), but in evaluating the upgrade path to Drupal 8 (D8), we got cold feet trying to find parity in D8 modules matching to D7 modules. Coupled with the change in system resources needed to run those 1000 sites in D8, we started looking at alternatives that might be better suited for our service than D8.
The only best option we saw was migrating to the Backdrop CMS. Backdrop is a fork of D7 and has a lot of parity still left with D7. I’m not going to go into any more details of the history of D8 and Backdrop, but I will go into the details of the feature parity to D7 in regards to WYSIWYG editors, text formats, and text filters.
A D7 Module To Begin With
For our developer blog (and for other personal blogs I’ve had in the past) code syntax highlighting is an important feature to have so that other developers can better grok what you are trying to do and/or convince them to do.
If you don’t have any syntax tools, you are more likely to not share your code in the first place. Or, if you have to use onerous third-party services to embed your code (cough…Medium…cough), you end up writing a blog post more slowly and maybe never even finishing it.
For these reasons, I created a module that added code highlighting functionality to our WYSIWYG editor in D7. https://github.com/CuBoulder/code_syntax_highlighting_bundle
It uses the D7 WYSIWYG module to add an icon to the toolbar that inserts a shortcode via the Shortcode module. You can edit the shortcode snippet after it is inserted, but without the WYSIWYG plugin, developers would have to insert<pre>code class="hljs blah blah"> before they attempted to copy their code in…and tabs/spaces weren’t preserved either, which made adding those back in the WYSIWYG editor a real PITA.
The end result is some code that looks like what you would see in an IDE. I’m pretty used to seeing blog posts with formatting like this so it is a requirement for me to write blog posts…except on Medium, I guess, where they still don’t have syntax highlighting to my knowledge. At least it’s free hosting 🤷♂
…but sadly, I will be using Gists for my code examples in this blog series. I actually wrote a post about how easy it is to create Gists from PHPStorm that you should check out if you write Medium articles with code samples in them. It is an IntelliJ level feature so you can use it for many more languages than just PHP.
Basic Porting Guidance
I’m not going to go into any of the general parts of porting a D7 module to Backdrop, but the community has provided a couple of great resources for you to get started.
“Converting modules to Backdrop from Drupal 7” is a guide that has some of the common info file changes, function renaming, configuration management, and other small changes included in it.
The “Coder Upgrade” module allows for an easier starting point as it covers most of the changes mentioned in the linked guide above. It utilizes the Grammar Parser library to modify source code in a precise and programmatic fashion. Sounds fancy 🎩!
Drupal 7 WYSIWYG Solutions
One of the bizarro things about Drupal until the D8 release was the omission of a WYSIWYG editor when you create a new, stock Drupal site. Users only have the choice of using a restrictive “filtered HTML” format, an un-restrictive “full HTML” format, and finally just simply a “plain text” format.
So, the solution for a WYSIWYG editor had to live in the contrib layer, which meant that there were multiple ways you could add WYSIWYG support to your site. CKEditor and TinyMCE were pretty popular in the D7 world, but an abstraction layer introduced in the WYSIWYG module became a more popular way to switch editors so you could introduce a number of different solutions and users could choose from them by simply selecting a format from the content entry box.
You could also select the filters, order of filters, and buttons included in the toolbar via the WYSIWYG module’s settings UI. The Express service uses CKEditor + WYSIWYG module so that is the perspective I’m coming from as I port the code syntax highlighting bundle to Backdrop.
CKEditor In Backdrop Core
Luckily for us, the CKEditor was chosen for integration into Backdrop’s core. D8 also decided to integrate CKEditor so if you chose that instead of TinyMCE I would think your migration to either Backdrop or D8 will be easier. It might even be worth the time to invest in moving your WYSIWYG to CKEditor as you prepare to migrate off of D7.
From a quick glance, the editor looks very similar to what we have now in D7. You have the toolbar, the content area, and the text format switcher.
One nice addition that was missing in D7 is the list of the filter tips next to the formatting options. You can certainly go to “filter/tips” on a D7 site and see the same filter tips text, but most end-users don’t even know that page exists or a way to quickly find it…hmm, providing a link to that page underneath the text format selector might be a good addition to D7 even in its old age.
A lot of the UI looked to be the same, but I started seeing big differences when I went to the configuration pages. In D7, the specific editor you used was completely missing from the text format options. So, that is where the WYSIWYG module came into play and helped map an editor to a text format.
So in our version of D7, you first had associate a text format to an editor in the WYSIWYG settings, and then you could hop over to the text format settings to add and rearrange filters on that format. The buttons in the CKEditor still had to be managed from the WYSIWYG settings, however, so managing the configuration for your WYSIWYG solution seemed cumbersome to me. I kept forgetting where each part was and ended up always clicking through to both WYSIWYG and text format settings page in order to make sure I didn’t miss anything.
Backdrop combines the editor and text format settings into one page. Rather than changing settings in two places, you only have to remember one area of the settings to go to. I like the UX of this a lot better than what we have currently in D7. Backdrop win!
Adding My Filter
Even though I’m adding a button to the CKEditor, I need to use the Shortcode module in tandem with the CKEditor functionality in order to render the inserted code with syntax highlighting. The Shortcode module is still being ported to Backdrop, but the code I am using lives here currently.
I’m choosing to implement the plugin in the “filtered HTML” text format out of the three formats Backdrop provides on install, since the shortcodes get filtered and aren’t just HTML or plain text. After I enabled the Shortcode module, I can see a couple filters to choose from in the text formats UI on “admin/config/content/formats/filtered_html”.
I’m not really sure what the “Shortcodes — html corrector” filter does, but I will select it for now and remove it if I run into any trouble. I also enabled the “Shortcode Basic Tags” module just to see that the Shortcode-side of things was working as expected.
Once again, those filter tips included in the formatting options are super helpful. And when I saved the node…
Yep, Shortcodes work. Hooray! An introduction to Backdrop’s text formats and editors is enough for this blog post. In the second part of this series, we will go over adding the “code” button to the CKEditor toolbar, inserting code through a modal when you click the code button, and rendering the inserted code sample via the Shortcode module.
