Rich Text Editor - AtlasOfLivingAustralia/profile-hub Wiki

Profiles is using CKEditor, wrapped in an AngularJS directive.

CKEditor (website) supports a lot of different plugins.

CKEditor 5 (version 2.5 and above)

The version we are using is based on the Classic version, with a few useful plugins added in order to keep it as small as possible.

To update CKEditor

  1. Go to the CKEditor Builder page
  2. Click the classic button
  3. Add the plugins selected in [projects dir]/profile-hub/grails-app/assets/thirdparty/ckeditor5/src/ckeditor.js file using the online interface. This contains the built in plugins we are using. It also contains custom plugins. Make sure they are not added. Click Next.
  4. Choose the toolbar items and arrange them. Click next.
  5. Add/remove the languages using the controls on the UI
  6. Download the zip file
  7. Unpack the zip file and replace the contents of [projects dir]/profile-hub/grails-app/assets/thirdparty/ckeditor5/
  8. Asset pipeline requires CKEditor to be in ES5. Therefore we need to transpile the code using babeljs. Install the following dependencies npm install --save babel-loader @babel/core @babel/preset-env regenerator-runtime.
  9. Modify [projects dir]/profile-hub/grails-app/assets/thirdparty/ckeditor5/webpack.config.js to include the following in module.exports.module.rules path. See Note 1.
  10. Add the following code to [projects dir]/profile-hub/grails-app/assets/thirdparty/ckeditor5/webpack.config.js in path module.export.entry. See Note 2.
  11. Run webpack npx webpack. Build file should be found in build directory.
  12. Update build/ckeditor.js file by converting const keyword to var keyword. This part of code is inserted as string and escapes the transpiling process.
  13. More information on ES5 conversion can be found here.
{
				test: /\.js$/,
				use: [
					{
						loader: 'babel-loader',
						options: {
							presets: [ require( '@babel/preset-env' ) ]
						}
					}
				]
			}

Note 1

require.resolve( 'regenerator-runtime/runtime.js' )

Note 2

To add a custom plugin

Do not put custom plugins in the thirdparty/ckeditor directory - they will easily be deleted when CKEditor is updated. Put them in javascript/ckeditor/plugins (the javascript directory contains only our custom js).

  1. Install ckeditor built in plugins from npm. Change directory to [projects dir]/profile-hub/grails-app/assets/thirdparty/ckeditor5/. Then, npm install.
  2. Create a new file in [projects dir]/profile-hub/web-app/javascript/ckeditor/plugins with the name of your plugin. See InsertImage.js for example.
  3. Register the plugin in the [projects dir]/profile-hub/grails-app/assets/thirdparty/ckeditor5/src/ckeditor.js file. See note 3 below.
  4. Run webpack npx webpack. Build file should be found in build directory.
  5. Update build/ckeditor.js file by converting const keyword to var keyword. This part of code is inserted as string and escapes the transpiling process.
import InsertImage from '../../../javascripts/ckeditor/plugins/insertimage.js'
class Editor extends ClassicEditor {}

Editor.builtinPlugins = [
	Bold,
        ...
	InsertImage
];

export default Editor;

Note 3

CKEditor 4 (version 2.4.1 and below)

The version we are using is based on the Basic version, with a few useful plugins added in order to keep it as small as possible.

To update CKEditor

  1. Go to the CKEditor Builder page
  2. Click the upload build-config.js button
  3. Find the [projects dir]/profile-hub/web-app/thirdparty/ckeditor/build-config.js file. This contains the config we are using
  4. Add/remove additional plugins or languages using the controls on the UI
  5. Download the zip file
  6. Unpack the zip file and replace the contents of [projects dir]/profile-hub/web-app/thirdparty/ckeditor/
  7. Update the config in profiles.js as necessary
  8. Remove the directory [projects dir]/profile-hub/web-app/thirdparty/ckeditor/samples.

To add a custom plugin

Do not put custom plugins in the thirdparty/ckeditor directory - they will easily be deleted when CKEditor is updated. Put them in js/ckeditor (the js directory contains only our custom js).

  1. Create a new directory in [projects dir]/profile-hub/web-app/js/ckeditor/plugins with the name of your plugin.
  2. Add a plugin.js file
  3. Register the plugin in the plugin.js file using CKEDITOR.plugins.add('alaToolbar', { init: function (editor) {...}
  4. Update profiles.js and add a line like this CKEDITOR.plugins.addExternal('<plugin>', config.contextPath + '/static/js/ckeditor/plugins/<plugin>/');