Add Custom Editor
Before you begin…
This tutorial goes through the process of adding CKEditor4 as an editor that can be used by the WYSIWYG UI component.
As a developer, use this tutorial as a guide for adding your own custom JavaScript editor to Magento.
Step 1. Make the editor library available
Download and install your editor’s library into your module’s view/base/web/js directory to have Magento publish it under pub/static.
Step 2. Register editor
In your module’s etc/adminhtml/di.xml file, add your editor to the list of adapterOptions to include it to the list of available WYSIWYG editors in the Admin.
Provide unique values for the name parameter and the value and label entries for your editor to avoid naming collisions.
If you are also extending or overriding the configuration for Variable, Widget, or Gallery, you must use the same string as the value entry.
CKEditor registration in
app/code/CKEditor/CKEditor4/etc/adminhtml/di.xml
1
2
3
4
5
6
7
8
9
10
<type name="Magento\Cms\Model\Config\Source\Wysiwyg\Editor">
<arguments>
<argument name="adapterOptions" xsi:type="array">
<item name="ckeditor" xsi:type="array">
<item name="value" xsi:type="string">CKEditor_CKEditor4/ckeditor4Adapter</item>
<item name="label" xsi:type="string" translatable="true">ckeditor</item>
</item>
</argument>
</arguments>
</type>
To avoid issues in the case that we remove or disable the adapter module, add this configuration to the di.xml file:
Configuration in
di.xml
1
2
3
4
5
6
7
8
9
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
<type name="Magento\Ui\Block\Wysiwyg\ActiveEditor">
<arguments>
<argument name="availableAdapterPaths" xsi:type="array">
<item name="CKEditor_CKEditor4/ckeditor4Adapter" xsi:type="string"/>
</argument>
</arguments>
</type>
</config>
Step 3. Create editor adapter
Create an adapter for your editor in your module’s view/base/web directory.
This adapter should implement the extensions points called by wysiwygInstance in the following file:
lib/mage/adminhtml/wysiwyg/tiny_mce/setup.js
At minimum your adapter should implement the following methods:
getAdapterPrototype()setup( mode )openFileBrowser( o )toggle()onFormValidation()encodeContent(content)
If you are integrating Magento entities such as variable and widget as plugins, your adapter must also implement the following methods:
get( id )- returns the editor by it element idgetContent()- returns the content stored in the WYSIWYG fieldsetContent(content)- replaces the entire contents of the WYSIWYG with the string content parameterinsertContent( content )- inserts content into the editorsetCaretOnElement( targetElement )- sets the caret location in the editor-
activeEditor()- returns the active editor as an object with aselectionproperty.The
selectionproperty returns an instance of the editor with the following additional methods defined:-
getBookmark( type:Number, normalized:Boolean ):Object- returns a bookmark object that has the location for the current selection.This is used to restore the selection after content modification in the document.
moveToBookmark( bookmark:Object ):Boolean- restores the selection of the specified bookmark.getNode():Element- returns the currently selected element or common ancestor element for both start and end of the selection.-
select( targetElement )- selects the specified element.This places the start and end of the selection range around the element.
collapse( to_start:Boolean ):void- collapse the selection to start or end of range.
-
Example: CKEditor/CKEditor4/view/base/web/ckeditor4Adapter.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
/**
* Copyright © Magento, Inc. All rights reserved.
* See COPYING.txt for license details.
*/
/* global varienGlobalEvents, tinyMceEditors, MediabrowserUtility, closeEditorPopup, Base64 */
/* eslint-disable strict */
define([
'jquery',
'underscore',
'CKEditor_CKEditor4/js/ckeditor4/ckeditor',
'mage/translate',
'prototype',
'mage/adminhtml/events',
'jquery/ui'
], function (jQuery, _, ckeditor4) {
var ckeditorWysiwyg = Class.create();
ckeditorWysiwyg.prototype = {
mediaBrowserOpener: null,
mediaBrowserTargetElementId: null,
/**
* @param {*} htmlId
* @param {Object} config
*/
initialize: function (htmlId, config) {
this.id = htmlId;
this.config = config;
if (typeof ckeditorWysiwyg === 'undefined') {
window.ckeditorWysiwyg = $H({});
}
var settings = '';
ckeditorWysiwyg.settings = this.config;
settings = $H({});
if (this.config.plugins) {
this.config.plugins.each(function (plugin) {
settings.set(plugin.name, plugin.options);
});
this.config.magentoPluginsOptions = settings;
}
this.config.elements = this.id;
ckeditor4.settings = this.config;
},
/**
* @param {*} mode
*/
setup: function (mode) {
ckeditor4.replaceAll();
},
/**
* Insert content to active editor.
*
* @param {String} content
* @param {Boolean} ui
*/
insertContent: function (content, ui) {
this.activeEditor().insertText(content);
},
/**
* @param {Object} o
*/
openFileBrowser: function (o) {
},
/**
* Encodes the content so it can be inserted into the wysiwyg
* @param {String} content - The content to be encoded
*
* @returns {*} - The encoded content
*/
updateContent: function (content) {
},
/**
* On form validation.
*/
onFormValidation: function () {
if (tinyMCE4.get(this.id)) {
$(this.id).value = tinyMCE4.get(this.id).getContent();
}
},
/**
* @param {String} id
*/
get: function (id) {
return ckeditor4.instances[id];
},
/**
* @return {Object}
*/
activeEditor: function () {
var activeInstance = false;
_.each(ckeditor4.instances, function (instance) {
if (instance.activeEnterMode === 1) {
activeInstance = instance;
instance.getBookmark = function () {
return null;
};
instance.moveToBookmark = function () {
return instance;
};
instance.getNode = function () {
return instance.getSelection();
};
instance.getNode = function () {
return instance.getSelection();
};
activeInstance.selection = instance;
}
});
return activeInstance;
},
/**
* @param {*} mode
* @return {tinyMceWysiwygSetup}
*/
turnOn: function (mode) {
},
/**
* @return {tinyMceWysiwygSetup}
*/
turnOff: function () {
return this;
},
/**
* Retrieve directives URL with substituted directive value.
*
* @param {String} directive
*/
makeDirectiveUrl: function (directive) {
},
/**
* @param {Object} content
* @return {*}
*/
encodeDirectives: function (content) {
},
/**
* @param {Object} content
* @return {*}
*/
encodeWidgets: function (content) {
},
/**
* @param {Object} content
* @return {*}
*/
decodeDirectives: function (content) {
},
/**
* @param {Object} content
* @return {*}
*/
decodeWidgets: function (content) {
},
/**
* @param {Object} attributes
* @return {Object}
*/
parseAttributesString: function (attributes) {
},
/**
* Update text area.
*/
updateTextArea: function () {
},
setCaretOnElement: function (targetElement) {
this.activeEditor().selection.select(targetElement);
this.activeEditor().selection.collapse();
},
/**
* @param {Object} content
* @return {*}
*/
decodeContent: function (content) {
},
/**
* @return {Boolean}
*/
toggle: function () {
return this.wysiwygInstance.toggle();
},
/**
* @param {Object} content
* @return {*}
*/
encodeContent: function (content) {
},
/**
* @param {Object} o
*/
beforeSetContent: function (o) {
},
/**
* @param {Object} o
*/
saveContent: function (o) {
},
/**
* @returns {Object}
*/
getAdapterPrototype: function () {
return ckeditorWysiwyg;
},
/**
* Return the content stored in the WYSIWYG field
* @param {String} id
* @return {String}
*/
getContent: function (id) {
}
};
return ckeditorWysiwyg.prototype;
});
Step 4. Load editor library
After loading, modifying, and merging all configurations, Magento serializes the result into a JSON object and passes it to the UI component.
In your module’s view/base/requirejs-config.js file, add a shim configuration entry for your editor in order to have RequireJS load it correctly.
Example: CKEditor\CKEditor4\view\base\requirejs-config.js
1
2
3
4
5
var config = {
"shim": {
"CKEditor_CKEditor4/js/ckeditor4/ckeditor": { "exports": "CKEDITOR" }
}
};