Expose public API for refreshing widget mask and parts

CHANGES.md

@@ -28,6 +28,7 @@ API Changes:
 * [#3727](https://github.com/ckeditor/ckeditor4/issues/3727): Added new commands `textColor` and `bgColor` which applies the selected color choosen by the [Color Button](https://ckeditor.com/cke4/addon/colorbutton) plugin.
 * [#3728](https://github.com/ckeditor/ckeditor4/issues/3728): Added new commands `font` and `fontSize` which applies the selected font style choosen by the [Font](https://ckeditor.com/cke4/addon/colorbutton) plugin.
 * [#3842](https://github.com/ckeditor/ckeditor4/issues/3842): Added [`editor.getSelectedRanges`](https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR_editor.html#method-getSelectedRanges) alias.
+* [#3775](https://github.com/ckeditor/ckeditor4/issues/3775): Widget [mask](https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR_plugins_widget.html#property-mask) and [parts](https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR_plugins_widget.html#property-parts) can now be refreshed dynamically via API calls.
 
 ## CKEditor 4.13.1
 

plugins/widget/plugin.js

@@ -986,11 +986,23 @@
 		 *
 		 * For every `partName => selector` pair in {@link CKEDITOR.plugins.widget.definition#parts},
 		 * one `partName => element` pair is added to this object during the widget initialization.
+		 * Parts can be reinitialized with {@link #refreshParts} method.
 		 *
 		 * @readonly
 		 * @property {Object} parts
 		 */
 
+		/**
+		 * An object containing definitions of widget parts (`part name => CSS selector`).
+		 *
+		 * Unlike {@link #parts} object, it stays unchanged throughout the widget lifecycle
+		 * and is used in {@link #refreshParts} method.
+		 *
+		 * @readonly
+		 * @property {Object} partSelectors
+		 * @since 4.14.0
+		 */
+
 		/**
 		 * The template which will be used to create a new widget element (when the widget's command is executed).
 		 * It will be populated with {@link #defaults default values}.
@@ -1420,6 +1432,31 @@
 			this.editor.focus();
 		},
 
+		/**
+		 * Refreshes widget's mask. Can be used together with {@link #refreshParts} method to reinitialize mask
+		 * for dynamically created widgets.
+		 *
+		 * @since 4.14.0
+		 */
+		refreshMask: function() {
+			setupMask( this );
+		},
+
+		/**
+		 * Reinitializes widget's {@link #parts}.
+		 *
+		 * This method can be used to link new DOM elements to widget parts, for example in case when widget's HTML is created
+		 * asynchronously or modified during widget lifecycle. Note that it uses {@link #partSelectors} object, so it doesn't
+		 * refresh parts that were created manually.
+		 *
+		 * @since 4.14.0
+		 * @param {Boolean} [refreshInitialized=true] Whether parts that are already initialized should be reinitialized.
+		 */
+		refreshParts: function( refreshInitialized ) {
+			refreshInitialized = typeof refreshInitialized !== 'undefined' ? refreshInitialized : true;
+			setupParts( this, refreshInitialized );
+		},
+
 		/**
 		 * Removes a class from the widget element. This method is used by
 		 * the {@link #removeStyle} method and should be overriden by widgets
@@ -3598,15 +3635,23 @@
 	// partName => selector pairs
 	// with:
 	// partName => element pairs
-	function setupParts( widget ) {
+	function setupParts( widget, refreshInitialized ) {
+		if ( !widget.partSelectors ) {
+			widget.partSelectors = widget.parts;
+		}
+
 		if ( widget.parts ) {
 			var parts = {},
 				el,
 				partName;
 
-			for ( partName in widget.parts ) {
-				el = widget.wrapper.findOne( widget.parts[ partName ] );
-				parts[ partName ] = el;
+			for ( partName in widget.partSelectors ) {
+				if ( refreshInitialized || !widget.parts[ partName ] || typeof widget.parts[ partName ] == 'string' ) {
+					el = widget.wrapper.findOne( widget.partSelectors[ partName ] );
+					parts[ partName ] = el;
+				} else {
+					parts[ partName ] = widget.parts[ partName ];
+				}
 			}
 			widget.parts = parts;
 		}
@@ -3727,8 +3772,8 @@
 		var part = this.parts[ this.maskPart ],
 			mask;
 
-		// If requested part is invalid, don't create mask.
-		if ( !part ) {
+		// If requested part is invalid or wasn't fetched yet (#3775), don't create mask.
+		if ( !part || typeof part == 'string' ) {
 			return;
 		}
 

tests/plugins/widget/definition.js

@@ -417,6 +417,68 @@
 			} );
 		},
 
+		// (#3775)
+		'test parts refresh': function() {
+			var editor = this.editor,
+				bot = this.editorBot;
+
+			var widgetDef = {
+				parts: {
+					first: '.first',
+					second: '.second',
+					third: '.third'
+				}
+			};
+
+			editor.widgets.add( 'testparts2', widgetDef );
+
+			bot.setData( '<div data-widget="testparts2" id="w"><p class="first">Hello</p><p class="third">!</p></div>', function() {
+				var missingPart = CKEDITOR.dom.element.createFromHtml( '<p class="second">World</p>' ),
+					widget = getWidgetById( editor, 'w' );
+
+				assert.areEqual( 2, widget.element.getChildCount(), 'Middle part of widget should be missing.' );
+				assert.areEqual( widget.parts.second, null, 'Middle part of widget should be missing.' );
+
+				missingPart.insertAfter( widget.wrapper.findOne( '.first' ) );
+
+				widget.refreshParts();
+
+				assert.areEqual( 3, widget.element.getChildCount(), 'Middle part of widget should be inserted.' );
+				assert.areEqual( widget.parts.second, missingPart, 'Middle part of widget should be inserted.' );
+			} );
+		},
+
+		// (#3775)
+		'test parts refresh flag': function() {
+			var editor = this.editor,
+				bot = this.editorBot;
+
+			var widgetDef = {
+				parts: {
+					first: '.first',
+					second: '.second'
+				}
+			};
+
+			editor.widgets.add( 'testparts2', widgetDef );
+
+			bot.setData( '<div data-widget="testparts2" id="w"><p class="first">Hello</p><p class="second">World!</p></div>', function() {
+				var widget = getWidgetById( editor, 'w' ),
+					partToRefresh = CKEDITOR.dom.element.createFromHtml( '<p class="second">World!</p>' );
+
+				widget.wrapper.findOne( '.second' ).remove();
+				partToRefresh.insertAfter( widget.element.findOne( '.first' ) );
+
+				widget.refreshParts( false );
+
+				assert.areEqual( widget.parts.second.getParent(), null, 'Deleted widget part should not be reinitialized.' );
+
+				widget.refreshParts();
+
+				assert.areEqual( widget.parts.second.getParent(), widget.element, 'Deleted widget part should be reinitialized.' );
+			} );
+		},
+
 		'test defined dialog name': function() {
 			var editor = this.editor;
 

tests/plugins/widget/manual/refreshmaskapi.html

@@ -0,0 +1,87 @@
+<div id="editor">
+	<p>bar</p>
+	<div id="widget" class="partiallyMasked"><div class="notmasked">You can type here...</div></div>
+</div>
+<div>
+	<button id="add-content">Add missing widget HTML</button>
+</div>
+<div>
+	<button id="refresh-parts">Refresh widget parts</button>
+</div>
+<div>
+	<button id="refresh-mask">Refresh widget mask</button>
+</div>
+
+<script>
+	CKEDITOR.addCss( '.left { float: left; width: 200px; } .right { float: right; width: 200px; } .cke_widget_partial_mask { border: 1px solid red };' );
+
+	CKEDITOR.stylesSet.add( 'default', [
+		{ name: 'None', type: 'widget', widget: 'partiallyMasked', attributes: { 'class': '' }, group: 'alignment' },
+		{ name: 'Left', type: 'widget', widget: 'partiallyMasked', attributes: { 'class': 'left' }, group: 'alignment' },
+		{ name: 'Right', type: 'widget', widget: 'partiallyMasked', attributes: { 'class': 'right' }, group: 'alignment' }
+	] );
+
+	CKEDITOR.plugins.add( 'partiallyMasked', {
+		requires: 'widget',
+		init: function( editor ) {
+			editor.widgets.add( 'partiallyMasked', {
+				button: 'Partial mask widget',
+				pathName: 'test-widget',
+
+				template:
+					'<div class="partiallyMasked">' +
+						'<div class="notmasked"></div>' +
+						'<div class="content"></div>' +
+					'</div>',
+
+				editables: {
+					nomask: {
+						selector: '.notmasked',
+						allowedContent: 'br'
+					},
+					content: {
+						selector: '.content',
+						allowedContent: 'br'
+					}
+				},
+
+				parts: {
+					nomask: '.notmasked',
+					content: '.content'
+				},
+
+				allowedContent: 'div(partiallyMasked,content,notmasked,left,right)',
+				requiredContent: 'div(partiallyMasked)',
+
+				mask: 'content',
+
+				upcast: function( element ) {
+					return element.name == 'div' && element.hasClass( 'partiallyMasked' );
+				}
+			} );
+		}
+	} );
+
+	var editor = CKEDITOR.replace( 'editor', {
+		extraPlugins: 'partiallyMasked'
+	} );
+
+	CKEDITOR.document.findOne( '#add-content' ).on( 'click', function() {
+		var div = new CKEDITOR.dom.element( 'div' ),
+			widget = editor.widgets.instances[ 0 ];
+
+		if ( !widget.element.findOne( '.content' ) ) {
+			div.setText( '...but not here' );
+			div.addClass( 'content' );
+
+			widget.element.append( div );
+		}
+	} );
+	CKEDITOR.document.findOne( '#refresh-parts' ).on( 'click', function() {
+		editor.widgets.instances[ 0 ].refreshParts();
+	} );
+	CKEDITOR.document.findOne( '#refresh-mask' ).on( 'click', function() {
+		editor.widgets.instances[ 0 ].refreshMask();
+	} );
+
+</script>

tests/plugins/widget/manual/refreshmaskapi.md

@@ -0,0 +1,68 @@
+@bender-ui: collapsed
+@bender-tags: 4.14.0, feature, 3775
+@bender-ckeditor-plugins: wysiwygarea,toolbar,clipboard,image2,sourcearea,list,undo,stylescombo
+
+**Note:** Mask has a red border so it's positioning is visible without inspecting mask element,
+but still keep the console opened and watch out for errors.
+
+1. Click `Refresh widget mask` button below editor.
+
+  **Expected:**
+
+  Nothing happened.
+
+  **Unexpected:**
+
+  Error was thrown.
+
+1. Click `Add missing widget HTML` button below editor.
+
+  **Expected:**
+
+  Widget expanded by the second row. It's not clickable, but there is no mask (red border).
+
+  **Unexpected:**
+
+  Second row didn't appear.
+
+1. Click `Refresh widget mask` button below editor.
+
+  **Expected:**
+
+  Nothing happened.
+
+  **Unexpected:**
+
+  Error was thrown.
+
+1. Click `Refresh widget parts` button below editor.
+
+1. Click `Refresh widget mask` button below editor.
+
+  **Expected:**
+
+  Mask appeared over the second row.
+
+  **Unexpected:**
+
+  Mask didn't appear or error was thrown.
+
+1. Add a new row in the widget's editable.
+
+  **Expected:**
+
+  Mask moved and still covers the right part of widget.
+
+  **Unexpected:**
+
+  Mask didn't move.
+
+1. Switch to source mode and back.
+
+  **Expected:**
+
+  Mask is still visible and in the right place.
+
+  **Unexpected:**
+
+  Mask disappeared.