8
0
Просмотр исходного кода

Move `element` getter and `uiReady` event to `EditorUI` and deprecate the former.

Krzysztof Krztoń 7 лет назад
Родитель
Сommit
f2b2c5538f

+ 15 - 1
packages/ckeditor5-core/src/editor/editor.js

@@ -21,6 +21,7 @@ import EditingKeystrokeHandler from '../editingkeystrokehandler';
 
 import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
 import mix from '@ckeditor/ckeditor5-utils/src/mix';
+import log from '@ckeditor/ckeditor5-utils/src/log';
 
 import '@ckeditor/ckeditor5-utils/src/version';
 
@@ -319,7 +320,20 @@ export default class Editor {
 	}
 }
 
-mix( Editor, ObservableMixin );
+const ObservableMixinExtended = Object.assign( {}, ObservableMixin, {
+
+	_listenTo: ObservableMixin.listenTo,
+
+	listenTo( emitter, event, callback, options = {} ) {
+		if ( event === 'uiReady' ) {
+			log.warn( 'deprecated-editor-event-uiReady: The editor#uiReady event is deprecated.' );
+		}
+
+		this._listenTo( emitter, event, callback, options );
+	}
+} );
+
+mix( Editor, ObservableMixinExtended );
 
 /**
  * Fired after {@link #initPlugins plugins are initialized}.

+ 38 - 0
packages/ckeditor5-core/src/editor/editorui.js

@@ -64,6 +64,35 @@ export default class EditorUI {
 		this.listenTo( editor.editing.view.document, 'layoutChanged', () => this.update() );
 	}
 
+	/**
+	 * The main (outermost) DOM element of the editor UI.
+	 *
+	 * For example, in {@link module:editor-classic/classiceditor~ClassicEditor} it is a `<div>` which
+	 * wraps the editable element and the toolbar. In {@link module:editor-inline/inlineeditor~InlineEditor}
+	 * it is the editable element itself (as there is no other wrapper). However, in
+	 * {@link module:editor-decoupled/decouplededitor~DecoupledEditor} it is set to `null` because this editor does not
+	 * come with a single "main" HTML element (its editable element and toolbar are separate).
+	 *
+	 * This property can be understood as a shorthand for retrieving the element that a specific editor integration
+	 * considers to be its main DOM element.
+	 *
+	 * @readonly
+	 * @member {HTMLElement|null} #element
+	 */
+	get element() {
+		return null;
+	}
+
+	/**
+	 * Fires the {@link module:core/editor/editorui~EditorUI#event:ready `ready`} event.
+	 *
+	 * This method should be called after {@link module:core/editor/editor~Editor#event:pluginsReady} and before
+	 * {@link module:core/editor/editor~Editor#event:dataReady} by the specific editor creator.
+	 */
+	ready() {
+		this.fire( 'ready' );
+	}
+
 	/**
 	 * Fires the {@link module:core/editor/editorui~EditorUI#event:update `update`} event.
 	 *
@@ -82,6 +111,15 @@ export default class EditorUI {
 		this.view.destroy();
 	}
 
+	/**
+	 * Fired when the editor UI is ready.
+	 *
+	 * Fired after {@link module:core/editor/editor~Editor#event:pluginsReady} and before
+	 * {@link module:core/editor/editor~Editor#event:dataReady}.
+	 *
+	 * @event ready
+	 */
+
 	/**
 	 * Fired whenever the UI (all related components) should be refreshed.
 	 *

+ 23 - 2
packages/ckeditor5-core/src/editor/editorwithui.jsdoc

@@ -29,6 +29,8 @@
  */
 
 /**
+ * **Deprecated** since `v12.0.0`. The {@link module:core/editor/editorui~EditorUI#element `EditorUI element`} should be used instead.
+ *
  * The main (outermost) DOM element of the editor UI.
  *
  * For example, in {@link module:editor-classic/classiceditor~ClassicEditor} it is a `<div>` which
@@ -38,18 +40,37 @@
  * come with a single "main" HTML element (its editable element and toolbar are separate).
  *
  * This property can be understood as a shorthand for retrieving the element that a specific editor integration
- * considers to be its main DOM element. There are always other ways to access these elements, too
- * (e.g. via {@link #ui `editor.ui`}).
+ * considers to be its main DOM element.
  *
+ * @deprecated v11.2.0 The {@link module:core/editor/editorui~EditorUI#element `EditorUI element`} should be used instead.
  * @readonly
  * @member {HTMLElement|null} #element
  */
 
 /**
+ * **Deprecated** since `v12.0.0`. The {@link module:core/editor/editorui~EditorUI#event:ready ui ready event} should be listened to instead.
+ *
  * Fired when the editor UI is ready.
  *
  * Fired after {@link module:core/editor/editor~Editor#event:pluginsReady} and before
  * {@link module:core/editor/editor~Editor#event:dataReady}.
  *
+ * @deprecated v11.2.0 The {@link module:core/editor/editorui~EditorUI#event:ready ui ready event} should be listened to instead.
  * @event uiReady
  */
+
+/**
+ * This error is thrown when a component tries to access deprecated
+ * {@link module:core/editor/editorwithui~EditorWithUI#element editor element}. Instead the
+ * {@link module:core/editor/editorui~EditorUI#element `EditorUI element`} should be used.
+ *
+ * @error deprecated-editor-element
+ */
+
+/**
+ * This error is thrown when a component tries to listen to deprecated
+ * {@link module:core/editor/editorwithui~EditorWithUI#event:uiReady editor uiReady event}.
+ * Instead the {@link module:core/editor/editorui~EditorUI#event:ready ui ready event} should be listened to.
+ *
+ * @error deprecated-editor-event-uiReady
+ */

+ 26 - 3
packages/ckeditor5-core/tests/_utils-tests/classictesteditor.js

@@ -20,16 +20,19 @@ import ElementApiMixin from '../../src/editor/utils/elementapimixin';
 import RootElement from '@ckeditor/ckeditor5-engine/src/model/rootelement';
 
 import { getData } from '@ckeditor/ckeditor5-engine/src/dev-utils/model';
+import log from '@ckeditor/ckeditor5-utils/src/log';
 import testUtils from '../../tests/_utils/utils';
 
 describe( 'ClassicTestEditor', () => {
-	let editorElement;
+	let editorElement, logStub;
 
 	testUtils.createSinonSandbox();
 
 	beforeEach( () => {
 		editorElement = document.createElement( 'div' );
 		document.body.appendChild( editorElement );
+
+		logStub = testUtils.sinon.stub( log, 'warn' ).callsFake( () => {} );
 	} );
 
 	describe( 'constructor()', () => {
@@ -122,7 +125,7 @@ describe( 'ClassicTestEditor', () => {
 			class EventWatcher extends Plugin {
 				init() {
 					this.editor.on( 'pluginsReady', spy );
-					this.editor.on( 'uiReady', spy );
+					this.editor.ui.on( 'ready', spy );
 					this.editor.on( 'dataReady', spy );
 					this.editor.on( 'ready', spy );
 				}
@@ -133,7 +136,7 @@ describe( 'ClassicTestEditor', () => {
 					plugins: [ EventWatcher ]
 				} )
 				.then( editor => {
-					expect( fired ).to.deep.equal( [ 'pluginsReady', 'uiReady', 'dataReady', 'ready' ] );
+					expect( fired ).to.deep.equal( [ 'pluginsReady', 'ready', 'dataReady', 'ready' ] );
 
 					return editor.destroy();
 				} );
@@ -199,4 +202,24 @@ describe( 'ClassicTestEditor', () => {
 				} );
 		} );
 	} );
+
+	describe( 'deprecated uiReady event', () => {
+		it( 'logs deprecated warning when attaching uiReady on listener', () => {
+			return ClassicTestEditor.create( editorElement, { foo: 1 } )
+				.then( editor => {
+					editor.on( 'uiReady', () => {} );
+
+					expect( logStub.calledOnceWith( 'deprecated-editor-event-uiReady: The editor#uiReady event is deprecated.' ) ).to.true;
+				} );
+		} );
+
+		it( 'logs deprecated warning when attaching uiReady once listener', () => {
+			return ClassicTestEditor.create( editorElement, { foo: 1 } )
+				.then( editor => {
+					editor.once( 'uiReady', () => {} );
+
+					expect( logStub.calledOnceWith( 'deprecated-editor-event-uiReady: The editor#uiReady event is deprecated.' ) ).to.true;
+				} );
+		} );
+	} );
 } );

+ 1 - 1
packages/ckeditor5-core/tests/_utils/classictesteditor.js

@@ -75,7 +75,7 @@ export default class ClassicTestEditor extends Editor {
 					} )
 					.then( () => {
 						editor._elementReplacer.replace( element, editor.ui.view.element );
-						editor.fire( 'uiReady' );
+						editor.ui.ready();
 					} )
 					.then( () => editor.editing.view.attachDomRoot( editor.ui.view.editableElement ) )
 					.then( () => editor.data.init( getDataFromElement( element ) ) )

+ 20 - 0
packages/ckeditor5-core/tests/editor/editorui.js

@@ -44,6 +44,10 @@ describe( 'EditorUI', () => {
 			expect( ui.focusTracker ).to.be.instanceOf( FocusTracker );
 		} );
 
+		it( 'should have #element getter', () => {
+			expect( ui.element ).to.null;
+		} );
+
 		it( 'should fire update event after viewDocument#layoutChanged', () => {
 			const spy = sinon.spy();
 
@@ -59,6 +63,22 @@ describe( 'EditorUI', () => {
 		} );
 	} );
 
+	describe( 'ready()', () => {
+		it( 'should fire ready event', () => {
+			const spy = sinon.spy();
+
+			ui.on( 'ready', spy );
+
+			ui.ready();
+
+			sinon.assert.calledOnce( spy );
+
+			ui.ready();
+
+			sinon.assert.calledTwice( spy );
+		} );
+	} );
+
 	describe( 'update()', () => {
 		it( 'should fire update event', () => {
 			const spy = sinon.spy();