CKEditor Tips & Hacks for gpEasy

This page is a combination of tips, tricks, hacks, and general information on using CKEditor with gpEasy CMS. Basically, I'll be putting up info I find when I want to figure out something with CKEditor or find something that can potentially cause problems for users.

General Info

gpEasy 2.0 introduced inline true WYSIWYG editing. To accomplish this CKEditor's toolbar now floats. You can move it to wherever you like.

Pasting text is unintuitive in HTML editors. Most people are used to just copying text from anywhere they want and pasting it. If you do that in an HTML editor you will end up with a lot of unnecessary code. The HTML editor tries to format the pasted text to look exactly like the original; however, that's not what we usually want on our web pages. We usually want it pasted in as plain text, thus there is a command for that, "paste as plain text." This will strip all the formatting code and past it into the editor as clean plain text so it will be formatted properly by your theme's style sheet (css).

Right click in CKEditor will bring up a menu. This is especially handy when you are working on elements such as tables. Many of the options you will need are there in the right click.

gpEasy Auto Complete Links Plugin

gpEasy CMS 1.7 Beta 1 introduces a great new feature to CKEditor, the HTML editor, auto completion of links. While the CKEditor plugin has just been introduced there are already some changes that will show up in the next revision. Therefore, I won't be displaying any images just yet, but I want to give you all a heads up on how this new plugin works and what changes will come with the next revision.

Search Your gpEasy Pages
Basically the new plugin searches all your gpEasy pages via the words in the page slug and menu label. However, there is a unique twist that can throw you off, it did me. If you start the link with a / as you are accustomed to then it no longer searches for words but page slug only; therefore it's best now to start without the slash and just type a word of the page or menu label you are looking for.

All you need to do is type a word in and a drop down list will be displayed showing you the pages you have that contain that word either in their slug/file name or label/menu label. It's super handy!

Once you see the page you want to link to just use the down arrow or mouse to select the page and the relative link is entered automatically. Currently if you hit the enter key to select the link CKEditor enters the link and closes the dialog. This will be changed in the next revision so the enter key will just enter the relative link so you can continue on with adding your title and other information for the link. Also, the current list isn't scrollable but it will be with the next revision, and the down arrow will bring up a list of all your pages even if you haven't typed any letters into the field while currently you have to type something.

While it sounds like a simple addition this a one of the handiest features to the HTML editor we could ask for.

Spell Checker in CKEditor

In gpEasy CKEditor's check spelling as you type is turned off by default. You can enable it via the toolbar; however, I would suggest leaving it off and using your browser's built in spell checker. Firefox and Chrome (not sure about the others these days) have built in spell checkers that you can enable. Once enabled they will spell check text fields such as CKEditor's. In fact they will spell check all the text fields, alternative name, captions, etc. This allows you to spell check any field in CKEditor and takes some of the burden off CKEditor and allows the browser to handle the load. It speeds up CKEditor and spell checking. There's only one trick to using it. You have to use Ctrl+right click on the miss-spelled word.

Copy/Paste & Browser Find

One of the first pitfalls I want to warn users about is copying in CKEditor when you use your browser's find or find & highlight all. The problem seems specific to hyperlinks. When you find or find and highlight all and copy a hyperlink often the URL address is stripped from the anchor or, especially in Firefox, some extraneous code is added..

Example: I find all occurrences of "widgets" and copy one that is linked then past it over another occurrence of the word widgets. The original linked "widgets" had a relative link: <a href="/widgets"> but the newly pasted linked "widgets" is stripped of the URL = <a href="">. That's not good.

Adding your theme's CSS to CKEditor

Please see the styling CKEditor tutorial.

Customize CKEditor's Toolbar Buttons

The file /include/js/ckeditor_config.js is used by gpEasy to configure certain features of CKEditor. One of those customized configurations that you can change are the toolbar buttons displayed by CKEditor. Open the ckeditor_config.js file and you will see the following code, .toolbar_gpeasy='gpeasy';

Following that code is the toolbar configuration for CKEditor. Now checkout CKEditor's developers code for customizing toolbar buttons. The page explains what you need to know to makes your own custom toolbar. Remember that the ckeditor_config.js file is a core gpEasy file and will be over-written with your next upgrade so keep a copy of your customized toolbar setting. See my custom ckeditor_config.js file for my custom toolbar settings as an example..

Adding Keyboard Shortcuts to CKEditor

Please go to the CKEditor keyboard shortcuts page.

Protect line breaks <br /> in CKEditor

One of the most frustrating things I've found with the default CKEditor setup is that line breaks <br /> aren't protected. In other words, CKEditor loves to change them to paragraph marks or wrap them in paragraph marks. Because of certain design challenges I was having this behavior just wasn't acceptable. So, I found out how to fix it.

Go to the \include\js\ckeditor_config.js file and enter this code at the end of the file:

CKEDITOR.config.shiftEnterMode = CKEDITOR.ENTER_P;

What does this code do? It changes the enter key behavior. By default when you hit enter (return key) CKEditor enters a new paragraph and when you hit enter+shift CKEditor enters a line break. The above code makes it do the opposite. You wouldn't think this would matter but it does. Let me give you an example.

Say you have two div elements with a line break between them for spacing. when you go to edit that page and click at that line break CKEditor will automatically change that line break to a new paragraph. With the above code that won't happen. So line breaks no longer have to be wrapped in paragraph marks. For most users this won't be a problem but for those of use whom it is a problem this it the best solution I've found. It isn't perfect however, the needed fix requires hacking another core CKEditor file and I'm of the mind set to hack as few core files as possible as it can make upgrade a pain.

Protect PHP Code

Please see the protect php code tutorial.

My Custom CKEditor Config File

Please go to the ckeditor_config.js page to see how I customized the CKEditor configuration file.

OK that it, check out the gpEasy tutorials for more information about working with gpEasy CMS.


gpEasy B2sq Theme by CS @True Acupuncture