Rich Text (WYSIWYG) Editors
Rich Text (WYSIWYG) EditorsA "rich text" or "WYSIWYG" (What You See is What You Get) text editor gives your content editors a way to create and maintain content using an interface that looks and feels a lot like using a word processor. Formatting is applied using button controls, so the content editor doesn't have to know anything about HTML and can immediately see what the content is going to look like after it has been saved.
Drupal 9 / 10
Drupal 9 comes with the CKEditor version 4 text editor built-in, though it is a minimal version, so site administrators may wish to install additional features through CKEditor plugins.
NOTE: CKEditor version 5 is coming to Drupal 10, and is a complete rewriting of the CKEditor system. Because of this, we do not recommend anyone customize CKEditor 4 any further, as any customization will have to be redeveloped when upgrading to Drupal 10.
Drupal 7
Drupal 7 does not come with any kind of rich text editor. There are two popular add-on options commonly used on campus:
-
CKEditor Drupal module and CKEditor library: This popular editor is easy to set up and gives you a wide range of flexibility in what your content editors can create.
-
Georgia Tech GT Editor module: This module is actually built around CKEditor, but provides a great deal more control over what content editors can create, preventing them from doing things that might be dangerous (embedding JavaScript, for example.)
Rich Text Editor Guides and Resources
Drupal 9 CKEditor Enhancements, Tips and Tricks
Drupal 9 CKEditor Enhancements, Tips and TricksDrupal 8+ includes the popular What You See is What You Get (WYSIWYG) editor CKEditor, but out of the box it only provides the 'minimal' configuration, which is missing a lot of the features you may have come to enjoy when implementing CKEditor in Drupal 7 using the CKEditor module and the full version of CKEditor.
Fortunately, there are a few easy ways to make CKEditor much more useful. To start, the Drupal core team has assembled a list of add-on modules that implement popular CKEditor plugins, which makes it very easy to add official CKEditor features to your site:
CK Editor Modules and Plugins | Drupal.org
Important: Most if not all of these modules do not include the actual plugin. You will need to go to ckeditor.com and download the matching plugin, then create a 'libraries' directory at the root of your Drupal installation and unpack the plugin into that directory. For example, for the 'font' plugin, you should end up with a 'libraries/font' directory, which would have a file named 'plugin.js' in it, along with any other supporting files for the plugin.
When downloading a plugin, you will need the version that works with CKEditor 4.17.1, as that is what comes with Drupal 9.3. For future versions of Drupal, to determine what version of CKEditor you have, go to a page with the CKEditor editor visible, then open your browser's developer console and type:
alert(CKEDITOR.version);
In addition to the plugin based modules referenced above, the following special purpose Drupal 9 / CK Editor modules may also be of interest:
- Editor Advanced Link - Adds additional properties (title, class, id, target, rel) to the Link properties box
- Editor File - Adds the ability to upload files directly into CKEditor (just like you can now do with Images)
Here are a few more tips and tricks for enhancing CKEditor:
Where Did Image Properties Go?
One thing you won't find in any of the lists above is a means of bringing back the extensive set of image properties available in CKEditor under Drupal 7, and there's a reason for this. The designers of Drupal 8+ want you to upload properly sized images and let Drupal handle their placement, so that they can be as responsive as possible. This is actually a good thing in retrospect, as it's going to minimize the situations where a content editor uploads a giant 3000+ pixel image and then uses the size properties to make it fit on the screen.
That said, you're probably going to want a way to float images left and right. That ability still exists and is enabled via Configuation -> Content authoring -> Text formats and editors. Modify one of your text formats and look for the "Align images" checkbox under "Enabled Filters". The explanation for the option isn't very informative, but enabling it will enable options on the CKEditor image placement pop-up to left or right align (float) the image.
You'll also want to enable "Caption images" directly below "Align images", as it provides a very useful feature for entering automatically positioned and formatted visible image captions.
Expanding CKEditor's Default Window Height
Editor's Note: All current versions of Drupal 8+ now support CKEditor's dynamic height feature, which automatically grows the height of the editor box based on the number of lines of text it contains. So, the following is no longer needed, but has been left here in case someone should still want to force the default height to be larger.
One feature lost in Drupal 8 is the ability to set the number of rows on a textarea field and have CKEditor expand to fill that space. However, you can still manually set the height of CKEditor, but you have to do it by creating a simple module. We won't go into how to write a module here, as there are plenty of tutorials out there covering this basic topic. Once you have the skeleton of a bare bones module in place, add this function to it, replacing 'xxxxxx' with the machine name of your module:
function xxxxxx_editor_js_settings_alter(array &$settings) {
foreach (array_keys($settings['editor']['formats']) as $text_format_id) {
if ($settings['editor']['formats'][$text_format_id]['editor'] === 'ckeditor') {
$settings['editor']['formats'][$text_format_id]['editorSettings']['height'] = '600px';
}
}
}
This will set your CKEditor window height to 600px tall. Just change 600 to another value if you prefer the window to he taller or shorter.
Adding a Font Size Drop-Down
While it is not recommendable to add a font selection drop down on Georgia Tech sites, many content editors want to be able to make lines of text bigger, and if you don't give them a way to do it correctly, they'll make those lines headings, which creates accessibility problems.
The easiest way to fix this is to add the CKEditor Font plugin using the CKEditor Font module. Once installed you can edit any of your text formats and add the 'S' button (for font 'S'ize) to the button bar. However, if you want to be fully accessibility compliant, you should also change the available size list from point sizes to percentages. That can be done by creating another bare bones module (see the Window Height section above) and putting the following code into it:
function xxxxxx_editor_js_settings_alter(array &$settings) {
foreach (array_keys($settings['editor']['formats']) as $text_format_id) {
if ($settings['editor']['formats'][$text_format_id]['editor'] === 'ckeditor') {
$settings['editor']['formats'][$text_format_id]['editorSettings']['fontSize_sizes'] ='80%/80%;90%/90%;Normal/100%;110%/110%;120%/120%;130%/130%;140%/140%;150%/150%';
}
}
}
Note: if you want to change both the font size menu and the window height, you can (and should) combine the code into a single function in a single module. Just add the innermost assignment line from one of the code snippets to the other snippet.
Getting CKEditor to Use Your Theme CSS
By default CKEditor uses a very basic set of CSS, so the text you create and edit won't look exactly like it will when displayed by your Drupal site's theme. However, you can tell CKEditor to use your site's CSS so that the editing experience better reflects reality.
To do this, you will need to be using a custom sub-theme. In your sub-theme's .info.yaml file, add the following lines:
ckeditor_stylesheets:
- css/fonts.css
- css/general.css
YAML is very picky about spacing, so take care to get it right: it's two blank spaces (no tabs allowed), then a dash, then one more space. Of course, replace fonts.css and general.css with whichever CSS files are needed to implement your theme's special text formatting. You can have any number of CSS lines underneath the 'ckeditor_stylesheets:' heading.
If you add this to a theme that is already active, be sure to flush all of your caches to get the change to take effect.
CKEditor Companion Modules
CKEditor Companion ModulesThe Drupal community on campus has found a number of modules which help with using CKEditor:
IMCE
Versions: Drupal 9, 7
IMCE can be used for managing images, and you might even use imce for files, as well.
Installation instructions for IMCE:
- Download, install, and configure IMCE.
- Remove the default Image button.
- Add the IMCE button.
- Enable the option "Plugin for inserting files from imce without image dialog".
- Enable the option "Plugin for inserting Drupal embeded media".
LinkIt
Versions: Drupal 9, 7
LinkIt can be used for managing URL links to pages on the site and outside of the site.
Installation instructions for LinkIt:
- Download, install, and configure LinkIt
- Remove the default URL button.
- Add the LinkIt button.
- Check "Support for Linkit module".
Image Resize Filter
Versions: Drupal 9, 7
From the Drupal.org site: Image Resize Filter makes it easy to resize images, especially when combined with a WYSIWYG editor such as tinyMCE, CKeditor etc. Users never have to worry about scaling image sizes again, just insert an image and set it's height and width properties in HTML (this is done automatically by WYSIWYG editors) and the image is resized on output to match the HTML.
Embedding Digital Videos in CKEditor / GT Editor
Embedding Digital Videos in CKEditor / GT EditorEmbedding Georgia Tech MediaSpace Repository Content
A good solution for the Georgia Tech MediaSpace (Kaltura) repository has not been developed yet. In the meantime, an experimental MediaSpace embed module is available for Drupal 7 and Drupal 8+ from the developer who created the embed module for the now retired OIT Digital Media Repository. Use at your own risk!
-
IAC Support for oEmbed Formats for Drupal 9 (oEmbed support for MediaSpace, YouTube, Vimeo, and Google Maps)
- GT Kaltura Module for Drupal 7
After installing either module, you will have to add the new input filter to your preferred text formats. Make sure to set the ordering so that the filter comes last after all other filters. This ensures that the filter's Javascript code does not get filtered out by any of your other text filters.
There is also a method now for enabling MediaSpace as an oEmbed provider in the Drupal Media library system. The Media Library works outside of CKEditor and would be used in conjunction with custom blocks that contain Media fields (typically used with Layout Builder based page.)
Embedding YouTube and Vimeo Videos
Option #1 - Video Embed Field (Drupal 7 or 9)
- Download, install, and enable the Video Embed Field module.
- Add the new video field type to one or more of your Drupal Content Types.
- Content editors can now add videos to nodes of those content types by inserting the right linking details into the video field.
- WebWash provides a tutorial about video styles you can create with the Video Embed Field module.
Option #2 - Video Filter (Drupal 7)
- Download, install, and enable the Video Filter module.
- In the administrative configuration area of Drupal under Content authoring -> Text formats, configure each text format that you want to be able to use embedded videos.
- Enable the video filter.
- In the Filter processing order section, move the video filter down to the bottom of the list so that it is applied after all other filters.
- Don't forget to save your changes.
- On pages that use one of these configured text formats, you can now insert a video shortcode to create an embed of a supported video type. See the download page at the link above for the full list of supported video services and formats.
- Example shortcode for embedding a video:
[ VIDEO::http://www.youtube.com/watch?v=98nNpzE6gIs::aVideoStyle ]
Option #3 - Ivan Allen College oEmbed Support Module (Drupal 9)
- Install the IAC Support for oEmbed Formats for Drupal 9 module
- Add the new "Embed remote content with oEmbed links" input filter to your preferred text formats
- Where you want to place a YouTube video, just paste in the video's oEmbed URL (see the oEmbed module's instructions for full details)
Option #4 - Drupal Media Library and oEmbed
You can use the standard instructions for adding an oEmbed provider to Drupal's Media Library to enable the use of YouTube, Vimeo, and some other video services. In most cases YouTube will be enabled out-of-the-box. The Media Library works outside of CKEditor and would be used in conjunction with custom blocks that contain Media fields (typically used with Layout Builder based page.)
Embedding HTML, JavaScript or PHP Code on a Page
Embedding HTML, JavaScript or PHP Code on a PageThe Easy Way for IFRAME and JavaScript Embeds
The "Full HTML" format in an out-of-the-box installation of Drupal 9, or in Drupal 7 with CKEditor installed without the WYSIWYG plugin should already allow for IFRAME embeds and JavaScript embeds. If you haven't added any tools to restrict this, then you're all set.
For more restrictive CKEditor configurations, such as the GT Editor version of CKEditor for Drupal 7, you'll need to add a new text format (Configuration -> Content authoring -> Text formats and editors
) that at a minimum allows IFRAME embeds. If the service you want to embed from also requires you to include a snippet of JavaScript, then you'll need to enable that for your new text format as well. You'll then want to restrict this format to site administrators (which should hopefully be a separate role from that of your site's day-to-date content creators and editors). You can then add blocks where needed and use this new text format so that you can add your embed code to the block.
The Preferred Way for PHP Code
By far, the recommended way of adding custom PHP Code to a page of a Drupal site is by creating a custom module, which is a type of plugin that adds extra functionality to your Drupal site. This does require a reasonable amount of PHP coding experience and time to get familiar with how to code for Drupal. The Drupal organization has made some tutorials available to help get you started:
For a lot of cases, the right approach is to create a module that implements its own dynamic block(s). These will act like a custom block that you create in the Block Layout interface, only the content will be generated by your module instead of being entered through the Drupal user interface. Thus, you could implement a block that has your external embed code or custom PHP code output as its content, then place that block on whichever page you want the output to show.
The Absolutely Wrong Way for PHP Code
Do not try to use the PHP Code Filter module under any circumstances! This module used to let you put PHP Code directly into CKEditor and have it get processed when the page is displayed. It is very unsafe and can't even be turned on in Drupal 7 unless you upgraded to Drupal 7 from an earlier version that had it turned on. In addition, the module has been completely removed from Drupal 8. If you are already using this method for custom PHP, you should look into switching to one of the following methods as soon as possible.
Installing and Using CKEditor in Drupal 7
Installing and Using CKEditor in Drupal 7There are two parts to installing CKEditor for Drupal 7 (Drupal 8 comes with it already installed):
- The CKEditor Drupal module, which is placed in the
sites/all/modules
folder. - The CKEditor library, which is placed INSIDE the
sites/all/libraries
folder.
After installing the module and library, enable the module and it should take effect immediately.
If you want to customize your CKEditor settings, look in the administrative configuration area under Content Authoring -> CKEditor.
Additional Resources for Using CKEditor in Drupal 7
Creating a True WYSIWYG Environment in CKEditor [Drupal 7]
Creating a True WYSIWYG Environment in CKEditor [Drupal 7]If you'd like the look and feel of your body text field to better mimic the look and feel of your site's theme when editing pages then you'll need to configure the CSS settings for the appropriate CKEditor profiles to use your theme's CSS.
- Go to Configuration -> Content authoring -> CKEditor
- Select the Edit link under the OPERATIONS row for the appropriate CKEditor profile (advanced, basic, etc.)
- Under the CSS accordion fieldset change the Editor CSS drop-down to use "Define CSS"
- In the CSS file path field you'll need to enter the path to the CSS file(s) of your theme. If you'd like it to use the CSS from the main GT theme, enter the following:
/sites/all/themes/gt/css/reset.css?v=1,/sites/all/themes/gt/css/default.css?v=1,/sites/all/themes/gt/css/typography.css?v=1,/sites/all/themes/gt/css/editor.css?v=1
Note the query string at the end of each CSS file listed (i.e., "?v=1") If you are experimenting with adding links to your own stylesheets and are finding your changes aren't showing up, just change the value in the query string, save the CKEditor settings, and next time you edit a page your changes will most likely show up. By changing the query string value you'll get CKEditor to reload the stylesheet.
See Adding Classes to the CKEditor Styles Dropdown List if you'd like to add new custom styles there as well.
Adding Classes to the CKEditor Styles Dropdown List [Drupal 7]
Adding Classes to the CKEditor Styles Dropdown List [Drupal 7]If you want your editors to be able to easily apply your custom CSS classes via the Styles drop-down list in the GT Editor:
- Copy the
js/ckeditor.styles.js
file from the GT Theme (version 7.x-2.2 and above) into your subtheme folder. - Add your own CSS styles to this file. The CKEditor documentation explains how this works.
- Go to Configuration -> Content authoring -> CKEditor
- Select the Edit link under the OPERATIONS row for the appropriate CKEditor profile (advanced, basic, etc.)
- Under the CSS accordion fieldset change the Predefined styles drop-down to "Use theme ckeditor.styles.js"
- Flush your browser's caches to get CKEditor to pick up the new file. You'll need to flush your browser's caches each time you update this file.
If you'd rather not rely on users caches expiring or telling them to flush their caches, you can use another technique to specify your styles file:
- Go to Configuration -> Content authoring -> CKEditor
- Select the Edit link under the OPERATIONS row for the appropriate CKEditor profile (advanced, basic, etc.)
- Under the CSS accordion fieldset change the Predefined styles drop-down to "Define path to ckeditor.styles.js"
- Set the Predefined styles path to point to your custom styles file. Add "?v=XXX" where XXX is some random value. Change this value each time you make changes to your styles file. This change will trigger web browsers to consider the file to be updated and to ignore the version held in the browser cache.
NOTE: If you implement a custom ckeditor.styles.js
file, you'll need to remember to integrate into this file any changes to the standard styles introduced by any newer version of the GT Theme.
GT Editor Site Administrator Documentation [Drupal 7]
GT Editor Site Administrator Documentation [Drupal 7]The Georgia Tech GT Editor module for Drupal 7 is built around CKEditor, but provides a great deal more control over what content editors can create, preventing them from doing things that might be dangerous (embedding JavaScript, for example.)
This is a community supported project, meaning it is not officially supported by OIT or Institute Communications.
GT Editor Guides and Tutorials
Allowing Additional CSS Classes in GT Editor [Drupal 7]
Allowing Additional CSS Classes in GT Editor [Drupal 7]Are you adding design elements with CSS and want editors to be able to use your new CSS classes within GT Editor? You may have discovered that those classes are being stripped out when the page is saved. What's happening is that GT Editor operates on a whitelist principle to keep your site and its content safe. You must add any elements, classes, etc. that you want to use to the editor's whitelist - otherwise, it will assume the worst and remove them when you save a page. GT Editor strips all non-whitelisted classes and elements using the WYSIWYG Filter module. This module is configured within each text format (such as the "basic text editor" format that comes standard in GT Editor).
The Easy Way: Use Standard "gt-ed-*" Class Naming
The latest versions of GT Editor (7.x-2.0-beta1 and above) will allow any CSS class that starts with "gt-ed-". So, if you don't mind adding CSS classes that use this naming format, you're done.
Create Your Own Text Format
If you want to use CSS classes that aren't in the "gt-ed-" naming format, you will need to create your own text format (at admin/config/content/formats
). This way, any changes you make to the format won't be overwritten when you update the GT Editor.
It is recommended that you copy the settings from the existing basic text editor text format into your new format, and THEN make changes. If you take this approach, you'll need to remember to integrate changes to this format from each new GT Editor version.
To add to the whitelist of classes, look under your text format's WYSIWYG Filter settings at: admin/config/content/formats/text_editor_basic
. You will see sections called Rules for Class Names and Rules for Element IDs where these filters are configured.
Unhiding the CKEditor Text Format Selector [Drupal 7]
Unhiding the CKEditor Text Format Selector [Drupal 7]CKEditor normally shows a Text format drop-down selector just below the editing window, but the GT Editor hides this selector to streamline the editing experience. However, there can be cases where you want to use other Drupal text formats for special cases (e.g. embedding a Twitter or Facebook feed).
The GT Subtheme has CSS code that hides the drop-down, which you can find at sites/all/themes/gt_subtheme/css/gt_subtheme.css
. The lines that hide the text format dropdown box are:
div.form-item-log,
.preview h3,
.preview .node-teaser,
body.page-admin-structure-block-add .form-item-regions-seven,
body.page-admin-structure-block-manage-block .form-item-regions-seven,
fieldset#edit-body-und-0-format,
fieldset#edit-field-body-1-und-0-format,
fieldset#edit-field-body-2-und-0-format,
fieldset#edit-field-body-3-und-0-format
{
display: none;
}
Changing the Default Format Without Displaying the Text Format Selector
If you have created your own text format and want your editors to use it instead of the "basic text editor" format, you should change the order of the text formats so that yours is first/on top at admin/config/content/formats
.
GT Editor Paragraph Image Wrapping Problem [Drupal 7]
GT Editor Paragraph Image Wrapping Problem [Drupal 7]Some Georgia Tech Drupal users have encountered a bug where CKEditor/WYSIWYG settings were wrapping standalone images in paragraph tags. To fix this problem, follow the two steps below.
Step 1. Adjust Your Theme's template.php.
In your theme’s template.php
file, add:
/**
* Implements hook_wysiwyg_editor_settings_alter()
*/
function THEMENAME_wysiwyg_editor_settings_alter(&$settings, $context) {
if ($context['profile']->editor == 'ckeditor') {
$settings['autoParagraph'] = FALSE;
}
}
Be sure to replace "THEMENAME" with the actual machine name of your theme. For the standard GT theme, the function name would be gt_wysiwyg_editor_settings_alter
Step 2. Adjust Your Text Format.
In your browser, go to {domain}/admin/config/content/formats
and modify each text format that your site is actively using. F or your specified text formats (here I’m listing the Advanced one), located at , make sure that the option "Convert line breaks into HTML (i.e. <br>
and <p>
)" is turned off.