Update Placeholder after initialization

docs/_snippets/features/update-placeholder.html

@@ -0,0 +1,4 @@
+<div id="snippet-update-placeholder">
+    <p></p>
+</div>
+<button id="update-placeholder-button">Update placeholder</button>

docs/_snippets/features/update-placeholder.js

@@ -0,0 +1,36 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals console, window, document, ClassicEditor */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-update-placeholder' ), {
+		cloudServices: CS_CONFIG,
+		toolbar: [
+			'undo', 'redo', '|', 'heading',
+			'|', 'bold', 'italic',
+			'|', 'link', 'uploadImage', 'insertTable', 'mediaEmbed',
+			'|', 'bulletedList', 'numberedList', 'outdent', 'indent'
+		],
+		ui: {
+			viewportOffset: {
+				top: window.getViewportTopOffsetConfig()
+			}
+		},
+		placeholder: 'Type some content here!'
+	} )
+	.then( editor => {
+		const button = document.getElementById( 'update-placeholder-button' );
+		window.editor = editor;
+
+		button.addEventListener( 'click', () => {
+			editor.editing.view.document.getRoot( 'main' ).placeholder = 'New placeholder';
+		} );
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

docs/features/editor-placeholder.md

@@ -108,6 +108,16 @@ The editor placeholder text is displayed using a CSS pseudo–element (`::before
 
 **Note**: The `.ck-placeholder` class is also used to display placeholders in other places, for instance, {@link features/images-captions image captions}. Make sure your custom styles apply to the right subset of placeholders.
 
+## Updating the placeholder
+
+The editor placeholder could be updated in runtime changing `placeholder` property in editing root. You can use it also in {@link installation/getting-started/predefined-builds#multi-root-editor `Multi-root editor`} and {@link installation/getting-started/predefined-builds#inline-editor `Inline editor`}.
+
+```js
+editor.editing.view.document.getRoot( 'main' ).placeholder = 'new placeholder'
+```
+
+{@snippet features/update-placeholder}
+
 ## Contribute
 
 The source code of the feature is available on GitHub at [https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core).

packages/ckeditor5-editor-balloon/src/ballooneditorui.ts

@@ -8,8 +8,7 @@
  */
 
 import {
-	type Editor,
-	type ElementApi
+	type Editor
 } from 'ckeditor5/src/core';
 
 import {
@@ -110,22 +109,23 @@ export default class BalloonEditorUI extends EditorUI {
 		const editor = this.editor;
 		const editingView = editor.editing.view;
 		const editingRoot = editingView.document.getRoot()!;
-		const sourceElement = ( editor as Editor & ElementApi ).sourceElement;
 
 		const placeholder = editor.config.get( 'placeholder' );
+		let placeholderText;
 
 		if ( placeholder ) {
-			const placeholderText = typeof placeholder === 'string' ? placeholder : placeholder[ editingRoot.rootName ];
-
-			if ( placeholderText ) {
-				enablePlaceholder( {
-					view: editingView,
-					element: editingRoot,
-					text: placeholderText,
-					isDirectHost: false,
-					keepOnFocus: true
-				} );
-			}
+			placeholderText = typeof placeholder === 'string' ? placeholder : placeholder[ editingRoot.rootName ];
 		}
+
+		if ( placeholderText ) {
+			editingRoot.placeholder = placeholderText;
+		}
+
+		enablePlaceholder( {
+			view: editingView,
+			element: editingRoot,
+			isDirectHost: false,
+			keepOnFocus: true
+		} );
 	}
 }

packages/ckeditor5-editor-classic/src/classiceditorui.ts

@@ -162,14 +162,15 @@ export default class ClassicEditorUI extends EditorUI {
 		}
 
 		if ( placeholderText ) {
-			enablePlaceholder( {
-				view: editingView,
-				element: editingRoot,
-				text: placeholderText,
-				isDirectHost: false,
-				keepOnFocus: true
-			} );
+			editingRoot.placeholder = placeholderText;
 		}
+
+		enablePlaceholder( {
+			view: editingView,
+			element: editingRoot,
+			isDirectHost: false,
+			keepOnFocus: true
+		} );
 	}
 
 	/**

packages/ckeditor5-editor-decoupled/src/decouplededitorui.ts

@@ -8,8 +8,7 @@
  */
 
 import {
-	type Editor,
-	type ElementApi
+	type Editor
 } from 'ckeditor5/src/core';
 
 import {
@@ -118,22 +117,23 @@ export default class DecoupledEditorUI extends EditorUI {
 		const editor = this.editor;
 		const editingView = editor.editing.view;
 		const editingRoot = editingView.document.getRoot()!;
-		const sourceElement = ( editor as Editor & ElementApi ).sourceElement;
 
 		const placeholder = editor.config.get( 'placeholder' );
+		let placeholderText;
 
 		if ( placeholder ) {
-			const placeholderText = typeof placeholder === 'string' ? placeholder : placeholder[ editingRoot.rootName ];
-
-			if ( placeholderText ) {
-				enablePlaceholder( {
-					view: editingView,
-					element: editingRoot,
-					text: placeholderText,
-					isDirectHost: false,
-					keepOnFocus: true
-				} );
-			}
+			placeholderText = typeof placeholder === 'string' ? placeholder : placeholder[ editingRoot.rootName ];
 		}
+
+		if ( placeholderText ) {
+			editingRoot.placeholder = placeholderText;
+		}
+
+		enablePlaceholder( {
+			view: editingView,
+			element: editingRoot,
+			isDirectHost: false,
+			keepOnFocus: true
+		} );
 	}
 }

packages/ckeditor5-editor-inline/src/inlineeditorui.ts

@@ -8,7 +8,6 @@
  */
 
 import {
-	type ElementApi,
 	type Editor
 } from 'ckeditor5/src/core';
 
@@ -153,22 +152,25 @@ export default class InlineEditorUI extends EditorUI {
 		const editor = this.editor;
 		const editingView = editor.editing.view;
 		const editingRoot = editingView.document.getRoot()!;
-		const sourceElement = ( editor as Editor & ElementApi ).sourceElement;
 
 		const placeholder = editor.config.get( 'placeholder' );
+		let placeholderText;
 
 		if ( placeholder ) {
-			const placeholderText = typeof placeholder === 'string' ? placeholder : placeholder[ editingRoot.rootName ];
-
-			if ( placeholderText ) {
-				enablePlaceholder( {
-					view: editingView,
-					element: editingRoot,
-					text: placeholderText,
-					isDirectHost: false,
-					keepOnFocus: true
-				} );
-			}
+			placeholderText = typeof placeholder === 'string' ? placeholder : placeholder[ editingRoot.rootName ];
+		}
+
+		if ( placeholderText ) {
+			editingRoot.placeholder = placeholderText;
+		}
+
+		if ( placeholderText ) {
+			enablePlaceholder( {
+				view: editingView,
+				element: editingRoot,
+				isDirectHost: false,
+				keepOnFocus: true
+			} );
 		}
 	}
 }

packages/ckeditor5-editor-multi-root/src/multirooteditorui.ts

@@ -204,17 +204,16 @@ export default class MultiRootEditorUI extends EditorUI {
 			}
 		}
 
-		if ( !placeholder ) {
-			return;
-		}
-
 		const editingView = this.editor.editing.view;
 		const editingRoot = editingView.document.getRoot( editable.name! )!;
 
+		if ( placeholder ) {
+			editingRoot.placeholder = placeholder;
+		}
+
 		enablePlaceholder( {
 			view: editingView,
 			element: editingRoot,
-			text: placeholder,
 			isDirectHost: false,
 			keepOnFocus: true
 		} );

packages/ckeditor5-engine/src/view/editableelement.ts

@@ -42,6 +42,15 @@ export default class EditableElement extends ObservableMixin( ContainerElement )
 	 */
 	declare public isFocused: boolean;
 
+	/**
+	 * Placeholder of editable element. Could be updated.
+	 *
+	 * editor.editing.view.document.getRoot( 'main' ).placeholder = 'New placeholder';
+	 *
+	 * @observable
+	 */
+	declare public placeholder?: string;
+
 	/**
 	 * Creates an editable element.
 	 *
@@ -62,6 +71,7 @@ export default class EditableElement extends ObservableMixin( ContainerElement )
 
 		this.set( 'isReadOnly', false );
 		this.set( 'isFocused', false );
+		this.set( 'placeholder', undefined );
 
 		this.bind( 'isReadOnly' ).to( document );
 

packages/ckeditor5-engine/src/view/placeholder.ts

@@ -11,6 +11,7 @@ import '../../theme/placeholder.css';
 
 import type Document from './document';
 import type DowncastWriter from './downcastwriter';
+import type EditableElement from './editableelement';
 import type Element from './element';
 import type View from './view';
 
@@ -30,17 +31,15 @@ const documentPlaceholders = new WeakMap<Document, Map<Element, PlaceholderConfi
  * @param options Configuration options of the placeholder.
  * @param options.view Editing view instance.
  * @param options.element Element that will gain a placeholder. See `options.isDirectHost` to learn more.
- * @param options.text Placeholder text.
  * @param options.isDirectHost If set `false`, the placeholder will not be enabled directly
  * in the passed `element` but in one of its children (selected automatically, i.e. a first empty child element).
  * Useful when attaching placeholders to elements that can host other elements (not just text), for instance,
  * editable root elements.
  * @param options.keepOnFocus If set `true`, the placeholder stay visible when the host element is focused.
  */
-export function enablePlaceholder( { view, element, text, isDirectHost = true, keepOnFocus = false }: {
+export function enablePlaceholder( { view, element, isDirectHost = true, keepOnFocus = false }: {
 	view: View;
-	element: Element;
-	text: string;
+	element: PlaceholderableElement | EditableElement;
 	isDirectHost?: boolean;
 	keepOnFocus?: boolean;
 } ): void {
@@ -60,16 +59,28 @@ export function enablePlaceholder( { view, element, text, isDirectHost = true, k
 		}, { priority: 'high' } );
 	}
 
-	// Store information about the element placeholder under its document.
-	documentPlaceholders.get( doc )!.set( element, {
-		text,
-		isDirectHost,
-		keepOnFocus,
-		hostElement: isDirectHost ? element : null
-	} );
+	if ( element.is( 'editableElement' ) ) {
+		element.on( 'change:placeholder', ( evtInfo, evt, text ) => {
+			setPlaceholder( text );
+		} );
+	}
+
+	if ( element.placeholder ) {
+		setPlaceholder( element.placeholder );
+	}
 
-	// Update the placeholders right away.
-	view.change( writer => updateDocumentPlaceholders( doc, writer ) );
+	function setPlaceholder( text: string ) {
+		// Store information about the element placeholder under its document.
+		documentPlaceholders.get( doc )!.set( element, {
+			text,
+			isDirectHost,
+			keepOnFocus,
+			hostElement: isDirectHost ? element : null
+		} );
+
+		// Update the placeholders right away.
+		view.change( writer => updateDocumentPlaceholders( doc, writer ) );
+	}
 }
 
 /**
@@ -297,3 +308,10 @@ interface PlaceholderConfig {
 	keepOnFocus: boolean;
 	hostElement: Element | null;
 }
+
+/**
+ * Element which could have placeholder.
+ */
+export type PlaceholderableElement = Element & {
+	placeholder?: string;
+};