Skip to content

Commit d6c410c

Browse files
kemister85kemister85
committed
DOC-3202: add migration guide outline initial.
1 parent 2acbde5 commit d6c410c

File tree

2 files changed

+293
-6
lines changed

2 files changed

+293
-6
lines changed

‎modules/ROOT/pages/migration-from-4x.adoc‎

Lines changed: 145 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,149 @@
1-
= Migrating from {productname} 4 to {productname} 7
1+
= Migrating from {productname} 4 to {productname} {release-version}
22
:navtitle: Migrating from TinyMCE 4
3-
:description: Guidance for migrating from TinyMCE 4 to TinyMCE 7
3+
:description: Guidance for migrating from TinyMCE 4 to TinyMCE {release-version}
44
:keywords: migration, considerations, premigration, pre-migration
55
:release-version: 7.0
66

7-
// Todo
7+
8+
== Overview
9+
10+
{productname} has evolved significantly from version 4 to version {release-version}, introducing major architectural changes, modern UI improvements, enhanced performance, and better security. This guide outlines the critical breaking changes, recommended migration action steps, and top-level configuration adjustments required to upgrade from {productname} v4 to v{release-version}.
11+
12+
== Key Changes
13+
14+
=== UI Themes and Skins
15+
16+
* **Removed**: modern, lightgray, and mobile themes/skins.
17+
* **New**: silver theme with oxide skin (supports light and dark variants). see xref:customize-ui.adoc#themes[customize-ui].
18+
* **Impact**: Custom v4 skins/themes are incompatible with v{release-version} and must be rewritten using the oxide skin structure.
19+
20+
.Example:
21+
[source,js]
22+
----
23+
tinymce.init({
24+
selector: "textarea",
25+
skin: "oxide-dark",
26+
content_css: "dark",
27+
});
28+
----
29+
30+
=== Plugin Ecosystem
31+
32+
// The contextmenu plugin was absorbed into core, the options still works, see https://www.tiny.cloud/docs/tinymce/latest/contextmenu/. not sure why this is mentioned as removed.
33+
* **Removed**: `colorpicker`, `contextmenu`, `imagetools`, `legacyoutput`, `bbcode`, `fullpage`, `template`, `print`, `spellchecker`, and `tabfocus` plugins.
34+
* **Core Integrations**: Many plugins are now part of the core (e.g., `paste`, `hr`, `noneditable`, `table`).
35+
* **Premium Only**: Plugins like `spellchecker`, `tableofcontents`, `mediaembed` are now premium.
36+
37+
Plugin Migration Examples:
38+
39+
* **contextmenu** (Removed in v5):
40+
** Replace with browser-native context menus or custom menu logic.
41+
** Consider using link:https://www.tiny.cloud/docs/tinymce/latest/apis/tinymce.editor.ui.registry/#addContextMenu[editor.ui.registry.addContextMenu] for custom right-click actions.
42+
* **bbcode** (Removed in v6):
43+
** Replace with custom parsing or server-side processing if needed.
44+
* **fullpage** (Removed in v6):
45+
** No direct replacement. Use custom templates or server-side processing for full HTML documents.
46+
* **template** (Removed in v{release-version}):
47+
** Use premium xref:advanced-templates.adoc[advtemplate] or implement custom modal dialogs for templating.
48+
* **textcolor** (Removed in v6):
49+
** Use `forecolor` and `backcolor` buttons instead.
50+
51+
.Example:
52+
[source,js]
53+
----
54+
tinymce.init({
55+
selector: "textarea",
56+
toolbar: "undo redo | forecolor backcolor | bold italic | alignleft aligncenter alignright alignjustify",
57+
plugins: ["lists link image table code"],
58+
});
59+
----
60+
61+
=== Content Structure
62+
63+
* **Removed**: `forced_root_block: false`.
64+
** **Requirement**: All content must be wrapped in block elements (e.g., <p>).
65+
66+
.Example:
67+
[source,js]
68+
----
69+
tinymce.init({
70+
selector: "textarea",
71+
forced_root_block: "p"
72+
});
73+
----
74+
75+
=== Configuration Changes
76+
77+
// multiple toolbars still work https://www.tiny.cloud/docs/tinymce/latest/toolbar-configuration-options/#toolbarn not sure why this is mentioned as decricated
78+
* **Deprecated**: toolbar1, toolbar2, theme, skin, mobile configurations.
79+
** **New Options**: Consolidate toolbar settings and use new options like xref:content-filtering.adoc#sandbox-iframes[sandbox iframes], xref:content-filtering.adoc#convert-unsafe-embeds[convert_unsafe_embeds], and xref:accessibility.adoc#highlight_on_focus[highlight_on_focus].
80+
81+
.Example:
82+
[source,js]
83+
----
84+
tinymce.init({
85+
selector: "textarea",
86+
toolbar: "undo redo | blocks | bold italic | alignleft aligncenter alignright alignjustify | outdent indent | removeformat",
87+
toolbar_mode: "floating",
88+
sandbox_iframes: true,
89+
convert_unsafe_embeds: true
90+
});
91+
----
92+
93+
=== Licensing Changes (GPL v2+ and Commercial)
94+
95+
* **Legacy License**: {productname} 4 was licensed under LGPL 2.1.
96+
* **New License**: {productname} {release-version} is licensed under GPL v2+ or a commercial license.
97+
* **Impact**: The xref:license-key.adoc[License key] option is required as part of your editor configuration if self-hosting {productname}.
98+
99+
.Example:
100+
[source,js]
101+
----
102+
tinymce.init({
103+
selector: "textarea",
104+
license_key: "your-license-key"
105+
});
106+
----
107+
108+
== Migration Steps
109+
110+
. **Backup and Prepare**: Ensure comprehensive backups before upgrading.
111+
. **Update Core Initialization**:
112+
.. Remove `theme`, `skin`, and `forced_root_block: false` options.
113+
.. Consolidate toolbars.
114+
.. Review new v{release-version} defaults for security settings.
115+
. **Plugin Migration**:
116+
.. Remove deprecated plugins from your configuration.
117+
.. Update renamed plugins (e.g., `spellchecker` → `tinymcespellchecker`).
118+
.. Verify premium plugins for compatibility.
119+
. **Custom Code Updates**:
120+
.. Rewrite custom plugins using the `editor.ui.registry.*` API. see link:https://www.tiny.cloud/docs/tinymce/latest/apis/tinymce.editor.ui.registry/[editor.ui.registry].
121+
.. Replace v4 API methods like `editor.addButton`, `editor.addMenuItem`, `editor.windowManager.open`.
122+
.. Update media embed handling (`media_url_resolver` API changes). see xref:media.adoc#media_url_resolver[media_url_resolver].
123+
. **CSS Updates**:
124+
.. Remove `.mce-*` classes and use `.tox-*` classes.
125+
.. Review custom skins and stylesheets for compatibility with Oxide.
126+
. **Testing and Deployment**:
127+
.. Thoroughly test your updated configuration before production deployment.
128+
.. Validate media, iframe, and content security settings.
129+
130+
== Additional Resources
131+
132+
* link:https://www.tiny.cloud/docs/tinymce/latest/[{productname} {release-version} Documentation]
133+
* xref:license-key.adoc[License Key Setup]
134+
* link:https://community.tiny.cloud/[Community Forum]
135+
* link:https://github.com/tinymce/tinymce/issues[GitHub Issues]
136+
137+
== Helpful Links
138+
139+
To make your upgrade smooth, check the following version-specific migration guides:
140+
141+
* link:https://www.tiny.cloud/docs/tinymce/5/migration-from-4x/[Migrating from {productname} 4 to {productname} 5]
142+
* link:https://www.tiny.cloud/docs/tinymce/6/migration-from-5x/[Migrating from {productname} 5 to {productname} 6]
143+
* link:https://www.tiny.cloud/docs/tinymce/latest/migration-from-6x/[Migrating from {productname} 6 to {productname} {release-version}]
144+
145+
These include deeper configuration notes, plugin replacements, and examples.
146+
147+
== Next Steps
148+
149+
Ensure you follow the migration steps carefully to avoid common issues like missing plugins, broken UI, and unexpected formatting changes. Consider running your updated editor in a staging environment for a complete verification before final deployment.

‎modules/ROOT/pages/migration-from-5x.adoc‎

Lines changed: 148 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,152 @@
1-
= Migrating from {productname} 5 to {productname} 7
1+
= Migrating from {productname} 5 to {productname} {release-version}
22
:navtitle: Migrating from TinyMCE 5
3-
:description: Guidance for migrating from TinyMCE 5 to TinyMCE 7
3+
:description: Guidance for migrating from TinyMCE 5 to TinyMCE {release-version}
44
:keywords: migration, considerations, premigration, pre-migration
55
:release-version: 7.0
66

7-
// Todo
7+
== Overview
8+
9+
{productname} has evolved significantly from version 5 to version {release-version}, introducing architectural improvements, modern UI enhancements, stricter security defaults, and updated plugin structures. This guide outlines the critical breaking changes, recommended migration action steps, and top-level configuration adjustments required to upgrade from {productname} v5 to v{release-version}.
10+
11+
== Key Changes
12+
13+
=== UI Themes and Skins
14+
15+
* **Minor Adjustments**: Oxide-based skins from v5 remain mostly compatible but may require small CSS adjustments for v{release-version}.
16+
* **Impact**: Test custom skins visually, as minor DOM changes can affect layout and styling.
17+
* **Browser Support**: Internet Explorer 11 is no longer supported in v{release-version} (dropped in v6), requiring modern browsers.
18+
19+
.Example:
20+
[source,js]
21+
----
22+
tinymce.init({
23+
selector: "textarea",
24+
skin: "oxide-dark",
25+
content_css: "dark",
26+
});
27+
----
28+
29+
=== Plugin Ecosystem
30+
31+
// The contextmenu plugin was absorbed into core, the options still works, see https://www.tiny.cloud/docs/tinymce/latest/contextmenu/. not sure why this is mentioned as removed.
32+
* **Moved to Core**: `paste`, `hr`, `table`, `noneditable`, `nonbreaking`.
33+
* **Removed**: `imagetools`, `template`, `colorpicker`, `contextmenu`, `legacyoutput`.
34+
* **Premium Only**: `mediaembed`, `toc` (renamed to `tableofcontents`), `advtemplate`.
35+
36+
Plugin Migration Examples:
37+
38+
* **contextmenu** (Removed in v5):
39+
** Replace with browser-native context menus or custom menu logic.
40+
** Consider using link:https://www.tiny.cloud/docs/tinymce/latest/apis/tinymce.editor.ui.registry/#addContextMenu[editor.ui.registry.addContextMenu] for custom right-click actions.
41+
* **bbcode** (Removed in v6):
42+
** Replace with custom parsing or server-side processing if needed.
43+
* **fullpage** (Removed in v6):
44+
** No direct replacement. Use custom templates or server-side processing for full HTML documents.
45+
* **template** (Removed in v{release-version}):
46+
** Use premium xref:advanced-templates.adoc[advtemplate] or implement custom modal dialogs for templating.
47+
* **textcolor** (Removed in v6):
48+
** Use `forecolor` and `backcolor` buttons instead.
49+
50+
.Example:
51+
[source,js]
52+
----
53+
tinymce.init({
54+
selector: "textarea",
55+
toolbar: "undo redo | forecolor backcolor | bold italic | alignleft aligncenter alignright alignjustify",
56+
plugins: ["lists link image table code"],
57+
});
58+
----
59+
60+
=== Content Structure
61+
62+
* **Removed**: `forced_root_block: false`.
63+
** **Requirement**: All content must be wrapped in block elements (e.g., `<p>`).
64+
65+
.Example:
66+
[source,js]
67+
----
68+
tinymce.init({
69+
selector: "textarea",
70+
forced_root_block: "p"
71+
});
72+
----
73+
74+
=== API and Initialization Changes
75+
76+
// multiple toolbars still work https://www.tiny.cloud/docs/tinymce/latest/toolbar-configuration-options/#toolbarn not sure why this is mentioned as decricated
77+
* **Deprecated**: toolbar1, toolbar2, theme, skin, mobile configurations.
78+
* **New Options**: Consolidate toolbar settings and use new options like xref:content-filtering.adoc#sandbox-iframes[sandbox iframes], xref:content-filtering.adoc#convert-unsafe-embeds[convert_unsafe_embeds], and xref:accessibility.adoc#highlight_on_focus[highlight_on_focus].
79+
* **UI API Updates**: Rewrite custom plugins using the `editor.ui.registry.*` API. Replace methods like `editor.addButton`, `editor.addMenuItem`, and `editor.windowManager.open`.
80+
* **Promise-based Methods**: `media_url_resolver` now returns a Promise, requiring async handling.
81+
* **Obsolete Options**: Remove `force_hex_color` and update `table_responsive_width` to `table_sizing_mode`.
82+
83+
.Example:
84+
[source,js]
85+
----
86+
tinymce.init({
87+
selector: "textarea",
88+
toolbar: "undo redo | blocks | bold italic | alignleft aligncenter alignright alignjustify | outdent indent | removeformat",
89+
toolbar_mode: "floating",
90+
sandbox_iframes: true,
91+
convert_unsafe_embeds: true,
92+
highlight_on_focus: true
93+
});
94+
----
95+
96+
=== Licensing Changes (GPL v2+ and Commercial)
97+
98+
* **Legacy License**: {productname} 5 was licensed under LGPL 2.1.
99+
* **New License**: {productname} {release-version} is licensed under GPL v2+ or a commercial license.
100+
* **Impact**: The xref:license-key.adoc[License key] option is required as part of your editor configuration if self-hosting {productname}.
101+
102+
.Example:
103+
[source,js]
104+
----
105+
tinymce.init({
106+
selector: "textarea",
107+
license_key: "your-license-key"
108+
});
109+
----
110+
111+
== Migration Steps
112+
113+
. **Backup and Prepare**: Ensure comprehensive backups before upgrading.
114+
. **Update Core Initialization**:
115+
.. Remove `theme`, `skin`, and `forced_root_block: false` options.
116+
.. Consolidate toolbars.
117+
.. Review new v{release-version} defaults for security settings.
118+
. **Plugin Migration**:
119+
.. Remove deprecated plugins from your configuration.
120+
.. Update renamed plugins (e.g., `spellchecker` → `tinymcespellchecker`).
121+
.. Verify premium plugins for compatibility.
122+
. **Custom Code Updates**:
123+
.. Rewrite custom plugins using the `editor.ui.registry.*` API.
124+
.. Replace v5 API methods like `editor.addButton`, `editor.addMenuItem`, `editor.windowManager.open`.
125+
.. Update media embed handling (`media_url_resolver` API changes). see xref:media.adoc#media_url_resolver[media_url_resolver].
126+
. **CSS Updates**:
127+
.. Remove `.mce-*` classes and use `.tox-*` classes.
128+
.. Review custom skins and stylesheets for compatibility with Oxide.
129+
. **Testing and Deployment**:
130+
.. Thoroughly test your updated configuration before production deployment.
131+
.. Validate media, iframe, and content security settings.
132+
133+
== Additional Resources
134+
135+
* link:https://www.tiny.cloud/docs/tinymce/latest/[{productname} {release-version} Documentation]
136+
* xref:license-key.adoc[License Key Setup]
137+
* link:https://community.tiny.cloud/[Community Forum]
138+
* link:https://github.com/tinymce/tinymce/issues[GitHub Issues]
139+
140+
== Helpful Links
141+
142+
To make your upgrade smooth, check the following version-specific migration guides:
143+
144+
* link:https://www.tiny.cloud/docs/tinymce/5/migration-from-4x/[Migrating from {productname} 4 to {productname} 5]
145+
* link:https://www.tiny.cloud/docs/tinymce/6/migration-from-5x/[Migrating from {productname} 5 to {productname} 6]
146+
* link:https://www.tiny.cloud/docs/tinymce/latest/migration-from-6x/[Migrating from {productname} 6 to {productname} {release-version}]
147+
148+
These include deeper configuration notes, plugin replacements, and examples.
149+
150+
== Next Steps
151+
152+
Ensure you follow the migration steps carefully to avoid common issues like missing plugins, broken UI, and unexpected formatting changes. Consider running your updated editor in a staging environment for a complete verification before final deployment.

0 commit comments

Comments
 (0)