You are here

How to customize the CKEditor on your Drupal 7 Website

We all want to have professional looking, consistently styled pages on our websites, right?  So how can you easily provide the styles you want to your content editors, without giving them access to all varieties of font sizes, colors and styles beyond the set you want to allow on your site?

Here is what you can accomplish with some CKEditor customizations: you can create a customized 'Styles'  drop down (as shown below), including only styles you want to be used on your site by content authors and editors.  You can use that to replace the 'Format', 'Font' and 'Size' drop downs that are enabled by default, so your content creators can no longer create pages with font styles that do not fit and/or are not pproved for your website.
Customized CKEditor screenshot, including custom styles drop-down

I have assumed that you have already downloaded and enabled CKEditor and have setup the module as you need for your content types, roles, etc already.  This tutorial only covers customizing the toolbar to include your own set of styles.

Setting up the toolbar

  1. Go to Configuration --> Content authoring --> CKEditor and edit the appropriate CKEditor profile (I did the below for both the Full and Advanced profiles!)
  2. Under the 'Editor Appearance' section, drag and drop the 'Styles' button to be used, and drag and drop the 'Format', 'Font', and 'Size' buttons to the bottom, unused section.  As you can see, I have also moved the 'Text color' and 'Background color' buttons, so content editors do not use unapproved colors.  Use your best judgement for your websites!
    Customizing ckeditor buttons
  3. Hit 'Save' at the bottom and start to edit or create a new piece of content to see your changes.  By default, the 'Styles' drop down will not include precisely the types of styles you want used on your site (for example, we do not want h1 tags to be used in our content body, since only the page title should be styled with h1).  Let's start customizing this list to fit our needs!

Customizing the 'Styles' drop-down

  1. Create a new text file called 'ckeditor.styles.js'.  We will use this to replace the ckeditor.styles.js file that comes with the ckeditor module by default.
    • Note: I saved this file directly in my custom theme's root folder.  Don't save it anywhere in the ckeditor module, or you'll forget that it's there and it will get overwritten next time you update the module...
  2. Create the styles you want to make available through your CKEditor interface in here, using the syntax described here.  I'm providing my own ckeditor.styles.js file below as an additional example:
    CKEDITOR.addStylesSet( 'drupal',
    [
    	/* Block Styles */
    	{ name : 'Heading 2'        , element : 'h2' },
    	{ name : 'Heading 3'        , element : 'h3' },
    	{ name : 'Heading 4'        , element : 'h4' },
    	{ name : 'Paragraph'        , element : 'p' },
    	{ name : 'Green Button',
    		element : 'div',
    		attributes : {
    		'class' : 'ncbc-green-button' }
    	},
    	{ name : 'Blue Image Button',
    		element : 'div',
    		attributes : {
    		'class' : 'ncbc-image-button' }
    	},
    
    	/* Inline Styles */
    	{ name : 'Inline Quotation'    , element : 'q' },
    
    	/* Object Styles */
    	{ name : 'Highlighted Row',
    		element : 'tr',
    		attributes : { 'class' : 'ncbc-highlighted-row' }
    	}
    ]);
  3. The above examples shows the use of block styles, inline styles and object styles.  Play around with them and keep refining and testing until you have the list that suits your needs!
    • Note: The object style I have above ('Highlighted Row') can be applied only when the editor's cursor is placed inside a table row (thus the "element: 'tr'").  That styles only appears in the 'styles' drop down if that condition is true.
  4. Make sure CKEditor knows where to find your new custom styles
    • Go back to the edit screen for your CKEditor profile(s), and find the 'Advanced options' section.
    • In the 'Custom Javascript configuration' box, paste in something like the following, but adjust for the path in which you saved your own file:
      config.stylesCombo_stylesSet = 'drupal:sites/all/themes/custom/<YOUR CUSTOM THEME>/ckeditor.styles.js'
  5. By the time you're done with the two sets of instructions above, you should have something like the desired drop-down that is displayed on the screenshot at the beginning of the tutorial.  However - these styles do not yet have any implementation that is meaningful.  Let's go ahead and create the css - and add it to our theme - that will make these styles look the way we want when they're used.  Otherwise, the elements editors apply the styles to will have the appropriate classes, but those classes will not have a match in any of our css files!

 

Implement the corresponding CSS

  1. Create a new css file, called ckeditor.css (or something like that), and save it in your theme's /css folder.  You can also choose to just include your css in an already existing css file, but I'll explain below why I chose to implement the css options included in my CKEditor separately.  You may choose to do this a little differently, of course.
  2. Define the css rules that you've included in your CKEditor's drop-down menu.  I'm not doing a tutorial on css here, but I'll provide a small snippet of my css file as an example
    tr.ncbc-highlighted-row { background-color: #E8E8E4; }
    tr a { text-decoration: none; }
    tr a:hover { text-decoration: underline; }
  3. Let your theme know about this new css file
    • Edit your theme's .info file and add the new css file in there.  To do that, add a line that looks something like this under all the other css files
      stylesheets[all][]        = css/ckeditor.css
    • If you flush your caches, your website will now pick up the new file, and you should see the correct styles applied to the correct elements
  4. Let CKEditor know about this new css file
    • This last step is not absolutely necessary, but it's confusing for the editors if you don't do it.  If CKEditor is not aware of the new styles, a content editor my select an element, apply a style to it from your drop-down, and not see any different to show her that the style has been applied (until she hits save and the page is actually rendered properly).
    • Go back to edit your CKEditor's profile(s) and find the 'CSS' section
    • For my CKEditor, I define my own CSS (first option), and only ask the CKEditor to use my html-reset and ckeditor.css stylesheets (second textbox).  You can choose to have it load more than just those, but I have a ton of stylesheets, some of which make my CKEditor go a little crazy.
      customizing css files CKEditor uses in its display

     

How to use

To use your wonderful new styles, simply highlight (select) a piece of text, and choose which style you want to apply to it from the drop-down:
Using CKEditor styles menu

Some styles (object styles) will only show in the drop down in the context of the object they apply to.  In  my case, when I place my cursor in a table row, I automatically get the 'Highlighted Row' style in the drop down:
CKEditor custom styles

​Enjoy your new consistent pages, which only use styles you have created and approved for your site!

Share

Comments

Hi Boriana,

thanks for your great blog!

It helps me setting custom styles in Drupal7 using CKEditor.

I now can see my custom style in CKEditor, e.g.: { name : 'Teaser Headline' , element : 'h2', attributes: {'id': 'header_teaser_headline'}}

But after I save the node the style is not shown in frontend.

There is no h2 tag in DOM only p tag. It should look like <h2 id="header_teaser_headline">My Headline</h2> but it looks like: <p data-thmr="thmr_13">My Headline</p>

I've cleared all cache (drupal with "drush cc all" and browser)

Thx for any help!
Dom

Dom, could you check one thing - after you highlight your "My Headline" text and apply the new style, is the style applied in the CKEditor itself?  Meaning, after you've tried to apply the style, if you hit the editor's 'SOURCE' button, is the h2 tag applied there (before you've saved)?

What I'm trying to understand is if it's never applied in the first place or if it's lost somehow during the 'save' which may have to do with your text formats/filters...

Editor's source looks like: <h2 id="header_teaser_headline">My Headline</h2> before AND after saving.

Only in frontend DOM it's missing. Same thing with blocks, not only view fields.

Strange thing... :)

Cool.  I see, so that means that the CKEditor styles are working correctly, and the styles are applied properly, but that something is messing up the *display*, not the html source of your node.

The 'data-thmr' seems like it may be applied by the Theme developer module.  Could you disable that and see if it fixes your problem?

Sorry, I've disabled the Theme developer module since a few hours :D

But it didn't solve the problem.

Here's the last thing I can think of.  Again - because the CKEditor customizations obviously work and are applied - it's just that something is messing with the *display* of them.  If it's not the additional styles of the Theme Developer module, then check out the 'Text format' you're using for your node type.  It should appear directly under the CKEditor in a drop-down.

Then check the configurations of that particular text format here: <your site>/admin/config/content/formats.  Make sure, when you check the settings, that the 'Limit allowed HTML tags' checkbox isn't checked, which may not allow <h2>'s to be displayed.  Look through all the options there and make sure there isn't something that could be messing up your display.

That did the trick.

'Limit allowed HTML tags' checkbox was checked.

Thank you! :)

Yay!  I'm so glad you got it working.  Thanks for reporting your issue - and hopefully this will help someone else.  Perhaps a tutorial on text formats should be next. ;-)

I am trying to add styles to UL and OL and change the default link color in the CK Editor, any advice on hwo to accomplish that?

Hey Chad,

If your question is about how to style links (in lists it seems?) within the actual editor itself, look back on step #3 above.  In some of my sites I use a separate css file specifically called ckeditor.css, which I include both in my theme's .info file *and* apply in CKEditor's configuration settings.  What that means is that all the css rules in that specific file are applied both to your nodes, once they are saved and viewed regularly and while you're looking at the node within the CKEditor itself.

You don't need to employ setting up separate styles from the drop-down if you want the style applied to all links or links within lists.  I think using the css file setup from above and putting your specific link styling in such a file should serve your purpose, unless I misunderstood the question...

Hope it makes sense.  Good luck!

Very helpful guide!

www.drupalcity.eu

jrvdtol@aol.com
When I open profile page I find under Editor Appearance:
Toolbar
Load sample toolbar: Basic | Advanced | Full
Whatever I click (Basic , Advanced or Full) nothing happens: No toolbar shown!
I think the installation of CKEditor with Drupal 7 is a mystery. I managed to get it working by also installing the WYSIWYG module. Without that it does not work. Everything OK now, but I can't let the end-user select a claas. And that's what I want.

My mission was to customise ckeditor to give the client just the appropriate amount of control over html. This article was exactly the help I needed. Then I ran into the same issue as Dom above, and reading your reply to her fixed that for me as well! Mission accomplished! :)

Oh, I'm so glad it worked for you too, Naomi.  I find this to be a surprisingly unknown part of Drupal+CKEditor, but it's such a help to non-technical editors.  I have some really cool, fancy styles pre-programmed in there for them.  :-)

I've Done all of this but whenever I have a file named ckeditor.styles.js in my theme's folder the drop down gets disabled and not working. by renaming the file it works again. What am I missing here?

Hi,
Great Step by Step Tutorial.

I have followed all your steps and cleared all Cashed.

But, some how when I save my page, my custom styles are not applied into it. I can see custom styles into CKEditor and can select it on text. But, at the end it doesn't show my heading or anything.
When I tried to debugged it with Chrome I can see that takes paragraph not heading which I applied.
Thanks!

Hey there,

Considering that the style is applied in the Editor, but not saved, I'm betting you're having an issue with your text formats.  It's nothing to do with the custom styles which work, but with the fact that styles are getting scrubbed off your content in the process of saving because of the text formatting you're applying in your editor.  Look at the first string of comments on this post and my comment about text formats, which solved the issue.  I bet that'll help you too!!

Good luck.

Wowwwwwwwwwwww.. Awesome !!
You were absolutely right.. I just unchecked 'Limit allowed HTML tags', and display problem got resolved.

Superb! You are GREAT!!

Thanks a bunchhhhhhhhhh !!! :)

So glad it worked! ;)

I prefer to use Codelobster to develop Drupal sites: http://codelobster.com/drupal.html

Thanks for this excellent tutorial.

One question, re "You can also choose to just include your css in an already existing css file, but I'll explain below why I chose to implement the css options included in my CKEditor separately."

I'm not sure you explained further?

Is it just because some of your stylesheets make your CKEditor "go a little crazy"?

I'm thinking I'll use an existing stylesheet, but curious to know if you found pitfalls with that workflow.

Hey, good question! Yes, the reason was indeed that some styles make the CKEditor "go a little crazy."  I love how you put that!  Haha.

In my case, some background colors and some header/footer issues were being applied within the CKEditor (everything looked fine once saved), but it was disruptive while editing.

That really was the only reason I chose an alternative approach.

There really shouldn't be any repercussions to saved content that you are viewing on the site, verses in 'edit' mode in the editor, because these styles apply strictly to the editor. Then again, that's precisely why you should choose to include styles that make sense in this setting, and it may be overkill to apply all your styles for all sections (not just the node area) within the editor.

Does that help at all?

I don't think that someone has already noted this above but I think that there is a slash missing between 'drupal:' and 'sites' in step 4 "Customizing the 'Styles' drop-down" . If you don't do this it will look for the file relative to the ckeditor module folder. So it should be like:

drupal:/sites/all/themes/custom/<YOUR CUSTOM THEME>/ckeditor.styles.js

Also, for those struggling with caching when adjusting your ckeditor.styles.js file, the only way I found of getting it to refresh was:

1. Add a version number (or something that you change each time you want to force a reload) to the end of the filename e.g. config.stylesCombo_stylesSet = 'drupal:/sites/all/themes/custom/<YOUR CUSTOM THEME>/ckeditor.styles.js?v=1'
2. Clear the cache, although I didn't always find this necessary.
3. Another option is to actually change the filename, but that is more tedious to do each time.

Very nice tutorial...helped me in saving time..thanks..!!

It worked.

Add new comment

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.