New content
'); +---- + +To insert content at the current selection instead of replacing the entire editor content, use xref:apis/tinymce.editor.adoc#insertContent[insertContent()]. + +[[setcontent-arguments]] +=== Arguments for `+setContent()+` + +`+setContent()+` accepts an optional second argument, an object with the following properties. + +[cols="1,1,1,3",options="header"] +|=== +|Property |Type |Default value |Description +|`+no_events+` |`+Boolean+` |`+false+` |When `+true+`, the `+BeforeSetContent+` and `+SetContent+` events are not dispatched. +|`+no_selection+` |`+Boolean+` |`+false+` |When `+true+`, the caret is not moved to the start of the new content. +|=== + +NOTE: Editor features and plugins that respond to the `+SetContent+` event do not run for content set with `+no_events: true+`. For example, xref:content-appearance.adoc#visual[visual aids] are not applied to the new content, and xref:file-image-upload.adoc#automatic_uploads[automatic image uploads] are not started. + +==== Example: setting content without moving the caret + +[source,js] +---- +tinymce.activeEditor.setContent('New content
', { no_selection: true }); +---- + +[[adding-an-undo-level]] +=== Adding an undo level + +`+setContent()+` does not add an undo level, so the change is not recorded in the undo history. To allow users to undo the change, call xref:apis/tinymce.undomanager.adoc#add[undoManager.add()] after setting the content. + +[source,js] +---- +const editor = tinymce.activeEditor; +editor.setContent('New content
'); +editor.undoManager.add(); +---- + +[[changing-content-before-it-is-set]] +=== Changing content before it is set + +To change content before {productname} sets it, update the `+content+` property in a `+BeforeSetContent+` event handler. The updated content is still parsed, filtered, and sanitized before it is set. To cancel the change, call `+preventDefault()+` on the event. The `+SetContent+` event is still dispatched when the change is canceled. + +Changing the `+content+` property in a `+SetContent+` event handler has no effect, as the content has already been set. The `+content+` property of the `+SetContent+` event is deprecated. + +The `+BeforeSetContent+` event is also dispatched when content is inserted at the selection, and when undo and redo restore content. When content is inserted at the selection, the `+selection+` property of the event is `+true+`. Write the handler so that running it more than once on the same content does not change the result. + +==== Example: replacing a placeholder before content is set + +[source,js] +---- +tinymce.init({ + selector: 'textarea', // change this value according to your HTML + setup: (editor) => { + editor.on('BeforeSetContent', (e) => { + if (!e.selection) { + e.content = e.content.replace(/\{\{year\}\}/g, String(new Date().getFullYear())); + } + }); + } +}); +---- + +[[what-to-avoid]] +== What to avoid when getting or setting content + +* *Do not write HTML directly into the editor after it has loaded.* For example, do not set `+editor.getBody().innerHTML+`, the body of the editor's `+iframe+`, or the element used by an inline editor. Content written this way skips parsing, filtering, and sanitization, does not dispatch the `+BeforeSetContent+` or `+SetContent+` events, and does not add an undo level. Use `+editor.setContent()+` or `+editor.insertContent()+` instead. Setting HTML on the target element before the editor loads is supported. +* *Do not read HTML directly from the editor.* For example, do not read `+editor.getBody().innerHTML+`. The editor DOM contains editor-only markup, such as `+data-mce-bogus+` elements and editor-only classes. This markup can display incorrectly when the content is published, and can cause unexpected results when the content is loaded back into the editor. Use `+editor.getContent()+` instead. == HTML forms options diff --git a/modules/ROOT/pages/events.adoc b/modules/ROOT/pages/events.adoc index 17d7ea945b..9938c20aa6 100644 --- a/modules/ROOT/pages/events.adoc +++ b/modules/ROOT/pages/events.adoc @@ -195,8 +195,8 @@ The following events are provided by the {productname} editor. |AfterSetSelectionRange |`+{ range: Range, forward: boolean }+` |Fired after the selection range is set in the editor. |BeforeGetContent |`+{ format: string, source_view?: boolean, selection?: boolean, save?: boolean }+` |Fired before the content is serialized from the editor. |GetContent |`+{ content: string, format: string, source_view?: boolean, selection?: boolean, save?: boolean }+` |Fired after the content is serialized from the editor. -|BeforeSetContent |`+{ content: string, format?: string, paste?: boolean, selection?: boolean }+` |Fired before the content is parsed and rendered in the editor. -|SetContent |`+{ content: string, format?: string, paste?: boolean, selection?: boolean }+` |Fired after the content is parsed and rendered in the editor. NOTE: The `+content+` property has been deprecated and will be removed in the next major release. +|BeforeSetContent |`+{ content: string, format?: string, paste?: boolean, selection?: boolean }+` |Fired before the content is parsed and rendered in the editor. Event handlers can change the `+content+` property, or call `+preventDefault()+` to cancel the change. For details, see: xref:editor-save-and-submit.adoc#changing-content-before-it-is-set[Changing content before it is set]. +|SetContent |`+{ content: string, format?: string, paste?: boolean, selection?: boolean }+` |Fired after the content is parsed and rendered in the editor. NOTE: The `+content+` property has been deprecated and will be removed in the next major release. To change content before it is set, use the `+BeforeSetContent+` event. |LoadContent |N/A |Fired after the initial content has loaded into the editor. |PreviewFormats |N/A |Fired before a formats CSS is generated when the format is being previewed in the editor. |AfterPreviewFormats |N/A |Fired after a formats CSS is generated when the format is being previewed in the editor. diff --git a/modules/ROOT/pages/initial-configuration.adoc b/modules/ROOT/pages/initial-configuration.adoc index 71bb8c1437..c91d4da20d 100644 --- a/modules/ROOT/pages/initial-configuration.adoc +++ b/modules/ROOT/pages/initial-configuration.adoc @@ -24,9 +24,9 @@ Options for setting the size of the editor and controling editor resizing. | [.lead] -xref:editor-save-and-submit.adoc[Editor save and submit options] +xref:editor-save-and-submit.adoc[Getting, setting, and saving editor content] -Editor options related to saving or submitting editor content. +How to get and set editor content with the `+getContent()+` and `+setContent()+` APIs, and options for saving or submitting editor content. | [.lead] diff --git a/modules/ROOT/partials/install/save-content.adoc b/modules/ROOT/partials/install/save-content.adoc index d6da4cf555..1be9dba7a6 100644 --- a/modules/ROOT/partials/install/save-content.adoc +++ b/modules/ROOT/partials/install/save-content.adoc @@ -6,7 +6,7 @@ If you use a form handler, once the `+