Merge pull request #176 from ckeditor/t/ckeditor5/746

Feature: Introduced a `secureSourceElement()` utility that prevents from initialising more than one editor on the same DOM element. See ckeditor/ckeditor5#746.

src/editor/editorui.js

@@ -124,7 +124,9 @@ export default class EditorUI {
 		// It helps 3rd–party software (browser extensions, other libraries) access and recognize
 		// CKEditor 5 instances (editing roots) and use their API (there is no global editor
 		// instance registry).
-		domElement.ckeditorInstance = this.editor;
+		if ( !domElement.ckeditorInstance ) {
+			domElement.ckeditorInstance = this.editor;
+		}
 	}
 
 	/**

src/editor/utils/securesourceelement.js

@@ -0,0 +1,50 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
+/**
+ * @module core/editor/utils/securesourceelement
+ */
+
+/**
+ * Marks the source element on which the editor was initialized. This prevents other editor instances from using this element.
+ *
+ * Running multiple editor instances on the same source element causes various issues and it is
+ * crucial this helper is called as soon as the source element is known to prevent collisions.
+ *
+ * @param {module:core/editor/editor~Editor} editor Editor instance.
+ */
+export default function secureSourceElement( editor ) {
+	const sourceElement = editor.sourceElement;
+
+	// If the editor was initialized without specifying an element, we don't need to secure anything.
+	if ( !sourceElement ) {
+		return;
+	}
+
+	if ( sourceElement.ckeditorInstance ) {
+		/**
+		 * A DOM element used to create the editor (e.g.
+		 * {@link module:editor-inline/inlineeditor~InlineEditor.create `InlineEditor.create()`})
+		 * has already been used to create another editor instance. Make sure each editor is
+		 * created with an unique DOM element.
+		 *
+		 * @error editor-source-element-already-used
+		 * @param {HTMLElement} element DOM element that caused the collision.
+		 */
+		throw new CKEditorError(
+			'editor-source-element-already-used: ' +
+			'The DOM element cannot be used to create multiple editor instances.',
+			editor
+		);
+	}
+
+	sourceElement.ckeditorInstance = editor;
+
+	editor.once( 'destroy', () => {
+		delete sourceElement.ckeditorInstance;
+	} );
+}

tests/editor/editorui.js

@@ -130,6 +130,17 @@ describe( 'EditorUI', () => {
 
 			expect( element.ckeditorInstance ).to.equal( editor );
 		} );
+
+		it( 'does not override a reference to the editor instance in domElement#ckeditorInstance', () => {
+			const ui = new EditorUI( editor );
+			const element = document.createElement( 'div' );
+
+			element.ckeditorInstance = 'foo';
+
+			ui.setEditableElement( 'main', element );
+
+			expect( element.ckeditorInstance ).to.equal( 'foo' );
+		} );
 	} );
 
 	describe( 'getEditableElement()', () => {

tests/editor/utils/securesourceelement.js

@@ -0,0 +1,67 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* global document */
+
+import secureSourceElement from '../../../src/editor/utils/securesourceelement';
+import Editor from '../../../src/editor/editor';
+import { expectToThrowCKEditorError } from '@ckeditor/ckeditor5-utils/tests/_utils/utils';
+
+describe( 'secureSourceElement()', () => {
+	let editor, sourceElement;
+
+	beforeEach( () => {
+		class CustomEditor extends Editor {}
+
+		sourceElement = document.createElement( 'div' );
+		editor = new CustomEditor();
+
+		editor.sourceElement = sourceElement;
+		editor.state = 'ready';
+	} );
+
+	afterEach( () => {
+		if ( editor ) {
+			return editor.destroy();
+		}
+	} );
+
+	it( 'does not throw if the editor was not initialized using the source element', () => {
+		delete editor.sourceElement;
+
+		expect( () => {
+			secureSourceElement( editor );
+		} ).to.not.throw();
+	} );
+
+	it( 'does not throw if the editor was initialized using the element for the first time', () => {
+		expect( () => {
+			secureSourceElement( editor );
+		} ).to.not.throw();
+	} );
+
+	it( 'sets the property after initializing the editor', () => {
+		secureSourceElement( editor );
+
+		expect( sourceElement.ckeditorInstance ).to.equal( editor );
+	} );
+
+	it( 'removes the property after destroying the editor', () => {
+		secureSourceElement( editor );
+
+		return editor.destroy()
+			.then( () => {
+				expect( sourceElement.ckeditorInstance ).to.be.undefined;
+			} );
+	} );
+
+	it( 'throws an error if the same element was used twice', () => {
+		sourceElement.ckeditorInstance = 'foo';
+
+		expectToThrowCKEditorError( () => {
+			secureSourceElement( editor );
+		}, /^editor-source-element-already-used/, editor );
+	} );
+} );