This package brings the TinyMCE Rich Text Editor (RTE) back to Umbraco CMS, (version 16+).
It also supports the use of TinyMCE Premium plugins with a valid subscription. Additional features include streamlined configuration for RTE Data Types in Umbraco and enhanced settings that support direct JSON-based configuration via .NET (appsettings.json).
Available via the Releases page
To install from NuGet, you can run the following command from the dotnet CLI:
dotnet add package TinyMCE.Umbraco
In addition, you can install packages via the Visual Studio NuGet Package Manager. This can be found in the Tools menu of Visual Studio.
If you are upgrading from Umbraco version 15, install this package before beginning the migration / upgrade process to version 16. If installed before the upgrade migration, this package will prevent the conversion to the TipTap editor and keep the TinyMCE RTE in place.
You can find the v13 version on NuGet as TinyMCE.Umbraco.Premium. Also, the documentation is available as a Readme on the v13/main branch here on Github.
To get started with the TinyMCE Umbraco property editor and use it with your projects, you will need to add some basic configuration and need to create a new Data Type for the TinyMCE Rich Text Editor. See the "Usage / Setup" Section below for more information.
The following options are available for configuration in the appsettings.json or through other environment level configuration settings (web.config, Azure environment variables, etc). This is using standard .NET configuration and you can learn more about .NET Configuration here.
The traditional Umbraco CMS TinyMCE Configuration settings continue to function as expected. The Umbraco Documentation has a good example of the configuration options and how they can be set here: Rich text editor settings.
{
"Umbraco": {
"CMS": {
"RichTextEditor": {
"Commands": "RichTextEditorCommand ARRAY"
"Plugins": ["STRING ARRAY"],
"CloudApiKey": "STRING",
"ValidElements": "STRING",
"InvalidElements": "STRING",
"CustomConfig": {JSON KEY/VALUES}
}
}
}
}The details on each configuration value are described below:
| Setting | Values | Default | Note |
|---|---|---|---|
| Commands | RichTextEditorCommand | None | A list of RichTextEditorCommand objects that contain and alias (STRING), name (STRING), and mode ("Insert", "Selection", or "All"). These commands are the buttons you find at the top of the editor, such as bold, italic, and so on. |
| Plugins | String array of TinyMCE plugins names to include | None | Add plugins to the list of available plugins in the TinyMCE Rich Text Editor DataType. See the Tiny Documentation for a list of plugins. |
| CloudApiKey | key string | None | The TinyMCE API Key found in your account. If applied, this will load the TinyMCE library from the Tiny Cloud URL unless the "tinyMceUrl" is specified. |
| ValidElements | string | See defaults | Specifies the list of HTML tags available to the TinyMCE Rich Text Editor. See the default list of ValidElements for more information. |
| InvalidElements | String | None | Specifies invalid HTML tags. These tags will not be allowed. |
| CustomConfig | JSON key/value pairs | {} | Simple key/value pairs for configuration of the TinyMCE Editor and Plugins. See the Tiny Documentation for the plugin configuration. This is here to support easy migration and upgrades. It is recommended to use the customConfig element below for a richer configuration experience. |
This package adds addition enhanced configuration options that carry over from the v13 TinyMCE Umbraco Premium package:
{
"TinyMceConfig": {
"tinyMceUrl": "STRING",
"tinyMceVersion": "STRING"
"apikey": "STRING",
"openAiApikey": "STRING",
"pluginsToExclude": ["STRING ARRAY"],
"customConfig": {JSON}
}
}The details on each configuration value are described below:
| Setting | Values | Default | Note |
|---|---|---|---|
| tinyMceUrl | url string | None | The URL location of the TinyMCE library. This allows for specific cloud URL access or self-hosted options. |
| tinyMceVersion | string | 6 | The version of the TinyMCE library. |
| apikey | key string | None | The TinyMCE API Key found in your account. If applied, this will load the TinyMCE library from the Tiny Cloud URL unless the "tinyMceUrl" is specified. |
| openAiApikey | key string | None | The ChatGPT API Key found in your account. This will enable a default implementation of the AI functionality using ChatGPT. |
| pluginsToExclude | String array of TinyMCE plugins names to exclude | [] | This excludes these plugins from being selected or used by the TinyMCE Rich Text Editor |
| customConfig | JSON TinyMCE Configuration | {} | See the Tiny Documentation for the plugin configuration. NOTE: this is JSON and can contain nested elements unlike the key/values in the RichTextEditor configuration above. |
The following open source TinyMCE plugins are available to add to the TinyMCE Umbraco RTE editor tools via the DataType configuration:
- Accordion (accordion)
- Code Sample (codesample)
- Emoticons (emoticons)
- Help for Editors (help)
- Insert Date/Time (insertdatetime)
- Search and Replace (searchreplace)
- Word Count (wordcount)
If the appsettings.json configuration has a valid Tiny apiKey set in configuration, then the following additional packages are available to the TinyMCe Umbraco Rich Text Editor:
- Accessibility Checker (a11ychecker)
- Advanced Typography (typography)
- Case Change (casechange)
- Checklist (checklist)
- Export (export)
- Footnotes (footnotes)
- Format Painter (formatpainter)
- Merge Tags (mergetags)
- Page Embed (pageembed)
- Permanent Pen (permanentpen)
- Spell Checker Pro (tinymcespellchecker)
- Table of Contents (tableofcontents)
Most of these have a Command / Toolbar associated with them and are disabled by default. To enable them, go to the Data Type in the Settings section of Umbraco to edit the toolbars available.
This package can be used to access some of the additional TinyMCE packages that may require more configuration to be used effectively.
In addition to the packages listed above, below are the additions TinyMCE Packages that are available via the TinyMCE Rich Text Editor:
- Advanced Code Editor (advcode)
- Advanced Table Editor (advtable)
- Advanced Templates (advtemplate)
- AI Assistant Shortcuts (ai)
- Enhanced Media Embed (mediaembed)
- Link Checker (linkchecker)
- PowerPaste (powerpaste)
- Spelling Autocorrect (autocorrect)
In order to use the TinyMCE Rich Text Editor, you will need to create at least one Umbraco Data Type that uses this property editor. Learn more about Umbraco Data Types and how to create them in the Umbraco Documentation here.
The TinyMCE Rich Text property editor adds a few new configuration options (from the v15 Umbraco TinyMCE Property Editor) for each Data Type that you create:
- Plugin Selection: Similar to the Toolbar items, you can select which plugins are enabled / available for this Data Type via the back-office UI.
- CustomConfig: Each Data Type that implements this editor has its own TinyMCE Configuration JSON that can be used for a custom configuration specific to this Data Type.
Both of these Data Type configuration options are managed via the Data Type editing interface in the back-office of Umbraco.
If you would like to extend the TinyMCE for Umbraco CMS package, there is an npm package avaliable to allow extentions and customization. It can be installed for development by running this on the command line:
npm install --save-dev @tiny-mce-umbraco/backoffice
Creating an extension to this package aligns with how Umbraco CMS allowed custom package in version 15.
The main difference is that the imports need to be from the @tiny-mce-umbraco/backoffice package reference like so:
import { UmbTinyMcePluginBase } from '@tiny-mce-umbraco/backoffice/core';
import type { TinyMcePluginArguments } from '@tiny-mce-umbraco/backoffice/core';
import type { Editor } from '@tiny-mce-umbraco/backoffice/external/tinymce';
If you have questions about TinyMCE plugins, please contact TinyMCE Support directly.
If something specific to the Property Editors in this package or the Configuration isn't working as you would expect, please submit a question via the GitHub Issues for this project. We will do our best to monitor and respond, but please be patient with us.
In addition, you may find that the community is very helpful and you can ask questions of them on the Umbraco Forums or the Umbraco Discord Server.
Contributions to this package are most welcome! Please read the contributing guidelines.
Copyright © ProWorks Corporation.
All source code is licensed under the MIT License.
The initial source code has been derived from Umbraco CMS, originally licensed under the MIT License.
Thanks to TinyMCE and Umbraco for their support during the package development.
Special thanks to Lee Kelleher and Jacob Overgaard for their contributions, help getting started, and for giving valuable feedback along the way.
Also thanks to the ProWorks team for their encouragement, support, and contributions.