Customizing the CKEditor in Craft CMS

When I cre­ate a new rich text field in Craft CMS, I use the first-par­­ty CKEd­i­tor plu­g­in. My nest task is to con­fig­ure the field with some stan­dard updates which is what we’ll cov­er in this post. 

Before div­ing in to my cus­tomiza­tions, check out the plugin’s offi­cial doc­u­men­ta­tion to under­stand the basic usage of the field type and learn about one of its super­pow­ers, nest­ed entries, which I won’t cov­er here. You’re not going to miss Redac­tor. 🍻

The to-do list #

I have a rou­tine set of tasks each time I use CKEd­i­tor. 

1. Cus­tomize the font fam­i­ly selec­tion
2. Occa­sion­al­ly, I adjust the text-align­­ment options
3. Cus­tomize the font-size options 
4. Allow an author to spec­i­fy if a link should open in a new win­dow
5. Allow the user to paste in a YouTube URL to cre­ate a video embed

Cus­tomize the CKEd­i­tor Con­fig #

In the Craft con­trol pan­el, you can cre­ate con­figs that will cus­tomize what the con­tent author sees in their rich text edit­ing win­dow. Your CKEd­i­tor can have mul­ti­ple con­figs. You’ll find them in the con­trol pan­el in Set­tings -> Plu­g­ins -> CKEd­i­tor. 

Here’s a Gist of starter con­fig­u­ra­tion if you sim­ply want to copy and paste in the Con­fig Options sec­tion of one of your con­fig def­i­n­i­tions.

https://​gist​.github​.com/​j​o​h​n​f​m​o​r​t​o​n​/​4​2​7​2​c​c​5​a​8​c​3​2​2​8​8​1​6​e​f​d​e​3​3​7​c​f​5​4e06a

Let’s look at some spe­cif­ic things in that file.

font­Fam­i­ly #

You can eas­i­ly con­fig­ure the fontFamily with the font stacks used on your site. I think the only thing to point out here is that font names that include a space in the name should be wrapped in sin­gle quotes inside the dou­bled quot­ed font cas­cade, like EB Gara­mond, in my exam­ple.

"'EB Garamond', Georgia, serif"

Adding this con­fig­u­ra­tion doesn’t auto­mat­i­cal­ly add the option to the tool­bar for your con­tent authors. Drag and drop the font fam­i­ly pick­er so that it’s avail­able in the tool­bar.

Customized toolbar options, shown with arrows: alignment, font-family, font-size, link, embed

text-align­ment options #

You’ll see in my sam­ple con­fig that I’ve includ­ed all options, left, center, right. Those options are there so I can sim­ply remove one if I choose. If you don’t need to cus­tomize align­ment, you can leave this con­fig block out entire­ly. Add the text-align­­ment but­ton to the tool­bar if you want to give users this option.

font­Sizes #

The fontSizes in CKEd­i­tor include five built-in options for font sizes: 

1. tiny
2. small
3. default — This option is not tech­ni­cal­ly a ​“size,” but a way to remove any size class.
4. big
5. huge

Using them is pret­ty sim­ple, the con­tent author can high­light some text in the rich text edi­tor and select one of the sizes which will add a span with a size class to it. For exam­ple, the small option will add a span with a class of text-small, like this.

<span class="text-small">This text will be small.</span>

In your con­fig you can remove an option by sim­ply leav­ing it out. But if you want to add an addi­tion­al option, the exam­ple con­fig will come in handy. Take a look at the addi­tion of a Bigger option. I’ve placed it between two of the default names, big and huge so that it will appear in the order I want it to appear in.

"fontSize": {
    "options": [
      "tiny",
      "small",
      "default",
      "big",
      {
        "model": "bigger",
        "title": "Bigger",
        "view": {
          "classes": [
            "text-bigger"
          ],
          "name": "span"
        }
      },
      "huge"
    ]
  },

Add the font-size pick­er option to the tool­bar so that its avail­able for con­tent authors. 

In addi­tion, you’ll need to define a style in the ​“Cus­tom Styles” sec­tion in your con­fig­u­ra­tion screen since Craft won’t know style your cus­tom style. Notice the .ck.ck-content class name. This will lim­it the rules so that they only apply to the CKEd­i­tor and don’t inad­ver­tent­ly style oth­er ele­ments of the con­trol pan­el.

.ck.ck-content .bigger {
  font-size: 1.5rem;
}

With those set­tings in place, your author can now choose ​“Big­ger” as an option which will gen­er­ate the new size class.

<span class="text-bigger">This text will be bigger.</span>

Last­ly, be sure to include the styling options in your CSS for the front-end for the styles you’re pro­vid­ing for your users.

Open links in a new tab #

If you’re com­ing to CKEd­i­tor from Redac­tor, you might miss the option that allows links to opened in a new win­dow. It’s not includ­ed in the CKEd­i­tor defaults, but you can eas­i­ly add it with the link con­fig­u­ra­tion in the same file. 

Example of the UX of the CKEditor opening links in a new tab.

Adding video #

When you added the but­tons for the tool­bar for font-fam­i­­ly, align­ment, font-size, etc., you might have also added the embed con­tent but­ton. If you want to allow video embeds, you did the right thing, but you’re not done yet. 

The HTML Puri­fi­er con­fig #

If you’ve nev­er updat­ed the HTML Puri­fi­er in Craft, the out of the box con­fig­u­ra­tion will like­ly strip out the video an author has insert­ed into the CKEd­i­tor inter­face when the entry was saved. 

This is the HTML Puri­fi­er doing its work. It may appear tempt­ing to sim­ply dis­able HTML Purifi­ca­tion entire­ly. Don’t do this. ☠️☠️☠️ Your future self will thank you. HTML Purifi­ca­tion is there for secu­ri­ty rea­sons. 

To keep those video embeds, check out this sam­ple htmlpurifier-config.json.

Use that as a starter con­fig for your own HTML Puri­fi­er. It’s writ­ten to allow YouTube embeds to not be stripped out dur­ing the purifi­ca­tion process. Note that I also have a Vimeo URL in my exam­ple. I won’t show the code for Vimeo in the next sec­tion, but you’ll see how to do that based on the YouTube exam­ple.

Con­vert­ing the embed tag to a video tag #

If you allow embed­ded media with the CKEd­i­tor, you’ll need to take the embed tag and con­vert it to ren­der the con­tent you want to dis­play. The CKEd­i­tor doc­u­men­ta­tion has a sec­tion on how to unfurl near­ly any media type by includ­ing the third-par­­ty embed.js library in your site. This library requires an API key and has a pay-as-you go plan.

This libray is overkill, IMO. Why? You need to know the con­tent that you expect so that you can prop­er­ly write your HTML Puri­fi­er. And, since you know what to expect, you can eas­i­ly write the Javascript to han­dle the embeds you will have. For my pur­pos­es, I’m expect­ing YouTube videos. That’s all. I don’t need a library that will unfurl every pos­si­ble embed type. Plus, if you write the unfurl­ing code your­self, you have more con­trol of the final out­put.

Here’s a Gist for embed­ding YouTube videos: https://​gist​.github​.com/​j​o​h​n​f​m​o​r​t​o​n​/​6​b​7​9​6​1​f​b​1​3​e​0​9​f​e​3​e​f​8​d​5​d​1​9​e​d​6​57614

No API key required. No prob­lem.

I’ve got some styles built into the func­tion, but you can remove them or cus­tomize them pret­ty eas­i­ly.

Wrap­ping up #

These updates deal with the major­i­ty of all CKEd­i­tor fields I cre­ate. Did I miss any­thing you use reg­u­lar­ly? I’d love to hear about it. Click the Con­act link and tell me about it.